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

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.

package/docs/en-GB/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 whilst leveraging Intlayer's powerful features under the hood.
+
+## What to do
+
+To get started, simply run the initialisation command in your project:
+
+```bash
+npx intlayer init
+```
+
+During the initialisation, 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, honouring 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 optimisation, and seamless CMS integration.

package/docs/en-GB/compiler.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2026-03-12
+updatedAt: 2026-06-23
 title: Intlayer Compiler | Automated Content Extraction for i18n
 description: Automate your internationalisation process with the Intlayer Compiler. Extract content directly from your components for faster, more efficient i18n in Vite, Next.js, and more.
 keywords:
@@ -60,6 +60,8 @@ As an alternative, to automate your i18n process whilst keeping full control of
 
 ## Usage
 
+> The quickest way to wire the compiler in is the interactive setup: run `npx intlayer init --interactive` and select **Compiler**. On Vite there is nothing to configure — the compiler is plugged in directly through the `intlayerCompiler()` plugin. On Next.js the command scaffolds the `babel.config.js` shown below. The non-interactive `intlayer init` leaves the compiler setup untouched.
+
 <Tabs>
  <Tab value='vite'>
 

package/docs/en-GB/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-06-17
+updatedAt: 2026-06-23
 title: Configuration
 description: Learn how to configure Intlayer for your application. Understand the various settings and options available to customize Intlayer to your needs.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.0.0
+    date: 2026-06-24
+    changes: "Add `enableProxy` option to the routing configuration"
   - version: 8.10.0
     date: 2026-06-17
     changes: "Add `format` option to the dictionary configuration"

package/docs/en-GB/custom_domains.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-02
-updatedAt: 2026-04-02
+updatedAt: 2026-06-23
 title: Custom Domains
 description: Learn how to configure domain-based locale routing in Intlayer to serve different locales from dedicated hostnames.
 keywords:

package/docs/en-GB/custom_url_rewrites.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-01-26
+updatedAt: 2026-06-23
 title: Custom URL Rewrites
 description: Learn how to configure and use custom URL rewrites in Intlayer to define locale-specific paths.
 keywords:

package/docs/en-GB/dictionary/content_file.md

@@ -578,6 +578,10 @@ JSON schema used for validation of the dictionary structure. Automatically added
 
 For remote dictionaries, this is the unique identifier of the dictionary on the remote server. Used for fetching and managing remote content.
 
+##### `projectIds` (string[])
+
+For remote dictionaries, this array contains the IDs of the projects that can use this dictionary. A remote dictionary can be shared between multiple projects.
+
 ##### `localId` (LocalDictionaryId)
 
 Unique identifier for local dictionaries. Auto-generated by Intlayer to help identify the dictionary and determine if it is local or remote, along with its location.
@@ -598,13 +602,6 @@ For remote dictionaries, this array contains all available versions of the dicti
 
 Indicates whether the dictionary has been auto-filled from external sources. In case of conflicts, base dictionaries will override auto-filled dictionaries.
 
-##### `location` ('distant' | 'locale')
-
-Indicates the location of the dictionary:
-
-- `'locale'`: Local dictionary (from content files)
-- `'distant'`: Remote dictionary (from external source)
-
 ## Content Node Types
 
 Intlayer provides several specialised content node types that extend basic primitive values:

package/docs/en-GB/dictionary/file.md

@@ -421,6 +421,14 @@ export default myMultilingualContent;
 
 This setup allows the content to be dynamically retrieved based on the user's language preference. When used in the Intlayer Visual Editor or CMS, the system will recognise that the content comes from the specified Markdown files and ensure they remain editable.
 
+## Different types of paths
+
+When using the `file` function, you can use different types of paths to specify the file to embed.
+
+- `file("./path/to/file.txt")` - Relative path to the current file
+- `file("path/to/file.txt")` - Relative path to the project root directory
+- `file("/users/username/path/to/file.txt")` - Absolute path
+
 ## How Intlayer Handles File Content
 
 The `file` function is based on Node.js' `fs` module to read the content of the specified file and insert it into the dictionary. When used in conjunction with the Intlayer Visual Editor or CMS, Intlayer can track the relationship between the dictionary and the file. This allows Intlayer to:

package/docs/en-GB/dictionary/function_fetching.md

@@ -109,7 +109,3 @@ const MyComponent: FC = () => {
 
 export default MyComponent;
 ```
-
-## Doc History
-
-- 5.5.10 - 29 June 2025: Init history

package/docs/en-GB/dictionary/nesting.md

@@ -27,6 +27,14 @@ author: aymericzip
 
 ## How Nesting Works
 
+In Intlayer, nesting is achieved through the `nest` function, which allows you to reference and reuse content from another dictionary. Instead of duplicating content, you can point to an existing content module by its key.
+
+## Setting Up Nesting
+
+To set up nesting in your Intlayer project, you first define the base content that you wish to reuse. Then, in a separate content module, you use the `nest` function to import that content.
+
+## How Nesting Works
+
 <Tabs group="framework">
   <Tab label="React" value="react">
 

package/docs/en-GB/dictionary/translation.md

@@ -393,64 +393,3 @@ document.getElementById("welcome-message")!.textContent = String(
 
   </Tab>
 </Tabs>
-
-## Custom Content Objects
-
-`intlayer` supports custom content objects for translation, allowing you to define more complex structures while ensuring type safety. Here's an example with a custom object:
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-import { t, type Dictionary } from "intlayer";
-
-interface ICustomContent {
-  title: string;
-  content: string;
-}
-
-const customContent = {
-  key: "custom_content",
-  content: {
-    profileText: t<ICustomContent>({
-      en: {
-        title: "Page Title",
-        content: "Page Content",
-      },
-      fr: {
-        title: "Titre de la Page",
-        content: "Contenu de la Page",
-      },
-      es: {
-        title: "Título de la Página",
-        content: "Contenido de la Página",
-      },
-    }),
-  },
-} satisfies Dictionary;
-
-export default customContent;
-```
-
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "custom_content",
-  "content": {
-    "profileText": {
-      "nodeType": "translation",
-      "translation": {
-        "en-GB": {
-          "title": "Page Title",
-          "content": "Page Content"
-        },
-        "fr": {
-          "title": "Titre de la Page",
-          "content": "Contenu de la Page"
-        },
-        "es": {
-          "title": "Título de la Página",
-          "content": "Contenido de la Página"
-        }
-      }
-    }
-  }
-}
-```