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

package/docs/de/releases/v9.md

@@ -0,0 +1,232 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-14
+title: Neues Intlayer v9 – Was ist neu?
+description: Entdecken Sie die Neuerungen in Intlayer v9. Einführung von Drop-in-Kompatibilitätspaketen für beliebte i18n-Bibliotheken und Unterstützung für Collections, Variants und Dynamic Records.
+keywords:
+  - Intlayer
+  - Compatibility
+  - Migration
+  - Collections
+  - Variants
+  - Dynamic Records
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+author: aymericzip
+---
+
+# Neues Intlayer v9 – Was ist neu?
+
+Willkommen bei Intlayer v9! Dieses Major Release markiert einen riesigen Meilenstein bei der Vereinfachung des Migrationspfads zu Intlayer mit **Compat Adapter Packages** für wichtige i18n-Bibliotheken (`react-i18next`, `next-intl`, `vue-i18n`, etc.) und fügt Unterstützung für reichhaltige Inhaltsstrukturen hinzu: **Collections**, **Variants** und **Dynamic Records**.
+
+## Inhaltsverzeichnis
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Compat Adapter Packages
+
+Die Migration von beliebten i18n-Bibliotheken zu Intlayer ist jetzt einfacher denn je. Wir haben fünf Kompatibilitätspakete erstellt, die die **exakt gleichen öffentlichen APIs** wie Standard-i18n-Bibliotheken bereitstellen, aber die gesamte Übersetzungsarbeit zur Laufzeit an Intlayer delegieren.
+
+### Gleiche öffentliche API mit strenger Typisierung
+
+Durch das Ersetzen von Imports erhalten Sie alle Vorteile von Intlayer (einschließlich Compile-Time-Typsicherheit gegenüber Ihren tatsächlichen Dictionaries) mit minimalen Codeänderungen:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+
+Ändern Sie zum Beispiel einfach:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+zu:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Ihre Keys werden nun **streng typisiert** gegenüber Ihren Intlayer-Dictionaries, was eine vollständige Dot-Path-Auto-Vervollständigung in Ihrer IDE bietet!
+
+### Bundler Alias Plugins (Vite, Next.js, Turbopack)
+
+Um die Migration ohne manuelles Umschreiben aller Import-Statements zu ermöglichen, enthält jedes Compat Adapter Package ein **benutzerdefiniertes Bundler-Plugin** (Vite oder Next.js) unter dem Subpfad `/plugin`.
+
+Diese Plugins schreiben bestehende Imports (z.B. `react-i18next` oder `next-intl`) zur Build-Zeit automatisch in ihre `@intlayer/*`-Äquivalente um.
+
+#### Next.js (Webpack / Turbopack) Beispiel
+
+Anstelle von `withIntlayer` umschließen Sie Ihre Next.js-Konfiguration mit dem Kompatibilitäts-Plugin:
+
+```ts fileName="next.config.ts"
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+import type { NextConfig } from "next";
+
+const withIntlayer = createNextI18nPlugin();
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+#### Vite (React, Vue, Solid, Svelte) Beispiel
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Mutualized Runtime Resolver
+
+Alle Kompatibilitätsadapter leiten die Übersetzungsauflösung nun über einen einzigen, hochoptimierten Runtime-Parser: `@intlayer/core/messageFormat`.
+
+- **Interpolate Message**: Löst Standard `{{var}}` (Leerzeichen & Dot-Pfade), ICU-formatierte Argumente (`{v, number, percent}` etc.) und einfache `{var}`-Templates auf.
+- **Message Node Resolver**: Löst verschachtelte Nodes auf: `insert()`, `plural()` (CLDR-Pluralregeln), `enu()` (Aufzählung), `gender()`, HTML-Tags, Arrays und aufrufbare Funktions-Nodes.
+- **Tokenized Tag Parser**: Unterstützt Inline-XML/HTML-Tags und nummerierte Tags (z.B. `<1>children</1>`), um Rich-Text-Rendering out-of-the-box zu ermöglichen.
+
+---
+
+## Feature Spec: Collections, Variants & Dynamic Records
+
+Intlayer v9 geht über statische Schlüssel-Wert-Objekte hinaus und ermöglicht es Dictionaries, dynamische Layout-Strukturen zu deklarieren, die End-to-End vollständig typisiert sind.
+
+### 1. Collections
+
+Definieren Sie eine CMS-verwaltete Liste geordneter Elemente (z.B. FAQs, Produkte oder Bloglisten):
+
+```ts fileName="faq.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  content: [
+    {
+      question: t({
+        de: "Was ist Intlayer?",
+        en: "What is Intlayer?",
+        fr: "Qu'est-ce qu'Intlayer ?",
+      }),
+      answer: t({
+        de: "Ein i18n-Toolkit.",
+        en: "An i18n toolkit.",
+        fr: "Une boîte à outils i18n.",
+      }),
+    },
+  ],
+} satisfies Dictionary;
+```
+
+#### Verwendung:
+
+```ts
+// Alle Elemente abrufen
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Einzelnes Element nach Index abrufen
+const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+```
+
+### 2. Variants
+
+Liefern Sie A/B-Tests, saisonale Header, Feature Flags oder benutzerdefinierte Landing Pages:
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ de: "Willkommen", en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({
+      de: "Jetzt einkaufen",
+      en: "Shop now",
+      fr: "Acheter maintenant",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+#### Verwendung:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+### 3. Dynamic Records
+
+Definieren Sie Dictionaries, deren Einträge zur Laufzeit dynamisch über Query-IDs geladen werden:
+
+```ts fileName="product.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "product-copy",
+  meta: {
+    id: "prod_123",
+    category: "books",
+  },
+  content: {
+    title: t({ de: "Clean Code", en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Verwendung:
+
+```ts
+// Ruft nur das angeforderte Element dynamisch ab (erfordert Suspense)
+const product = useIntlayer("product-copy", {
+  id: "prod_123",
+  category: "books",
+});
+```
+
+---
+
+## Dynamisches Laden & Optimierungen der Bundle-Größe
+
+Um Bundles extrem klein zu halten, unterstützt Intlayer v9 dynamisches Lazy Loading.
+
+Stellen Sie in Ihrer Konfiguration `importMode` auf `'dynamic'` oder `'fetch'` ein:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+Zur Build-Zeit scannen `@intlayer/swc` und `@intlayer/babel` Ihre Dateien und ersetzen `useIntlayer` / `getIntlayer`-Aufrufe durch tree-shakeable Wrapper (`useDictionary` / `useDictionaryDynamic`). Nur der für das ausgewählte Collection-Element, die Variante oder das Locale erforderliche Inhalt wird geladen, wodurch verhindert wird, dass Ihr Produktions-Bundle ungenutzte Übersetzungen enthält.
+
+---
+
+## Migrationshinweise von v8
+
+Wenn Sie von v8 upgraden, beachten Sie, dass v9 keine Breaking Changes enthält. Hier sind jedoch die wichtigsten Änderungen:
+
+- **Locales & Dialects**: Wenn Sie externe i18n-Abhängigkeiten verwenden, fügen Sie deren entsprechende Kompatibilitätsadapter-Plugins in Ihrer Konfiguration oder Ihrem Bundler-Setup hinzu, um Imports automatisch umzuschreiben.
+- **Custom Selectors**: Beim Aufruf von `useIntlayer` ist der zweite Parameter nun für ein Options-Objekt reserviert, das `{ locale, item, variant, id }` enthält. Wenn Sie zuvor direkt einen Locale-String übergeben haben, können Sie dies weiterhin tun, aber die Verwendung des Options-Objekts wird für erweiterte Auswahlen empfohlen.
+
+---
+
+## Nützliche Links
+
+- [Leitfaden für Compat Adapter Packages](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/compat/index.md)
+- [Dynamische Dictionaries – Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/dynamic_dictionaries/index.md)
+- [Konfigurationsreferenz](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md)

package/docs/en/CI_CD.md

@@ -93,7 +93,7 @@ export default config;
 
 ```bash fileName=".husky/pre-push"
 npx intlayer build                          # To ensure dictionaries are up to date
-npx intlayer fill --unpushed --mode fill    # Only fill missing content, does not update existing ones
+npx intlayer fill --unpushed --mode complete    # Only fill missing content, does not update existing ones
 ```
 
 > For more information about Intlayer CLI commands and their usage, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
@@ -103,11 +103,11 @@ npx intlayer fill --unpushed --mode fill    # Only fill missing content, does no
 ```bash fileName=".husky/pre-push"
 # App 1
 npx intlayer build --base-dir ./app1
-npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
 
 # App 2
 npx intlayer build --base-dir ./app2
-npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
 ```
 
 ## Using GitHub Actions
@@ -135,8 +135,8 @@ jobs:
     runs-on: ubuntu-latest
     env:
       # OpenAI
-      AI_MODEL: openai
-      AI_PROVIDER: gpt-5-mini
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
       AI_API_KEY: ${{ secrets.AI_API_KEY }}
 
     steps:
@@ -167,10 +167,10 @@ jobs:
 
       # Step 6: Use AI to automatically fill missing translations
       - name: 🤖 Auto-fill missing translations
-        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+        run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
 
       # Step 7: Check if there are changes and commit them
-      - name: � Check for changes
+      - name: 🔍 Check for changes
         id: check-changes
         run: |
           if [ -n "$(git status --porcelain)" ]; then

package/docs/en/cli/ci.md

@@ -128,18 +128,72 @@ bun x intlayer ci fill --verbose --mode complete
 
 ### Use in CI/CD pipelines
 
-In your CI/CD configuration (e.g., GitHub Actions, GitLab CI), set the `INTLAYER_PROJECT_CREDENTIALS` as a secret:
+Running `intlayer init` scaffolds two ready-to-use GitHub Actions workflows for you (see [Scaffolded GitHub Actions](#scaffolded-github-actions) below). The example here shows the equivalent setup using the `ci` command for a monorepo, where credentials are injected per project from `INTLAYER_PROJECT_CREDENTIALS`.
+
+> **AI access**: The `fill` command needs AI access to generate translations. The credentials injected by `ci` from `INTLAYER_PROJECT_CREDENTIALS` (Intlayer CMS access keys) grant AI access through the Intlayer backend, so no separate AI provider key is required. If you prefer to use your own provider key instead, pass `--provider`, `--model`, and `--api-key` to `intlayer ci fill`. The `test` command does not require AI access.
+
+```yaml fileName=".github/workflows/intlayer-ci.yml"
+name: Intlayer CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  intlayer:
+    runs-on: ubuntu-latest
+    env:
+      # CMS access keys per project. They also grant AI access for `fill`.
+      INTLAYER_PROJECT_CREDENTIALS: ${{ secrets.INTLAYER_PROJECT_CREDENTIALS }}
+    steps:
+      - name: ⬇️ Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+
+      - name: 🟢 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: 🤖 Fill missing translations
+        run: npx intlayer ci fill --git-diff --mode complete
+
+      - name: 🧪 Test for missing translations
+        run: npx intlayer ci test
+```
+
+## Scaffolded GitHub Actions
+
+When you run `intlayer init`, Intlayer detects your package manager (npm, yarn, pnpm, or bun) and scaffolds two GitHub Actions workflows under `.github/workflows/`, with commands matching that package manager:
 
-```yaml
-# GitHub Actions example
-env:
-  INTLAYER_PROJECT_CREDENTIALS: ${{ secrets.INTLAYER_PROJECT_CREDENTIALS }}
+- **`intlayer-fill.yml`** — On every pull request, builds the dictionaries and runs `intlayer fill --git-diff --mode complete` to generate missing translations for the changed dictionaries, then commits the result back to the PR branch.
+- **`intlayer-test.yml`** — On every pull request, builds the dictionaries and runs `intlayer test`, failing the check when required locales are missing translations.
 
-steps:
-  - name: Fill dictionaries
-    run: npx intlayer ci fill
+Existing workflow files are never overwritten. To skip scaffolding entirely, run:
+
+```bash
+npx intlayer init --no-github-actions
 ```
 
+### Providing AI access to the fill workflow
+
+The scaffolded `intlayer-fill.yml` requires AI access. Two options are available (configured in the workflow's `env` block):
+
+1. **Your own AI provider key** — Add an `AI_API_KEY` secret in your repository settings (Settings → Secrets and variables → Actions). The workflow forwards it via `--provider`, `--model`, and `--api-key`.
+2. **Intlayer CMS access keys** — Add `INTLAYER_CLIENT_ID` and `INTLAYER_CLIENT_SECRET` secrets and wire them into your `intlayer.config` `editor` section. CMS access keys grant AI access through the Intlayer backend.
+
+The `intlayer-test.yml` workflow does not require any AI access.
+
 ## Error Handling
 
 - If `INTLAYER_PROJECT_CREDENTIALS` is not set, the command will exit with an error.

package/docs/en/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 activated one of the git options, the command will only review the part of the files that getting changed. The script will process by chunking the file and review each chunk. If there is 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/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 given time.
+  - Can be an absolute time 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. So it could be impacted 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 given time.
+  - Can be an absolute time 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. So it could be impacted 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]`**: Customize 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. (default to true using CLI)
+
+  > Example: `npx intlayer doc review --verbose`
+
+**Custom instructions options:**
+
+- **`--custom-instructions [customInstructions]`**: Custom instructions added to the prompt. Useful to apply specific rules regarding formatting, urls 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}}/` by `/{{locale}}/` (Unix)
+> - `\{{baseLocale}}\` by `\{{locale}}\` (Windows)
+> - `_{{baseLocale}}.` by `_{{locale}}.`
+> - `{{baseLocale}}_` by `{{locale}}_`
+> - `.{{baseLocaleName}}.` by `.{{localeName}}.`
+>
+> If the pattern is not found, the output file will add the `.{{locale}}` at the extensions of the file. `./my/file.md` will be reviewed and updated to `./my/file.fr.md` for the French locale.

package/docs/en/cli/index.md

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

package/docs/en/cli/scan.md

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

package/docs/en/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 optimized 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.
+- **Pluralization:** 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/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 utilizing the compat package, your Vanilla applications or internal modules can continue to leverage familiar syntax.
+
+## What to do
+
+To begin, initialize 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/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
+  - internationalization
+  - 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 internationalization 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)