@intlayer/docs 9.0.0-canary.3 → 9.0.0-canary.5

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.

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

@@ -0,0 +1,46 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from NuxtJS I18n to Intlayer"
+description: "Learn how to migrate your Nuxt.js application from @nuxtjs/i18n to Intlayer using the compat adapter."
+keywords:
+  - nuxtjs-i18n
+  - nuxt
+  - vue
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - nuxtjs-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from NuxtJS I18n to Intlayer
+
+Migrating your Nuxt application from `@nuxtjs/i18n` to Intlayer is a seamless process using the Nuxt adapter module.
+
+## What to do
+
+To initialise the project, run:
+
+```bash
+npx intlayer init
+```
+
+This will set up `intlayer.config.ts`. Then, add the Intlayer Nuxt module (e.g. `@intlayer/nuxt-i18n`) in your `nuxt.config.ts` modules array. This automatically applies the compat configuration for your application.
+
+## What it does under the hood
+
+`@nuxtjs/i18n` wraps `vue-i18n` whilst providing Nuxt-specific routing composables (`useLocalePath`, `useSwitchLocalePath`, `<NuxtLinkLocale>`).
+
+Under the hood:
+
+- **Translations:** Relies natively on the `@intlayer/vue-i18n` compat layer for all string translation tasks (fully supporting `vue-i18n` formats, pipe plurals, and reactivity).
+- **Routing:** Mirrors the routing composables using Intlayer's localised URL helpers.
+- **Configuration:** Reads the `availableLocales` and default settings straight from your `intlayer.config.ts` to coordinate Nuxt pages automatically.

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

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from Polyglot.js to Intlayer"
+description: "Learn how to migrate from Polyglot.js to Intlayer using the compat adapter."
+keywords:
+  - polyglot
+  - airbnb
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - polyglot
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from Polyglot.js to Intlayer
+
+If you are using Airbnb's Polyglot.js, migrating to Intlayer is extremely straightforward using the compat layer.
+
+## What to do
+
+Simply run the initialisation command in your project:
+
+```bash
+npx intlayer init
+```
+
+This generates `intlayer.config.ts`. You can then utilise the bundler plugin alias to transparently redirect Polyglot imports to `@intlayer/polyglot`.
+
+## What it does under the hood
+
+Polyglot.js syntax typically relies on `polyglot.t('key', {name})` with `%{name}` interpolations and `smart_count` plurals separated by `"singular |||| plural"`.
+
+Under the hood:
+
+- **Interpolation:** The compat layer handles `%{var}` placeholders natively.
+- **Plurals:** The string is split at `||||` and evaluated against native `Intl.PluralRules` according to the active locale, mirroring Polyglot's own bucket order per locale.
+- **Dictionaries:** You bypass the need to provide huge JSON configurations to `new Polyglot()` – Intlayer handles the dictionaries dynamically and prunes them automatically.

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

@@ -0,0 +1,58 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from react-i18next to Intlayer"
+description: "Learn how to migrate your React application from react-i18next to Intlayer using the compat adapter."
+keywords:
+  - react-i18next
+  - i18next
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - react-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from react-i18next to Intlayer
+
+For a complete and detailed step-by-step tutorial, please see our full [react-i18next Migration Guide](../migration_from_react-i18next_to_intlayer.md).
+
+Using Intlayer's compat adapter allows you to migrate from `react-i18next` without any changes to your source code imports.
+
+## What to do
+
+To initialise the project, run:
+
+```bash
+npx intlayer init
+```
+
+During initialisation, Intlayer will install `@intlayer/react-i18next` and create `intlayer.config.ts`. In your bundler (like Vite), apply the Intlayer plugin:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactI18nextVitePlugin()],
+});
+```
+
+## What it does under the hood
+
+The `reactI18nextVitePlugin` wraps the core `vite-intlayer` plugin and injects resolve aliases for `react-i18next` and `i18next`, redirecting them to `@intlayer/react-i18next` and `@intlayer/i18next`.
+
+Under the hood:
+
+- **`useTranslation` & `withTranslation`:** Rewritten to use Intlayer's native hooks, giving you automatic TypeScript completion for your dictionary keys. It seamlessly supports namespaces (e.g. `t('namespace:key')`).
+- **Plurals & Context:** Handles i18next's suffix-based pluralisation (`key_one`, `key_other`) using native `Intl.PluralRules` and context suffixes (`key_male`).
+- **`<Trans>` Component:** Re-implemented to support the `components` prop, object and array forms, and numbered tags `<1>...</1>` directly mapping to your React nodes.
+- **`i18n` instance:** Resolves keys directly from Intlayer without fetching large JSON files, resulting in significantly lower bundle sizes.

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

@@ -0,0 +1,55 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from React Intl to Intlayer"
+description: "Learn how to migrate your React application from react-intl to Intlayer using the compat adapter."
+keywords:
+  - react-intl
+  - formatjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - react-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from React Intl to Intlayer
+
+If your React application uses `react-intl` (FormatJS), transitioning to Intlayer is a breeze. Our compat layer seamlessly handles ICU MessageFormat and all existing `Formatted*` components.
+
+## What to do
+
+Start by running the initialisation command in your project:
+
+```bash
+npx intlayer init
+```
+
+Then, set up the Intlayer Vite or Next.js plugin in your configuration. This plugin injects build-time aliases to redirect `react-intl` imports to `@intlayer/react-intl`.
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import reactIntlVitePlugin from "@intlayer/react-intl/plugin";
+
+export default defineConfig({
+  plugins: [react(), reactIntlVitePlugin()],
+});
+```
+
+## What it does under the hood
+
+The bundler plugin aliases `react-intl` to `@intlayer/react-intl`. Instead of parsing large JSON files manually and wrapping your app in an `IntlProvider`, the Intlayer plugin statically extracts keys and uses Intlayer dictionaries at runtime.
+
+Under the hood:
+
+- **ICU MessageFormat:** Intlayer uses the `resolveMessage(..., 'icu')` resolver which fully supports the ICU pluralisation, selection, date/number formatting, and rich text tags natively.
+- **Method & JSX callers:** `intl.formatMessage({ id: 'a.b' })` and `<FormattedMessage id="a.b">` are identified by the Intlayer compiler plugins (`@intlayer/babel` / `@intlayer/swc`), converting flat dotted keys so that the first segment correctly resolves to the Intlayer dictionary key.
+- **Formatters:** `<FormattedNumber>`, `<FormattedDate>`, etc., bridge over to the native `core/formatters` using `Intl`.

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

@@ -0,0 +1,47 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from Svelte I18n to Intlayer"
+description: "Learn how to migrate your Svelte application from svelte-i18n to Intlayer using the compat adapter."
+keywords:
+  - svelte-i18n
+  - svelte
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - svelte-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from Svelte I18n to Intlayer
+
+Moving your Svelte application from `svelte-i18n` to Intlayer takes just a moment using the compat adapter.
+
+## What to do
+
+Simply run the initialisation command in your project:
+
+```bash
+npx intlayer init
+```
+
+This generates `intlayer.config.ts`. Ensure your SvelteKit / Vite plugins are wrapped with Intlayer's alias plugin to seamlessly map `svelte-i18n` to `@intlayer/svelte-i18n`.
+
+## What it does under the hood
+
+Svelte-i18n relies on heavily used stores (`$_`, `$t`, `$format`, etc.) and ICU MessageFormat.
+
+Under the hood:
+
+- **Stores:** Intlayer proxies the `svelte-i18n` stores. `$_` becomes a derived store of the current locale returning an Intlayer resolver.
+- **Keys:** Your flat keys (e.g. `$_('home.title')`) are evaluated such that the first path segment represents the Intlayer dictionary.
+- **ICU Syntax:** Fully handled by the shared ICU resolver (`intl-messageformat` equivalent parsing).
+- **Formatters:** `$date`, `$time`, `$number` calls redirect safely to Intlayer's native core formatters.
+- **Babel/SWC Analysis:** The Intlayer analyser reads the Svelte store callers (`$_`) inside your `.svelte` source files before compilation to automatically build the relevant dictionary chunks.

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

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from Transloco to Intlayer"
+description: "Learn how to migrate your Angular application from Transloco to Intlayer using the compat adapter."
+keywords:
+  - transloco
+  - angular
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - transloco
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from Transloco to Intlayer
+
+If your Angular application currently uses `@jsverse/transloco`, you can migrate to Intlayer using our compat adapter. This transition allows you to maintain your existing template syntax whilst utilising Intlayer's powerful dictionary structure.
+
+## What to do
+
+Simply run the initialisation command in your project:
+
+```bash
+npx intlayer init
+```
+
+This will generate the necessary `intlayer.config.ts` configuration. You will then replace your Transloco imports with `@intlayer/transloco` modules or rely on the build aliases.
+
+## What it does under the hood
+
+Transloco uses scopes and a `TranslocoService` (`translate`, `selectTranslate`), alongside structural directives (`*transloco="let t"`) and pipes (`| transloco`).
+
+Under the hood:
+
+- **Scopes:** Map naturally to Intlayer dictionary keys, providing a great pruning story for bundle optimisation.
+- **Service & Directives:** Intlayer's Angular adapter seamlessly replaces the providers, allowing your existing template pipes and directives to resolve strings against Intlayer dictionaries.
+- **Build time parsing:** The TypeScript analyser recognises `instant/get` calls, and fallback pruning ensures correctness even when template usage isn't statically trackable.