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

package/docs/en/packages/svelte-intlayer/usePathname.md

@@ -0,0 +1,103 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: usePathname Function Documentation | svelte-intlayer
+description: See how to use the usePathname function for svelte-intlayer package
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Svelte
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - svelte-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Add usePathname utility"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Init history"
+author: aymericzip
+---
+
+# Svelte Integration: `usePathname` Documentation
+
+The `usePathname` function returns the current browser pathname with the locale segment stripped, as a Svelte `Readable<string>` store. It is useful for building locale-aware navigation — for example, determining which nav item is active — without having to manually remove the locale prefix.
+
+## Importing `usePathname` in Svelte
+
+```typescript
+import { usePathname } from "svelte-intlayer";
+```
+
+## Overview
+
+`usePathname` creates a Svelte readable store that reads `window.location.pathname`, strips the locale prefix via `getPathWithoutLocale`, and emits a new value whenever the browser fires a `popstate` event (back/forward navigation). Subscribe with the `$` store syntax in components.
+
+## Usage
+
+```svelte fileName="src/components/NavItem.svelte"
+<script lang="ts">
+  import { usePathname } from "svelte-intlayer";
+
+  export let href: string;
+  export let label: string;
+
+  const pathname = usePathname();
+</script>
+
+<a {href} aria-current={$pathname === href ? "page" : undefined}>
+  {label}
+</a>
+```
+
+## Return Value
+
+| Type               | Description                                                                      |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `Readable<string>` | Svelte readable store containing the current pathname without the locale prefix. |
+
+## Behavior
+
+- **Locale stripping**: Removes the leading locale segment (e.g. `/fr/dashboard` → `/dashboard`).
+- **Reactive**: Emits a new value on every `popstate` event (browser back / forward navigation).
+- **SSR-safe**: Returns `""` when `window` is not available.
+- **Cleanup**: The `popstate` listener is removed automatically when the last subscriber unsubscribes.
+
+## Example
+
+```svelte fileName="src/components/Sidebar.svelte"
+<script lang="ts">
+  import { usePathname } from "svelte-intlayer";
+
+  const links = [
+    { href: "/dashboard", label: "Dashboard" },
+    { href: "/settings", label: "Settings" },
+  ];
+
+  const pathname = usePathname();
+</script>
+
+<nav>
+  {#each links as link}
+    <a
+      href={link.href}
+      style:font-weight={$pathname === link.href ? "bold" : "normal"}
+    >
+      {link.label}
+    </a>
+  {/each}
+</nav>
+```
+
+## Related
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/svelte-intlayer/exports.md) — current locale + locale switcher
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getPathWithoutLocale.md) — the underlying utility used by this function

package/docs/en/packages/vue-intlayer/exports.md

@@ -14,6 +14,9 @@ slugs:
   - vue-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Add usePathname utility"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Unified documentation for all exports"
@@ -59,6 +62,7 @@ import "vue-intlayer";
 | `useDictionaryAsync`   | Same as `useDictionary`, but handles asynchronous dictionaries.                                                   | -                                                                                                                     |
 | `useDictionaryDynamic` | Same as `useDictionary`, but handles dynamic dictionaries.                                                        | -                                                                                                                     |
 | `useLocale`            | Returns the current locale and a function to set it.                                                              | -                                                                                                                     |
+| `usePathname`          | Returns the current pathname as a `ComputedRef<string>` with the locale segment removed. Reactive to `popstate`.  | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vue-intlayer/usePathname.md)     |
 | `useRewriteURL`        | Client-side composable to manage URL rewrites. Automatically updates the URL if a localized rewrite rule exists.  | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vue-intlayer/useRewriteURL.md) |
 | `useIntl`              | Returns the Intl object for the current locale.                                                                   | -                                                                                                                     |
 | `useLoadDynamic`       | Composable to load dynamic dictionaries.                                                                          | -                                                                                                                     |

package/docs/en/packages/vue-intlayer/usePathname.md

