@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/en-GB/cli/doc-review.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-11-22
+updatedAt: 2026-06-17
 title: Review Document
 description: Learn how to review documentation files for quality, consistency, and completeness across different locales.
 keywords:
@@ -15,6 +15,10 @@ slugs:
   - concept
   - cli
   - doc-review
+history:
+  - version: 9.0.0
+    date: 2026-06-17
+    changes: "Add --log option"
 author: aymericzip
 ---
 
@@ -55,8 +59,110 @@ For most use cases,
 
 ## Arguments:
 
-The `doc review` command accepts the same arguments as `doc translate`, allowing you to review specific documentation files and apply quality checks.
+**File list options:**
 
-If you have activated one of the git options, the command will only review the parts of the files that are being changed. The script will process by chunking the file and reviewing each chunk. If there are no changes in the chunk, the script will skip it to speed up the review process and limit the AI Provider API cost.
+- **`--doc-pattern [docPattern...]`**: Glob patterns to match documentation files to review.
 
-For a complete list of arguments, see the [Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-translate.md) command documentation.
+  > Example: `npx intlayer doc review --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**: Glob patterns to exclude from review.
+
+  > Example: `npx intlayer doc review --excluded-glob-pattern "docs/internal/**"`
+
+- **`--skip-if-modified-before [skipIfModifiedBefore]`**: Skip the file if it has been modified before the specified time.
+  - Can be an absolute time such as "2025-12-05" (string or Date)
+  - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
+  - This option checks the update time of the file using the `fs.stat` method. Therefore, it could be affected by Git or other tools that modify the file.
+
+  > Example: `npx intlayer doc review --skip-if-modified-before "2025-12-05"`
+
+- **`--skip-if-modified-after [skipIfModifiedAfter]`**: Skip the file if it has been modified within the specified time.
+  - Can be an absolute time such as "2025-12-05" (string or Date)
+  - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
+  - This option checks the update time of the file using the `fs.stat` method. Therefore, it could be affected by Git or other tools that modify the file.
+
+  > Example: `npx intlayer doc review --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**: Skip the file if it already exists.
+
+  > Example: `npx intlayer doc review --skip-if-exists`
+
+**Review mode options:**
+
+- **`--log`**: Log-only mode. Do not translate with AI; instead log the blocks that need attention (with line numbers and content) for the base and target locales, to help another agent generate the translations.
+
+  > Example: `npx intlayer doc review --log`
+
+**Entry output options:**
+
+- **`--locales [locales...]`**: Target locales to review documentation for.
+
+  > Example: `npx intlayer doc review --locales fr es de`
+
+- **`--base-locale [baseLocale]`**: Source locale (base document) to compare with.
+
+  > Example: `npx intlayer doc review --base-locale en`
+
+**File processing options:**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: Number of files to process simultaneously for review.
+
+  > Example: `npx intlayer doc review --nb-simultaneous-file-processed 5`
+
+**AI options:**
+
+- **`--model [model]`**: The AI model to use for review (e.g., `gpt-3.5-turbo`).
+- **`--provider [provider]`**: The AI provider to use for review.
+- **`--temperature [temperature]`**: Temperature setting for the AI model.
+- **`--api-key [apiKey]`**: Provide your own API key for the AI service.
+- **`--application-context [applicationContext]`**: Provide additional context for the AI review.
+- **`--data-serialization [dataSerialization]`**: The data serialization format to use for the AI features of Intlayer. Options: `json` (standard, reliable), `toon` (fewer tokens, less consistent).
+- **`--custom-prompt [prompt]`**: Customise the base prompt used for review. (Note: For most use cases, the `--custom-instructions` option is recommended instead.)
+
+  > Example: `npx intlayer doc review --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`
+
+**Environment variables options:**
+
+- **`--env`**: Specify the environment (e.g., `development`, `production`).
+- **`--env-file [envFile]`**: Provide a custom environment file to load variables from.
+- **`--base-dir`**: Specify the base directory for the project.
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer doc review --base-dir ./docs --env-file .env.production.local`
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (defaults to true when using CLI)
+
+  > Example: `npx intlayer doc review --verbose`
+
+**Custom instructions options:**
+
+- **`--custom-instructions [customInstructions]`**: Custom instructions added to the prompt. Useful for applying specific rules regarding formatting, URL translation, etc.
+
+  > Example: `npx intlayer doc review --custom-instructions "Avoid translating URLs, and keep the markdown format"`
+
+  > Example: `npx intlayer doc review --custom-instructions "$(cat ./instructions.md)"`
+
+**Git options:**
+
+- **`--git-diff`**: Only run on files that include changes from base (default `origin/main`) to current branch (default: `HEAD`).
+- **`--git-diff-base`**: Specify the base reference for git diff (default `origin/main`).
+- **`--git-diff-current`**: Specify the current reference for git diff (default: `HEAD`).
+- **`--uncommitted`**: Include uncommitted changes.
+- **`--unpushed`**: Include unpushed changes.
+- **`--untracked`**: Include untracked files.
+
+  > Example: `npx intlayer doc review --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Example: `npx intlayer doc review --uncommitted --unpushed --untracked`
+
+> Note that the output file path will be determined by replacing the following patterns:
+>
+> - `/{{baseLocale}}/` with `/{{locale}}/` (Unix)
+> - `\{{baseLocale}}\` with `\{{locale}}\` (Windows)
+> - `_{{baseLocale}}.` with `_{{locale}}.`
+> - `{{baseLocale}}_` with `{{locale}}_`
+> - `.{{baseLocaleName}}.` with `.{{localeName}}.`
+>
+> If the pattern is not found, the output file will add `.{{locale}}` to the file extension. For example, `./my/file.md` will be reviewed and updated to `./my/file.fr.md` for the French locale.

package/docs/en-GB/cli/fill.md

@@ -47,6 +47,14 @@ Key Points:
 - Preserves existing translations by not overwriting them.
 - Processes files, chunks, and locales in parallel using a queue system to increase speed.
 
+## Key Points:
+
+- Splits large JSON files into chunks to stay within the AI model's context window limits.
+- Retries translation if the output format is incorrect.
+- Incorporates application and file-specific context for improved translation accuracy.
+- Preserves existing translations by not overwriting them.
+- Processes files, chunks, and locales in parallel using a queue system to increase speed.
+
 ## Aliases:
 
 - `npx intlayer dictionaries fill`

package/docs/en-GB/cli/index.md

@@ -17,7 +17,7 @@ slugs:
   - concept
   - cli
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Added scan command"
   - version: 8.6.4

package/docs/en-GB/cli/login.md

@@ -80,42 +80,6 @@ bun x intlayer login --cms-url https://intlayer.org
 
 You can also use common configuration options:
 
-- `--env-file <path>`: Path to the environment file
-- `-e, --env <env>`: Execution environment
-- `--base-dir <dir>`: Base directory of the project
-- `--verbose`: Enable detailed output (default: true)
-- `--prefix <prefix>`: Prefix for logs
-
-## How It Works
-
-1. **Local server start**: The command starts a local HTTP server on a random port to receive credentials from the CMS
-
-Specify the URL of the Intlayer CMS to connect to for authentication.
-
-- **Type**: `string`
-- **Default**: The value configured in `intlayer.config.*` or `https://intlayer.org`
-- **Example**:
-
-```bash packageManager="npm"
-npx intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="yarn"
-yarn intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="bun"
-bun x intlayer login --cms-url https://intlayer.org
-```
-
-### Configuration Options
-
-You can also use common configuration options:
-
 - `--env-file <path>`: Path to the environment file
 - `-e, --env <env>`: Execution environment
 - `--base-dir <dir>`: Base directory of the project

