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

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.

package/docs/en/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-05-12
+updatedAt: 2026-06-17
 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: 8.10.0
+    date: 2026-06-17
+    changes: "Add `format` option to the dictionary configuration"
   - version: 8.9.4
     date: 2026-05-12
     changes: "Add support for LM Studio provider"
@@ -135,6 +138,7 @@ Intlayer accepts JSON, JS, MJS, and TS configuration file formats:
 ````typescript fileName="intlayer.config.ts" codeFormat="typescript"
 import { Locales, type IntlayerConfig } from "intlayer";
 import { nextjsRewrite } from "intlayer/routing";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 import { z } from "zod";
 
 /**
@@ -586,10 +590,38 @@ const config: IntlayerConfig = {
     }),
   },
 
+  /**
+   * Dictionary configuration.
+   */
+  dictionary: {
+    /**
+     * Controls how dictionaries are imported.
+     * - "static": Statically imported at build time.
+     * - "dynamic": Dynamically imported using Suspense.
+     * - "fetch": Fetched dynamically via the live sync API.
+     */
+    importMode: "static",
+
+    /**
+     * The default message format for all dictionaries in the project.
+     * - 'intlayer': Native intlayer format (default).
+     * - 'icu': ICU message format (used by next-intl, react-intl, etc.).
+     * - 'i18next': i18next interpolation format (used by i18next, react-i18next, next-i18next).
+     * - 'vue-i18n': Vue I18n format (used by vue-i18n).
+     * - 'po': GNU Gettext PO format.
+     */
+    format: "icu",
+  },
+
   /**
    * Plugins configuration.
    */
-  plugins: [],
+  plugins: [
+    syncJSON({
+      format: "icu",
+      source: ({ locale }) => `./messages/${locale}.json`,
+    }),
+  ],
 };
 
 export default config;
@@ -886,6 +918,7 @@ For more information about content declaration files and how configuration value
 | `contentAutoTransformation` | Automatically transforms content strings into typed nodes (markdown, HTML, or insertion).                                                                 | `boolean` &#124; <br/> `{ markdown?: boolean; html?: boolean; insertion?: boolean }`                            | `false`        | `true`                                                                                      | • Markdown: `### Title` → `md('### Title')`.<br/>• HTML: `<div>Title</div>` → `html('<div>Title</div>')`.<br/>• Insertion: `Hello {{name}}` → `insert('Hello {{name}}')`.                                                                                                                                                                                                                                                                                                                   |
 | `location`                  | Indicates where dictionary files are stored and their CMS synchronization mode.                                                                           | `'local'` &#124; <br/> `'remote'` &#124; <br/> `'hybrid'` &#124; <br/> `'plugin'` &#124; <br/> `string`         | `'local'`      | `'hybrid'`                                                                                  | • `'local'`: managed locally only.<br/>• `'remote'`: managed remotely only (CMS).<br/>• `'hybrid'`: managed both locally and remotely.<br/>• `'plugin'` or custom string: managed by a plugin or custom source.                                                                                                                                                                                                                                                                             |
 | `importMode`                | Controls how dictionaries are imported.                                                                                                                   | `'static'` &#124; <br/> `'dynamic'` &#124; <br/> `'fetch'`                                                      | `'static'`     | `'dynamic'`                                                                                 | • `'static'`: imported statically (replaces `useIntlayer` with `useDictionary`).<br/>• `'dynamic'`: imported dynamically via Suspense (replaces with `useDictionaryDynamic`).<br/>• `'fetch'`: fetched via live sync API; falls back to `'dynamic'` on failure.<br/>• Relies on `@intlayer/babel` and `@intlayer/swc` plugins.<br/>• Keys must be declared statically.<br/>• Ignored if `optimize` is disabled.<br/>• Does not affect `getIntlayer`, `getDictionary`, `useDictionary`, etc. |
+| `format`                    | The default message format for all dictionaries in the project.                                                                                           | `'intlayer'` &#124; <br/> `'icu'` &#124; <br/> `'i18next'` &#124; <br/> `'vue-i18n'` &#124; <br/> `'po'`        | `'intlayer'`   | `'icu'`                                                                                     | • `'intlayer'`: Native intlayer format.<br/>• `'icu'`: ICU message format.<br/>• `'i18next'`: i18next interpolation format.<br/>• `'vue-i18n'`: Vue I18n format.<br/>• `'po'`: GNU Gettext PO format.                                                                                                                                                                                                                                                                                       |
 | `priority`                  | Priority of the dictionary. Higher values take precedence over lower ones when resolving conflicts between dictionaries.                                  | `number`                                                                                                        | `undefined`    | `1`                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `live`                      | Deprecated - use `importMode: 'fetch'` instead. Indicated whether dictionary content was fetched dynamically via the live sync API.                       | `boolean`                                                                                                       | `undefined`    |                                                                                             | Renamed to `importMode: 'fetch'` in v8.0.0.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `schema`                    | Auto-generated by Intlayer for JSON schema validation.                                                                                                    | `'https://intlayer.org/schema.json'`                                                                            | auto-generated |                                                                                             | Do not modify manually.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