@@ -0,0 +1,109 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: usePathname Composable Documentation | vue-intlayer
+description: See how to use the usePathname composable for vue-intlayer package
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - vue-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Add usePathname utility"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Init history"
+author: aymericzip
+---
+
+# Vue Integration: `usePathname` Composable Documentation
+
+The `usePathname` composable returns the current browser pathname with the locale segment stripped, as a reactive `ComputedRef<string>`. It is useful for building locale-aware navigation — for example, determining which nav item is active — without having to manually remove the locale prefix.
+
+## Importing `usePathname` in Vue
+
+```typescript
+import { usePathname } from "vue-intlayer";
+```
+
+## Overview
+
+`usePathname` reads `window.location.pathname`, strips the locale prefix via `getPathWithoutLocale`, and updates automatically when the browser fires a `popstate` event (back/forward navigation). The result is exposed as a `ComputedRef<string>` so it integrates naturally with Vue's reactivity system.
+
+## Usage
+
+```vue fileName="src/components/NavItem.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const props = defineProps<{
+  href: string;
+  label: string;
+}>();
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <a :href="href" :aria-current="pathname === href ? 'page' : undefined">
+    {{ label }}
+  </a>
+</template>
+```
+
+## Return Value
+
+| Type                  | Description                                                                      |
+| --------------------- | -------------------------------------------------------------------------------- |
+| `ComputedRef<string>` | Reactive computed ref containing the current pathname without the locale prefix. |
+
+## Behavior
+
+- **Locale stripping**: Removes the leading locale segment (e.g. `/fr/dashboard` → `/dashboard`).
+- **Reactive**: Updates automatically on `popstate` events (browser back / forward navigation).
+- **SSR-safe**: Returns `""` when `window` is not available.
+- **Cleanup**: The `popstate` listener is removed automatically when the component is unmounted (`onUnmounted`).
+
+## Example
+
+```vue fileName="src/components/Sidebar.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "Dashboard" },
+  { href: "/settings", label: "Settings" },
+];
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <nav>
+    <a
+      v-for="link in links"
+      :key="link.href"
+      :href="link.href"
+      :style="{ fontWeight: pathname === link.href ? 'bold' : 'normal' }"
+    >
+      {{ link.label }}
+    </a>
+  </nav>
+</template>
+```
+
+## Related
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vue-intlayer/exports.md) — current locale + locale switcher
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getPathWithoutLocale.md) — the underlying utility used by this composable

package/docs/en/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-14
+updatedAt: 2026-06-23
 title: New Intlayer v9 - What's new?
 description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections, Variants, and Dynamic Records.
 keywords:
@@ -204,10 +204,47 @@ At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace
 
 ---
 