package/docs/en-GB/cli/scan.md

@@ -18,7 +18,7 @@ slugs:
   - cli
   - scan
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Added scan command"
 author: aymericzip

package/docs/en-GB/cli/test.md

@@ -98,40 +98,4 @@ pnpm intlayer content test --verbose
 bun x intlayer content test --verbose
 ```
 
-The output helps you quickly identify which translations need to be completed to ensure your application works correctly across all configured locales.
-
-> Example: `npx intlayer content test --base-dir ./src --env-file .env.production.local`
-
-- **`--no-cache`**: Disable the cache.
-
-  > Example: `npx intlayer build --no-cache`
-
-**Preparation options:**
-
-- **`--build`**: Build the dictionaries before pushing to ensure the content is up to date. True will force the build, false will skip the build, undefined will allow using the cache of the build.
-
-**Log options:**
-
-- **`--verbose`**: Enable verbose logging for debugging. (default to true using CLI)
-
-  > Example: `npx intlayer content test --verbose`
-
-## Example:
-
-```bash packageManager="npm"
-npx intlayer content test --verbose
-```
-
-```bash packageManager="yarn"
-yarn intlayer content test --verbose
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer content test --verbose
-```
-
-```bash packageManager="bun"
-bun x intlayer content test --verbose
-```
-
 The output helps you quickly identify which translations need to be completed to ensure your application works properly across all configured locales.

package/docs/en-GB/compat/i18n-js.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from i18n-js to Intlayer"
+description: "Learn how to migrate your application from i18n-js to Intlayer using the compat adapter."
+keywords:
+  - i18n-js
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18n-js
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from i18n-js to Intlayer
+
+Transitioning from the `i18n-js` library to Intlayer is a highly optimised migration designed to offload large translations configurations into Intlayer's structured file resolution system.
+
+## What to do
+
+Execute the following setup command in your repository:
+
+```bash
+npx intlayer init
+```
+
+With `intlayer.config.ts` prepared, you can add Intlayer's alias to your bundler configuration so that any imports of `i18n-js` target the compat package `@intlayer/i18n-js`.
+
+## What it does under the hood
+
+`i18n-js` accesses namespaces through expressions like `i18n.t('scope.key', {name})` along with locale fallbacks and specific plural mappings.
+
+Under the hood:
+
+- **Interpolation:** The compat adapter easily parses `%{name}` mappings into your targeted runtime dictionary value.
+- **Pluralisation:** Replaces `one/other` subkeys and maps them against Intlayer's powerful underlying plural mechanisms (`Intl.PluralRules`), abstracting away manual mappings.
+- **Locales:** Instead of loading monolithic language payloads at bootstrap, dictionaries are served up optimally based on the current context setup via the native Intlayer configuration.

package/docs/en-GB/compat/i18next.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from i18next to Intlayer"
+description: "Learn how to migrate your Vanilla JS/TS application from i18next to Intlayer using the compat adapter."
+keywords:
+  - i18next
+  - vanilla
+  - javascript
+  - typescript
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from i18next to Intlayer
+
+For a detailed step-by-step tutorial, please see our full [i18next Migration Guide](../migration_from_i18next_to_intlayer.md).
+
+Intlayer perfectly replicates the core runtime characteristics of `i18next`. By utilising the compat package, your Vanilla applications or internal modules can continue to leverage familiar syntax.
+
+## What to do
+
+To begin, initialise Intlayer in your project:
+
+```bash
+npx intlayer init
+```
+
+If you are using Vite, include the Intlayer plugin to route imports to `@intlayer/i18next`:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { i18nextVitePlugin } from "@intlayer/i18next/plugin";
+
+export default defineConfig({
+  plugins: [i18nextVitePlugin()],
+});
+```
+
+## What it does under the hood
+
+The `i18nextVitePlugin` aliases `i18next` imports to `@intlayer/i18next`, avoiding bundle bloat from JSON file inclusions.
+
+Under the hood:
+
+- **Instance configuration:** `createInstance` correctly parses and applies namespace fallbacks while leveraging Intlayer's compilation pipeline for dictionary retrieval.
+- **Interpolation:** Native support for `{{name}}` replacements and `$t(key)` nesting recursively.
+- **Context & Plurals:** Identifies and resolves suffix formats like `key_male` and `key_one`/`key_other` evaluating against standard `Intl.PluralRules`.
+- **Return objects:** The `returnObjects: true` mode safely extracts trees from Intlayer dictionaries.

package/docs/en-GB/compat/index.md

@@ -0,0 +1,51 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Intlayer Compat Adapters"
+description: "Migrate your existing i18n solution to Intlayer with zero friction using compat adapters."
+keywords:
+  - compat
+  - migration
+  - internationalisation
+  - i18n
+  - Intlayer
+slugs:
+  - doc
+  - compatibility
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Intlayer Compat Adapters
+
+Migrating a large application to a new internationalisation library can be daunting. To ease this transition, Intlayer provides **compat adapters** for the most popular i18n libraries in the ecosystem.
+
+These adapter packages expose the **exact same public API** as your existing i18n libraries, but delegate all translation work to Intlayer at runtime.
+
+## How it works
+
+When you use a compat adapter, you do not need to rewrite your application's imports or change how you use your translation hooks and components. Instead, Intlayer's bundler plugins automatically alias your existing imports to the Intlayer compat packages.
+
+For example, a developer replaces `import { useTranslation } from 'react-i18next'` with `import { useTranslation } from '@intlayer/react-i18next'` (done automatically via the bundler plugin), and the app keeps working with translations now served from Intlayer dictionaries. Keys are also typed against your Intlayer dictionaries!
+
+## Available Compat Adapters
+
+Choose your existing library below to see how to migrate seamlessly:
+
+- [Vue I18n](./vue-i18n.md)
+- [Transloco](./transloco.md)
+- [React Intl](./react-intl.md)
+- [Svelte I18n](./svelte-i18n.md)
+- [React i18next](./react-i18next.md)
+- [Polyglot.js](./polyglot.md)
+- [NuxtJS I18n](./nuxtjs-i18n.md)
+- [NGX Translate](./ngx-translate.md)
+- [Next Translate](./next-translate.md)
+- [Next Intl](./next-intl.md)
+- [Next i18next](./next-i18next.md)
+- [i18next](./i18next.md)
+- [Lingui](./lingui.md)
+- [I18n-js](./i18n-js.md)

