---
createdAt: 2025-04-18
updatedAt: 2026-09-27
priority: 9
title: "Analog i18n - Complete guide to translate your app"
description: "Set up Intlayer in Analog: typed per-component content, locale detection and switching, and localized routes for Angular with Vite."
keywords:
- Internationalization
- Documentation
- Intlayer
- Analog
- Angular
- JavaScript
slugs:
- doc
- environment
- analog
applicationTemplate: https://github.com/aymericzip/intlayer-analog-template
applicationShowcase: https://intlayer-analog-template.vercel.app
history:
- version: 8.9.0
date: 2026-05-04
changes: "Update Solid useIntlayer API usage to direct property access"
- version: 8.0.4
date: 2026-01-26
changes: "Initial history"
author: aymericzip
---
# Translate your Analog (Angular) app using Intlayer
## Table of Contents
## Why Intlayer over alternatives?
Compared to main solutions like `ngx-translate` or `angular-l10n`, Intlayer is a solution that comes with integrated optimizations such as:
Intlayer is optimized to work perfectly with Analog by offering **multilingual routing**, **SSR support**, and all the features needed for scaling internationalization (i18n).
Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps **reduce your bundle and page sizes by up to 50%**.
Scoping your application's content **facilitates maintenance** for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is **fully typed** to ensure your content's accuracy.
Co-locating content **reduces the context needed** by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a **CLI** to test for missing translations,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, and **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, to make the developer experience (DX) even smoother for AI agents.
- [LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)
- [MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)
- [agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)
Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a **compiler** to automate content extraction, as well as a [web platform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) to help **translate in the background**.
- [web platform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.
More than just an i18n solution, Intlayer provides an **self-hosted [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** and a **[full CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** to help you manage your multilingual content in **real-time**, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.
- [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)
- [full CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
## Step-by-Step Guide to Set Up Intlayer in an Analog Application
See [Application Template](https://github.com/aymericzip/intlayer-analog-template) on GitHub.
Install the necessary packages using npm:
```bash packageManager="npm"
npx intlayer init --interactive
```
```bash packageManager="pnpm"
pnpm dlx intlayer init --interactive
```
```bash packageManager="yarn"
yarn dlx intlayer init --interactive
```
```bash packageManager="bun"
bunx intlayer init --interactive
```
> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
> This command will detect your environment and install the required packages. For example:
```bash packageManager="npm"
npm install intlayer angular-intlayer vite-intlayer
```
```bash packageManager="pnpm"
pnpm add intlayer angular-intlayer vite-intlayer
```
```bash packageManager="yarn"
yarn add intlayer angular-intlayer vite-intlayer
```
```bash packageManager="bun"
bun add intlayer angular-intlayer vite-intlayer
```
- **intlayer**
The core package that provides internationalization tools for configuration management, translation, [content declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md), transpilation, and [CLI commands](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
- **angular-intlayer**
The package that integrates Intlayer with Angular application. It provides context providers and hooks for Angular internationalization.
- **vite-intlayer**
The package that integrates Intlayer with Vite. It provides a plugin to handle content declaration files and sets up aliases for optimal performance.
### Architecture
In this architecture, `angular-intlayer` provides `provideIntlayer()`, registered in `src/app/app.config.ts` so that every component and file-based page can read its content through the `useIntlayer` signal. Analog builds on Vite, so the `intlayer()` plugin of `vite-intlayer` is added next to `analog()` in `vite.config.ts` to watch and rebuild your content declarations and to run the locale proxy. Content declarations are placed alongside components and pages in `src/app/`.
```bash
.
├── src
│ ├── app
│ │ ├── pages
│ │ │ └── index.page.ts # File-based route using useIntlayer
│ │ ├── app.config.ts # Application config with provideIntlayer()
│ │ ├── app.content.ts # App content declaration
│ │ └── locale-switcher.component.ts
│ └── main.ts
├── intlayer.config.ts
├── package.json
├── tsconfig.json
└── vite.config.ts # analog() and intlayer() Vite plugins
```
### Configuration
Create a config file to configure the languages of your application:
```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
import { Locales, type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
locales: [
Locales.ENGLISH,
Locales.FRENCH,
Locales.SPANISH,
// Your other locales
],
defaultLocale: Locales.ENGLISH,
},
};
export default config;
```
> Through this configuration file, you can set up localized URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
- [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
To integrate Intlayer with Analog, you need to use the `vite-intlayer` plugin.
Modify your `vite.config.ts` file:
```typescript fileName="vite.config.ts"
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";
import analog from "@analogjs/platform";
// https://vitejs.dev/config/
export default defineConfig(() => ({
plugins: [
analog(),
intlayer({
proxy: {
ignore: (req) => req.url?.startsWith("/api"),
},
}),
],
}));
```
> The `intlayer()` plugin configures Vite with Intlayer. It handles content declaration files and sets up aliases for optimal performance.
Create and manage your content declarations to store translations:
```tsx fileName="src/app/app.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"]
import { t, type Dictionary } from "intlayer";
const appContent = {
key: "app",
content: {
title: t({
en: "Hello",
fr: "Bonjour",
es: "Hola",
}),
congratulations: t({
en: "Congratulations! Your app is running. 🎉",
fr: "Félicitations! Votre application est en cours d'exécution. 🎉",
es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",
}),
},
} satisfies Dictionary;
export default appContent;
```
> Your content declarations can be defined anywhere in your application as soon they are included into the `contentDir` directory (by default, `./src`). And match the content declaration file extension (by default, `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`).
> For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
- [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md)
To utilize Intlayer's internationalization features throughout your Analog application, you need to provide Intlayer in your application configuration.
```typescript fileName="src/app/app.config.ts"
import { ApplicationConfig } from "@angular/core";
import { provideIntlayer } from "angular-intlayer";
export const appConfig: ApplicationConfig = {
providers: [
provideIntlayer(), // Add the Intlayer provider here
],
};
```
Then, you can use the `useIntlayer` function within any component.
```typescript fileName="src/app/pages/index.page.ts"
import { Component } from "@angular/core";
import { useIntlayer } from "angular-intlayer";
@Component({
selector: "app-home",
standalone: true,
template: `
{{ content().title }}
{{ content().congratulations }}
`,
})
export default class HomeComponent {
content = useIntlayer("app");
}
```
Intlayer content is returned as a `Signal`, so you access the values by calling the signal: `content().title`.
To change the language of your content, you can use the `setLocale` function provided by the `useLocale` function. This allows you to set the locale of the application and update the content accordingly.
Create a component to switch between languages:
```typescript fileName="src/app/locale-switcher.component.ts"
import { Component } from "@angular/core";
import { CommonModule } from "@angular/common";
import { useLocale } from "angular-intlayer";
@Component({
selector: "app-locale-switcher",
standalone: true,
imports: [CommonModule],
template: `
`,
})
export class LocaleSwitcherComponent {
localeCtx = useLocale();
locale = this.localeCtx.locale;
availableLocales = this.localeCtx.availableLocales;
setLocale = this.localeCtx.setLocale;
}
```
Then, use this component in your pages:
```typescript fileName="src/app/pages/index.page.ts"
import { Component } from "@angular/core";
import { useIntlayer } from "angular-intlayer";
import { LocaleSwitcherComponent } from "../locale-switcher.component";
@Component({
selector: "app-home",
standalone: true,
imports: [LocaleSwitcherComponent],
template: `
{{ content().title }}
{{ content().congratulations }}
`,
})
export default class HomeComponent {
content = useIntlayer("app");
}
```
### Configure TypeScript
Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.


Ensure your TypeScript configuration includes the autogenerated types.
```json5 fileName="tsconfig.json"
{
// ... Your existing TypeScript configurations
"include": [
// ... Your existing TypeScript configurations
".intlayer/**/*.ts", // Include the auto-generated types
],
}
```
### Git Configuration
It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
To do this, you can add the following instructions to your `.gitignore` file:
```bash
# Ignore the files generated by Intlayer
.intlayer
```
### VS Code Extension
To improve your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
- [Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
This extension provides:
- **Autocompletion** for translation keys.
- **Real-time error detection** for missing translations.
- **Inline previews** of translated content.
- **Quick actions** to easily create and update translations.
For more details on how to use the extension, refer to the [Intlayer VS Code Extension documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/vs_code_extension.md).
- [Intlayer VS Code Extension documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/vs_code_extension.md)
### Go Further
To go further, you can implement the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md) or externalize your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md).
- [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)
- [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
## Frequently Asked Questions
Analog is an Angular meta framework built on Vite, so it inherits the Angular options and adds the Vite ones:
- **`@angular/localize`**: XLIFF extraction with one compiled build per locale, which fits poorly with a file based router and server rendering.
- **`ngx-translate`** and **`Transloco`**: runtime JSON catalogs through a service, with no integration with Analog's routing or server side rendering.
- **`Intlayer`**: the most advanced solution. Content declared anywhere in your codebase ([next to each component or centralized](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md)) and compiled by the Vite plugin at build time, fully typed, with runtime locale switching, AI translation, a visual editor and a CMS.
See [why Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/interest_of_intlayer.md) and the [Angular guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_angular_21.md) for the Angular specific APIs.
- [why Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/interest_of_intlayer.md)
- [Angular guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_angular_21.md)
Much less than a namespace based setup, because a page never downloads a catalog it does not render. Server rendered markup resolves its content on the server, and the build time compiler replaces `useIntlayer` calls with the exact dictionary entries a component uses, so unused keys and unused languages are dropped, and [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md) split the rest per locale. Measured against the usual alternatives, Intlayer reduces bundle and page size by up to 50%. See [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md) and the [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md).
- [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
- [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md)
- [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
Largely. Follow the [ngx-translate migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/ngx-translate.md) or the [Transloco migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/transloco.md) to move the content over. You can also migrate gradually: the [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md) keeps your existing JSON catalogs as the source of truth and generates Intlayer dictionaries from them, so both layers stay in sync while you move templates across one at a time.
- [ngx-translate migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/ngx-translate.md)
- [Transloco migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/transloco.md)
- [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md)
Yes. The [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md) keeps your `/messages/{locale}/{namespace}.json` files as the source of truth and generates Intlayer dictionaries from them, in both directions. A [sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-po.md) does the same for gettext catalogs, and [per locale files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/per_locale_file.md) let you split content by language instead of grouping locales in one file.
- [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md)
- [sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-po.md)
- [per locale files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/per_locale_file.md)
No. Run `npx intlayer extract` and Intlayer reads your source files, pulls the user facing strings out and writes a `.content` file next to each one, so you review a diff instead of copying strings into a catalog one at a time. See the [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/extract.md).
- [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/extract.md)
For a fully automated pipeline, the [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compiler.md) does the same at build time on JSX, TSX, Vue and Svelte source, generating the dictionaries on every change so there are no keys to maintain by hand. It works by static analysis, so strings that only exist at runtime stay out of reach, and it needs a few annotations to tell user facing text apart from application logic.
- [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compiler.md)
Five pieces, all optional:
- **[VS Code extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/vs_code_extension.md)**: jump from a `useIntlayer` key to the content file that declares it, extract content from a component, and run build, fill, test, push and pull from the command palette or a dedicated Intlayer tab.
- **[LSP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**: the same awareness in any editor that speaks LSP, with go to definition, find all references, hover previews of a translated value, autocompletion of keys and fields, and a warning when a key is not declared anywhere. It also resolves `i18next`, `react-i18next`, `next-intl` and `use-intl` calls, which helps while you migrate.
- **[MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**: exposes the Intlayer documentation and CLI to Cursor, VS Code, Claude Desktop, Claude Code and ChatGPT, so an assistant answers from current docs instead of guessing, and can run commands such as `intlayer fill` itself.
- **[Agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**: focused skills such as `intlayer-config`, `intlayer-cli` and `intlayer-content`, plus one per framework, that teach an agent your routing setup and the content node types.
- **[ESLint plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/eslint.md)**: `no-raw-text` flags hardcoded strings, with further rules for static dictionary keys and unused content.
No. That is the `@angular/localize` model, where each locale is compiled into its own bundle and deployed separately. With Intlayer a single build serves every declared locale, and the active language is resolved at runtime from the URL, a cookie or the `Accept-Language` header.
Yes. Content is exposed through signals, so a template re-renders when the locale changes without a page reload, and the provider is registered like any other standalone provider.
Step 6 covers it. `useLocale` exposes the active locale, the declared locales and a setter that persists the choice, and `getLocalizedUrl` rewrites the current path so the user stays on the same route after switching.
Yes. The `intlayer()` Vite plugin compiles your content and watches it in development, and the locale is resolved on the server so the first HTML response is already in the right language. Prerendered routes resolve their content at build time.
Run `npx intlayer fill`. It fills missing translations with the LLM of your choice, using your own provider and API key, and `--git-diff` limits the run to the content changed on the branch. See the [fill command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/fill.md) and [CI/CD integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/CI_CD.md).
- [fill command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/fill.md)
- [CI/CD integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/CI_CD.md)
Yes: [plural forms](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/plurial.md), [gender based content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/gender.md), conditions, [insertions](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/insertion.md), [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/markdown.md) and [formatters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/formatters.md) for numbers, dates and currencies.
- [plural forms](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/plurial.md)
- [gender based content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/gender.md)
- [insertions](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/insertion.md)
- [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/markdown.md)
- [formatters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/formatters.md)
Run `npx intlayer test` in CI. It fails the build when a declared locale is missing content. The [VS Code extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/vs_code_extension.md) reports the same errors while you type. See [testing your content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/testing.md).
- [VS Code extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/vs_code_extension.md)
- [testing your content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/testing.md)
Through the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md), which runs on your own infrastructure and lets anyone edit text in place on the running app, or the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md), which externalizes content so it can change without a deployment.
- [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)
- [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)
Yes, under the Apache 2.0 license, commercial use included. The hosted CMS is an optional paid service that can also be [self hosted](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/self_hosting.md).
- [self hosted](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/self_hosting.md)