+## Vite Plugin: Bundled Compiler & Proxy
+
+The `intlayer()` Vite plugin now bundles the **compiler** and the **locale-routing proxy** directly, so most projects only need a single plugin in `vite.config.ts`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: Activates automatically when `compiler.enabled` is set and a `compiler.output` path is configured. You no longer need to register `intlayerCompiler()` separately.
+- **Proxy**: Activates automatically based on the new `routing.enableProxy` option (`true` by default). It wires the locale detection / redirect / rewrite middleware in development, preview, and production SSR. You no longer need to register `intlayerProxy()` separately.
+
+### `routing.enableProxy` option
+
+A new `routing.enableProxy` option controls whether the locale-routing proxy is plugged in. It defaults to `true`. Disable it when you want to handle locale routing yourself:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // Default: true
+  },
+};
+
+export default config;
+```
+
+The standalone `intlayerCompiler()` and `intlayerProxy()` plugins remain exported for advanced setups. Registering them alongside `intlayer()` is safe — each plugin deduplicates itself and runs only once.
+
+---
+
 ## Migration notes from v8
 
 If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:
 
+- **Vite plugin**: The compiler and locale-routing proxy are now bundled into `intlayer()`. If you previously registered `intlayerCompiler()` or `intlayerProxy()` manually, you can remove them — they are deduplicated automatically, so keeping them is harmless. Use `routing.enableProxy: false` to opt out of the proxy.
 - **Locales & Dialects**: If using external i18n dependencies, add their respective compat adapter plugins in your configuration or bundler setup to automatically rewrite imports.
 - **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant, id }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
 

package/docs/en-GB/CI_CD.md

@@ -26,6 +26,10 @@ author: aymericzip
 
 Intlayer allows the automatic generation of translations for your content declaration files. There are multiple ways to achieve this depending on your workflow.
 
+## Table of Contents
+
+<TOC/>
+
 ## Using the CMS
 
 With Intlayer, you can adopt a workflow where only a single locale is declared locally, while all translations are managed remotely through the CMS. This allows content and translations to be completely detached from the codebase, offering more flexibility for content editors and enabling hot content reloading (no need to rebuild the application to apply changes).

package/docs/en-GB/autoFill.md

@@ -28,6 +28,53 @@ history:
 author: aymericzip
 ---
 
+# Fill Content Declaration File Translations
+
+**Autofill content declaration files** in your CI are a way to speed up your development workflow.
+
+## Understanding the behaviour
+
+The `fill` command includes two modes:
+
+- **Complete**: Automatically fill all missing content for each locale and edit the current file, or another file if specified. That is, complete mode will skip the translation of existing content, if already translated.
+- **Review**: Automatically fill **all** content for each locale and generate for a specific file, or another file if specified.
+
+The fill command will process all your locale content declaration files. That is, it will not process your remote content from the CMS. The CMS includes its own translations management.
+If you use plugins such as `@intlayer/sync-json-plugin`, Intlayer will transform the JSON files into locale content declaration files. That is, they will be processed by the `fill` command.
+
+The new generated files include a `filled` instruction as dictionary metadata. This instruction will be used by Intlayer to know if the file has been autofilled or not, and skip this file from being translated again if present.
+
+Intlayer will also consider the following instruction for autofill:
+
+- From your `.content.{ts|js|json}` → `fill` instruction
+- From your configuration file `.intlayer.config.ts` → `dictionary.fill` instruction
+- Will be set to `true` by default otherwise
+
+For per-locale content declaration files, the `true` instruction will be replaced by `./{{fileName}}.fill.content.json`. This is because a per-locale content declaration file cannot receive additional localised content. So it will generate a new file to not overwrite the existing file.
+
+## Default Behavior
+
+By default, `fill` is set to `true` globally, which means Intlayer will automatically fill all content files and edit the file itself. This behaviour can be customised in several ways:
+
+### Global Configuration Options
+
+1. **`fill: true` (default)** - Automatically fill all locales and edit the current file
+2. **`fill: false`** - Disable auto-fill for this content file
+3. **`fill: "./relative/path/to/file"`** - Create/update the specified file without editing the current one by pointing to a relative path resolved based on the location of the current file
+4. **`fill: "/absolute/path/to/file"`** - Create/update the specified file without editing the current one by pointing to a relative path resolved based on the location of base directory (field `baseDir` in the configuration file `.intlayer.config.ts`)
+5. **`fill: "C:\\absolute\path\to\file"`** - Create/update the specified file without editing the current one by pointing to an absolute path resolved based on your operating system
+6. **`fill: { [key in Locales]?: string }`** - Create/update the specified file for each locale
+
+### v7 Behaviour Changes
+
+In v7, the `fill` command behaviour has been updated:
+
+- **`fill: true`** - Rewrites the current file with filled content for all locales
+- **`fill: "path/to/file"`** - Fills the specified file without modifying the current file
+- **`fill: false`** - Disables auto-fill completely
+
+When using a path option to write to another file, the fill mechanism works through a _master-slave_ relationship between content declaration files. The main (master) file serves as the source of truth, and when it's updated, Intlayer will automatically apply those changes to the derived (filled) declaration files specified by the path.
+
 # Autofill Content Declaration File Translations
 
 **Autofill content declaration files** are a way to speed up your development workflow.
@@ -88,6 +135,40 @@ Intlayer will automatically generate the derived declaration file at `src/compon
 
 Afterwards, both declaration files will be merged into a single dictionary, accessible using the standard `useIntlayer("example")` hook (React) / composable (Vue).
 
+## Global Configuration
+
+You can configure the global auto fill configuration in the `intlayer.config.ts` file.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // Auto-generate missing translations for all dictionaries
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // auto-generate missing translations for all dictionaries like using "./{{fileName}}.content.json"
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+You can still fine‑tune per dictionary using the `fill` field in content files. Intlayer will first consider the per dictionary configuration and then fallback to the global configuration.
+
 ## Autofilled File Format
 
 The recommended format for autofilled declaration files is **JSON**, which helps to avoid formatting constraints. However, Intlayer also supports `.ts`, `.js`, `.mjs`, `.cjs`, and other formats.

package/docs/en-GB/benchmark/solid.md

@@ -118,6 +118,28 @@ We compared **four loading strategies**:
 - **Scoped static**: Keeps code organised (logical separation) without complex extra network requests.
 - **Scoped dynamic**: Best approach for _code splitting_ and performance. Minimises memory by loading only what the current view and active locale need.
 
+### What I measured:
+
+I ran the same multilingual app in a real browser for every stack, then wrote down what actually showed up on the wire and how long things took. Sizes are reported **after normal web compression**, because that is closer to what people download than raw source counts.
+
+- **Internationalization library size**: After bundling, tree-shaking and minification, the size of the i18n library is the size of the providers + hooks/primitives code in an empty component. It does not include the loading of translation files. It answers how expensive the library is before your content enters the picture.
+
+- **JavaScript per page**: For each benchmark route, how much script the browser pulls in for that visit, averaged across the pages in the suite (and across locales where the report rolls them up). Heavy pages are slow pages.
+
+- **Leakage from other locales**: It's the content of the same page but in another language that would be loaded by mistake in the audited page. This content is unnecessary and should be avoided. (e.g. `/fr/about` page content in `/en/about` page bundle)
+
+- **Leakage from other routes**: The same idea for **other screens** in the app: whether their copy is riding along when you only opened one page. (e.g. `/en/about` page content in `/en/contact` page bundle). A high score hints at weak splitting or over-broad bundles.
+
+- **Average component bundle size**: Common UI pieces are measured **one at a time** instead of hiding inside one giant app number. It shows whether internationalization quietly inflates everyday components. For instance, if your component rerenders, it will load all that data from memory. Attaching a giant JSON to any component is like connecting a big store of unused data that will slow down your components' performance.
+
+- **Language switch responsiveness**: I flip the language using the app's own control and time how long it takes until the page has clearly switched, what a visitor would notice, not a lab micro-step.
+
+- **Rendering work after a language change**: A narrower follow-up: how much effort the interface took to repaint for the new language once the switch is in flight. Useful when the "felt" time and the framework cost diverge.
+
+- **Initial page load time**: From navigation to the browser considering the page fully loaded for the scenarios I tested. Good for comparing cold starts.
+
+- **Hydration time**: When the app exposes it, how long the client spends turning server HTML into something you can actually click. A dash in the tables means that implementation did not provide a reliable hydration figure in this benchmark.
+
 ## GitHub STARs
 
 GitHub stars are a strong indicator of a project's popularity, community trust, and long-term relevance. While not a direct measure of technical quality, they reflect how many developers find the project useful, follow its progress, and are likely to adopt it. For estimating the value of a project, stars help compare traction across alternatives and provide insights into ecosystem growth.

package/docs/en-GB/benchmark/svelte.md

@@ -116,6 +116,28 @@ We compared **four loading strategies**:
 - **Scoped static**: Keeps code organised (logical separation) without complex extra network requests.
 - **Scoped dynamic**: Best approach for _code splitting_ and performance. Minimises memory by loading only what the current view and active locale need.
 