package/docs/en/dictionary/condition.md

@@ -69,7 +69,10 @@ export default myConditionalContent;
 
 > If no fallback is declared, the last key declared will be taken as a fallback if the condition is not validated.
 
-## Using Conditional Content with React Intlayer
+## Using Conditional Content
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
 
 To utilize conditional content within a React component, import and use the `useIntlayer` hook from the `react-intlayer` package. This hook fetches the content for the specified key and allows you to pass in a condition to select the appropriate output.
 
@@ -113,6 +116,165 @@ const ConditionalComponent: FC = () => {
 export default ConditionalComponent;
 ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+To utilize conditional content in Next.js Client Components, retrieve it via the `useIntlayer` hook. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+const ConditionalComponent: FC = () => {
+  const { myCondition } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>{myCondition(true)}</p>
+      <p>{myCondition(false)}</p>
+    </div>
+  );
+};
+
+export default ConditionalComponent;
+```
+
+  </Tab>
+  <Tab label="Vue" value="vue">
+
+To utilize conditional content in Vue components, retrieve it via the `useIntlayer` hook. Here's an example:
+
+```vue fileName="**/*.vue"
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const { myCondition } = useIntlayer("my_key");
+</script>
+
+<template>
+  <div>
+    <p>{{ myCondition(true) }}</p>
+    <p>{{ myCondition(false) }}</p>
+  </div>
+</template>
+```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+To utilize conditional content in Svelte components, retrieve it via the `useIntlayer` hook. The store is accessed with `$`. Here's an example:
+
+```svelte fileName="**/*.svelte"
+<script lang="ts">
+import { useIntlayer } from "svelte-intlayer";
+
+const content = useIntlayer("my_key");
+</script>
+
+<div>
+  <p>{$content.myCondition(true)}</p>
+  <p>{$content.myCondition(false)}</p>
+</div>
+```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+To utilize conditional content in Preact components, retrieve it via the `useIntlayer` hook. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { FC } from "preact";
+import { useIntlayer } from "preact-intlayer";
+
+const ConditionalComponent: FC = () => {
+  const { myCondition } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>{myCondition(true)}</p>
+      <p>{myCondition(false)}</p>
+    </div>
+  );
+};
+
+export default ConditionalComponent;
+```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+To utilize conditional content in SolidJS components, retrieve it via the `useIntlayer` hook. Here's an example:
+
+```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
+import type { Component } from "solid-js";
+import { useIntlayer } from "solid-intlayer";
+
+const ConditionalComponent: Component = () => {
+  const { myCondition } = useIntlayer("my_key");
+
+  return (
+    <div>
+      <p>{myCondition(true)}</p>
+      <p>{myCondition(false)}</p>
+    </div>
+  );
+};
+
+export default ConditionalComponent;
+```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+To utilize conditional content in Angular components, retrieve it via the `useIntlayer` hook. Here's an example:
+
+```typescript fileName="app.component.ts" codeFormat="typescript"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-conditional",
+  template: `
+    <div>
+      <p>{{ content().myCondition(true) }}</p>
+      <p>{{ content().myCondition(false) }}</p>
+    </div>
+  `,
+})
+export class ConditionalComponent {
+  content = useIntlayer("my_key");
+}
+```
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+
+To utilize conditional content with `vanilla-intlayer`, retrieve it via the `useIntlayer` hook. Here's an example:
+
+```typescript fileName="**/*.ts" codeFormat={["typescript", "esm"]}
+import { installIntlayer, useIntlayer } from "vanilla-intlayer";
+
+installIntlayer();
+
+const content = useIntlayer("my_key").onChange((newContent) => {
+  document.getElementById("true-content")!.textContent =
+    newContent.myCondition(true);
+  document.getElementById("false-content")!.textContent =
+    newContent.myCondition(false);
+});
+
+// Initial render
+document.getElementById("true-content")!.textContent =
+  content.myCondition(true);
+document.getElementById("false-content")!.textContent =
+  content.myCondition(false);
+```
+
+  </Tab>
+</Tabs>
+
 ## Additional Resources
 
 For more detailed information on configuration and usage, refer to the following resources: