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

package/docs/en/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, initialize 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 utilizes 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 pluralization, selection, and ICU variants remains robust due to Intlayer's unified ICU parser, ensuring identical rendering outputs.

package/docs/en/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 behavior 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/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/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
+
+Initialize 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 behavior. Handled dynamically are `{{var}}` placeholders and pluralization 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/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/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 initialize 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` while 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 localized URL helpers.
+- **Configuration:** Reads the `availableLocales` and default settings straight from your `intlayer.config.ts` to coordinate Nuxt pages automatically.

package/docs/en/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 initialization command in your project:
+
+```bash
+npx intlayer init
+```
+
+This generates `intlayer.config.ts`. You can then utilize 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/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 initialize the project, run:
+
+```bash
+npx intlayer init
+```
+
+During initialization, 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 pluralization (`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/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 initialization 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 pluralization, 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/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 initialization 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 analyzer reads the Svelte store callers (`$_`) inside your `.svelte` source files before compilation to automatically build the relevant dictionary chunks.

package/docs/en/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 while utilizing Intlayer's powerful dictionary structure.
+
+## What to do
+
+Simply run the initialization 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 optimization.
+- **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 analyzer recognizes `instant/get` calls, and fallback pruning ensures correctness even when template usage isn't statically trackable.

package/docs/en/compat/vue-i18n.md

@@ -0,0 +1,58 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrate from Vue I18n to Intlayer"
+description: "Learn how to migrate your Vue application from vue-i18n to Intlayer using the compat adapter."
+keywords:
+  - vue-i18n
+  - vue
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - vue-i18n
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrate from Vue I18n to Intlayer
+
+If your Vue application currently uses `vue-i18n`, you can migrate to Intlayer without rewriting your components or translating hooks. Intlayer provides a compat adapter that perfectly mirrors `vue-i18n`'s API while leveraging Intlayer's powerful features under the hood.
+
+## What to do
+
+To get started, simply run the initialization command in your project:
+
+```bash
+npx intlayer init
+```
+
+During the initialization, Intlayer will set up your configuration file (`intlayer.config.ts`) and prepare your project for migration. You will just need to add the Intlayer plugin to your Vite configuration to automatically alias the `vue-i18n` imports.
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vue(), vueI18nVitePlugin()],
+});
+```
+
+## What it does under the hood
+
+The `vueI18nVitePlugin` injects a module alias into your bundler. Any import of `vue-i18n` in your codebase will be transparently redirected to `@intlayer/vue-i18n`.
+
+**Under the hood, the adapter handles the complex `vue-i18n` syntax natively:**
+
+- **Interpolation & Plurals:** Resolves `{name}` and list `{0}` interpolations. Pipe plurals (`"car | cars"`) are converted into Intlayer enumeration/plural nodes based on positional semantics.
+- **Formats:** Functions like `d()` and `n()` wrap `Intl` under the hood, honoring the `datetimeFormats` and `numberFormats` defined in your options.
+- **Global & Local State:** `global.locale` is mapped to a `WritableComputedRef` backed by the Intlayer client, so reactivity behaves exactly as expected (e.g. `locale.value = 'fr'`).
+- **Directives:** The `v-t` directive is registered and functions normally.
+
+Your application continues rendering exactly as before, but the content is powered by your Intlayer dictionaries, giving you type safety, better bundle optimization, and seamless CMS integration.