+### What I measured:
+
+I ran the same multilingual app in a real browser for every stack, then wrote down what actually showed up on the wire and how long things took. Sizes are reported **after normal web compression**, because that is closer to what people download than raw source counts.
+
+- **Internationalization library size**: After bundling, tree-shaking and minification, the size of the i18n library is the size of the providers + stores code in an empty component. It does not include the loading of translation files. It answers how expensive the library is before your content enters the picture.
+
+- **JavaScript per page**: For each benchmark route, how much script the browser pulls in for that visit, averaged across the pages in the suite (and across locales where the report rolls them up). Heavy pages are slow pages.
+
+- **Leakage from other locales**: It's the content of the same page but in another language that would be loaded by mistake in the audited page. This content is unnecessary and should be avoided. (e.g. `/fr/about` page content in `/en/about` page bundle)
+
+- **Leakage from other routes**: The same idea for **other screens** in the app: whether their copy is riding along when you only opened one page. (e.g. `/en/about` page content in `/en/contact` page bundle). A high score hints at weak splitting or over-broad bundles.
+
+- **Average component bundle size**: Common UI pieces are measured **one at a time** instead of hiding inside one giant app number. It shows whether internationalisation quietly inflates everyday components. For instance, if your component rerenders, it will load all that data from memory. Attaching a giant JSON to any component is like connecting a big store of unused data that will slow down your components' performance.
+
+- **Language switch responsiveness**: I flip the language using the app's own control and time how long it takes until the page has clearly switched, what a visitor would notice, not a lab micro-step.
+
+- **Rendering work after a language change**: A narrower follow-up: how much effort the interface took to repaint for the new language once the switch is in flight. Useful when the "felt" time and the framework cost diverge.
+
+- **Initial page load time**: From navigation to the browser considering the page fully loaded for the scenarios I tested. Good for comparing cold starts.
+
+- **Hydration time**: When the app exposes it, how long the client spends turning server HTML into something you can actually click. A dash in the tables means that implementation did not provide a reliable hydration figure in this benchmark.
+
 ## GitHub STARs
 
 GitHub stars are a strong indicator of a project's popularity, community trust, and long-term relevance. While not a direct measure of technical quality, they reflect how many developers find the project useful, follow its progress, and are likely to adopt it. For estimating the value of a project, stars help compare traction across alternatives and provide insights into ecosystem growth.

package/docs/en-GB/benchmark/tanstack.md

@@ -124,6 +124,28 @@ We compared **four loading strategies**:
 - **Scoped static**: Keeps code organised (logical separation) without complex extra network requests.
 - **Scoped dynamic**: Best approach for _code splitting_ and performance. Minimises memory by loading only what the current view and active locale need.
 
+### What I measured:
+
+I ran the same multilingual app in a real browser for every stack, then wrote down what actually showed up on the wire and how long things took. Sizes are reported **after normal web compression**, because that is closer to what people download than raw source counts.
+
+- **Internationalisation library size**: After bundling, tree-shaking and minification, the size of the i18n library is the size of the providers (e.g. `NextIntlClientProvider`) + hooks (e.g. `useTranslations`) code in an empty component. It does not include the loading of translation files. It answers how expensive the library is before your content enters the picture.
+
+- **JavaScript per page**: For each benchmark route, how much script the browser pulls in for that visit, averaged across the pages in the suite (and across locales where the report rolls them up). Heavy pages are slow pages.
+
+- **Leakage from other locales**: It's the content of the same page but in another language that would be loaded by mistake in the audited page. This content is unnecessary and should be avoided. (e.g. `/fr/about` page content in `/en/about` page bundle)
+
+- **Leakage from other routes**: The same idea for **other screens** in the app: whether their copy is riding along when you only opened one page. (e.g. `/en/about` page content in `/en/contact` page bundle). A high score hints at weak splitting or over-broad bundles.
+
+- **Average component bundle size**: Common UI pieces are measured **one at a time** instead of hiding inside one giant app number. It shows whether internationalisation quietly inflates everyday components. For instance, if your component rerenders, it will load all that data from memory. Attaching a giant JSON to any component is like connecting a big store of unused data that will slow down your components' performance.
+
+- **Language switch responsiveness**: I flip the language using the app's own control and time how long it takes until the page has clearly switched, what a visitor would notice, not a lab micro-step.
+
+- **Rendering work after a language change**: A narrower follow-up: how much effort the interface took to repaint for the new language once the switch is in flight. Useful when the "felt" time and the framework cost diverge.
+
+- **Initial page load time**: From navigation to the browser considering the page fully loaded for the scenarios I tested. Good for comparing cold starts.
+
+- **Hydration time**: When the app exposes it, how long the client spends turning server HTML into something you can actually click. A dash in the tables means that implementation did not provide a reliable hydration figure in this benchmark.
+
 ## GitHub STARs
 
 GitHub stars are a strong indicator of a project's popularity, community trust, and long-term relevance. While not a direct measure of technical quality, they reflect how many developers find the project useful, follow its progress, and are likely to adopt it. For estimating the value of a project, stars help compare traction across alternatives and provide insights into ecosystem growth.

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

@@ -140,6 +140,28 @@ steps:
     run: npx intlayer ci fill
 ```
 
+## 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:
+
+- **`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.
+
+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-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/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/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.