package/docs/en-GB/compat/lingui.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from Lingui to Intlayer"
+description: "Learn how to migrate your application from Lingui to Intlayer using the compat adapter."
+keywords:
+  - lingui
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - lingui
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from Lingui to Intlayer
+
+If your project currently relies on Lingui's macro-based compilation, transitioning to Intlayer allows you to maintain your powerful macro workflows while backing them natively with Intlayer's JSON compilation strategy.
+
+## What to do
+
+To begin, initialise Intlayer in your project:
+
+```bash
+npx intlayer init
+```
+
+This creates your `intlayer.config.ts`. Ensure you retain `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin` in your build step to run _before_ the Intlayer compiler. Then, use the bundler plugin alias to route `@lingui/core` and `@lingui/react` to `@intlayer/lingui`.
+
+## What it does under the hood
+
+Lingui utilises macros (like `` t`Hello ${name}` `` and `<Trans>`) which are compiled into runtime calls like `i18n._(id, values)`.
+
+Under the hood:
+
+- **Macros:** They compile precisely as they did before, ensuring no disruption in your source syntax.
+- **Runtime translation:** The aliased `i18n._()` uses Intlayer dictionaries. Both explicitly named IDs and hashed IDs are fully mapped using Intlayer's `.po` sync plugins to aggregate and prune keys securely.
+- **ICU capabilities:** Support for pluralisation, selection, and ICU variants remains robust due to Intlayer's unified ICU parser, ensuring identical rendering outputs.

package/docs/en-GB/compat/next-i18next.md

@@ -0,0 +1,57 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from next-i18next to Intlayer"
+description: "Learn how to migrate your Next.js application from next-i18next to Intlayer using the compat adapter."
+keywords:
+  - next-i18next
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from next-i18next to Intlayer
+
+For a complete and detailed step-by-step tutorial, please see our full [next-i18next Migration Guide](../migration_from_next-i18next_to_intlayer.md).
+
+Intlayer handles all Next.js Pages Router and App Router implementations transparently. Using the adapter lets you migrate your `next-i18next` implementation with zero code rewrite.
+
+## What to do
+
+To begin, run:
+
+```bash
+npx intlayer init
+```
+
+This creates the required Intlayer setup file. To swap to Intlayer behind the scenes, update your `next.config.ts`:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## What it does under the hood
+
+The `createNextI18nPlugin` composes Next.js's native behaviour alongside the core `next-intlayer` plugin, injecting all required Webpack/Turbopack aliases for `next-i18next`, `react-i18next`, and `i18next`.
+
+Under the hood:
+
+- **`serverSideTranslations` & `appWithTranslation`:** They now function as wrappers for Intlayer's internal loaders, circumventing large static JSON injection.
+- **Client hooks:** Delegates immediately to `@intlayer/react-i18next` retaining all formatting, plurals, and nested namespace features.

package/docs/en-GB/compat/next-intl.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from next-intl to Intlayer"
+description: "Learn how to migrate your Next.js application from next-intl to Intlayer using the compat adapter."
+keywords:
+  - next-intl
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from next-intl to Intlayer
+
+For a complete and detailed step-by-step tutorial, please see our full [next-intl Migration Guide](../migration_from_next-intl_to_intlayer.md).
+
+Migrating from `next-intl` to Intlayer allows you to maintain your application routing and syntax completely undisturbed.
+
+## What to do
+
+Execute the following command in your repository:
+
+```bash
+npx intlayer init
+```
+
+This will create an `intlayer.config.ts`. In your `next.config.ts`, use the plugin wrapper to seamlessly inject the `next-intl` aliases towards `@intlayer/next-intl`.
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
+
+const withIntlayer = createNextIntlPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## What it does under the hood
+
+The bundler wrapper replaces translations, but **leaves the `next-intl/navigation` features intact** (e.g. `Link`, `redirect`, `usePathname`).
+
+Under the hood:
+
+- **ICU runtime:** Plurals (`=0`, `one`, `other`), select/selectordinal, `#` arguments, and formatted args (`{ts, date, long}`) run correctly using the shared `resolveMessage(..., 'icu')` resolver.
+- **`useTranslations()` & `getTranslations()`:** The bare scope calls extract the first key segment as the correct dictionary identifier. Nested namespaces gracefully split into dictionary paths and prefixes.
+- **Rich formatting:** Both `t.rich()` and `t.markup()` are fully natively implemented, converting HTML-like nodes into rendered React chunks.
+- **`useFormatter`:** `relativeTime`, `list`, `dateTimeRange`, and named formats from the configuration bridge to the core native `Intl` formatters.

package/docs/en-GB/compat/next-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from Next Translate to Intlayer"
+description: "Learn how to migrate your Next.js application from next-translate to Intlayer using the compat adapter."
+keywords:
+  - next-translate
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from Next Translate to Intlayer
+
+Migrating from `next-translate` to Intlayer is a near drop-in replacement that retains your existing syntax and tags.
+
+## What to do
+
+Initialise Intlayer in your project:
+
+```bash
+npx intlayer init
+```
+
+The CLI will scaffold your configuration. You can then apply the Intlayer plugin in your `next.config.ts`, which injects build-time subpath aliases mapping `next-translate/useTranslation` to `@intlayer/next-translate`.
+
+## What it does under the hood
+
+`next-translate` provides hooks like `useTranslation('ns')`, `t('ns:key.path')`, and the `<Trans>` component.
+
+Under the hood:
+
+- **Interpolation & Plurals:** It relies closely on the `react-i18next` adapter behaviour. Handled dynamically are `{{var}}` placeholders and pluralisation mapped from suffixes like `key_0`, `key_one`, and `key_other`.
+- **`<Trans>` component:** Directly supported for HTML-ish tag parsing alongside an array-based `components` prop.
+- **Namespaces:** Subpath aliasing ensures that your `useTranslation` references the correct internal dictionary namespaces without manual modification.

package/docs/en-GB/compat/ngx-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from NGX-Translate to Intlayer"
+description: "Learn how to migrate your Angular application from ngx-translate to Intlayer using the compat adapter."
+keywords:
+  - ngx-translate
+  - angular
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - ngx-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from NGX-Translate to Intlayer
+
+Migrating your Angular application from `ngx-translate` to Intlayer is easy with the compat adapter, allowing you to bypass the need to rewrite all your templates.
+
+## What to do
+
+Begin by running:
+
+```bash
+npx intlayer init
+```
+
+This sets up the `intlayer.config.ts`. Replace your `TranslateModule.forRoot()` setups and import aliases appropriately to point to `@intlayer/ngx-translate`.
+
+## What it does under the hood
+
+`ngx-translate` uses `TranslateService` (`instant`, `get`, `stream`) alongside the `{{ 'KEY' | translate:params }}` pipe and the `[translate]` directive.
+
+Under the hood:
+
+- **Services:** `TranslateService` wraps `getIntlayer` and a locale observable, providing exactly the same methods.
+- **Pipes & Directives:** Re-implemented to resolve against Intlayer dictionaries directly.
+- **Loaders:** `TranslateHttpLoader` setups are converted to warning stubs because Intlayer inherently resolves and bundles your dictionaries at build time (or through standard dynamic imports), completely eliminating the need for HTTP loaders.