@intlayer/docs 9.4.1 → 9.4.3

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

@@ -262,6 +262,25 @@ You can configure HTML rendering globally for your entire application. This is i
     );
     ```
 
+    You can also use your own HTML renderer:
+
+    ```tsx fileName="AppProvider.tsx"
+    import { HTMLProvider } from "react-intlayer/html";
+
+    export const AppProvider = ({ children }) => (
+      <HTMLProvider
+        renderHTML={async (html) => {
+          const { renderHTML } = await import('react-intlayer/html');
+          return renderHTML(html);
+        }}
+      >
+        {children}
+      </HTMLProvider>
+    );
+    ```
+
+    > Importing your HTML renderer dynamically is a good way to reduce the bundle size of your application.
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -284,6 +303,29 @@ You can configure HTML rendering globally for your entire application. This is i
     app.mount("#app");
     ```
 
+    You can also use your own HTML renderer:
+
+    ```typescript fileName="main.ts"
+    import { createApp, h } from "vue";
+    import { intlayer } from "vue-intlayer";
+    import { intlayerHTML } from "vue-intlayer/html";
+    import App from "./App.vue";
+
+    const app = createApp(App);
+
+    app.use(intlayer);
+    app.use(intlayerHTML, {
+      renderHTML: async (html) => {
+        const { renderHTML } = await import('vue-intlayer/html');
+        return renderHTML(html);
+      },
+    });
+
+    app.mount("#app");
+    ```
+
+    > Importing your HTML renderer dynamically is a good way to reduce the bundle size of your application.
+
   </Tab>
   <Tab label="Svelte" value="svelte">
 
@@ -302,6 +344,25 @@ You can configure HTML rendering globally for your entire application. This is i
     </HTMLProvider>
     ```
 
+    You can also use your own HTML renderer:
+
+    ```svelte fileName="App.svelte"
+    <script lang="ts">
+      import { HTMLProvider } from "svelte-intlayer/html";
+    </script>
+
+    <HTMLProvider
+      renderHTML={async (html) => {
+        const { renderHTML } = await import('svelte-intlayer/html');
+        return renderHTML(html);
+      }}
+    >
+      <slot />
+    </HTMLProvider>
+    ```
+
+    > Importing your HTML renderer dynamically is a good way to reduce the bundle size of your application.
+
   </Tab>
   <Tab label="Preact" value="preact">
 
@@ -319,6 +380,25 @@ You can configure HTML rendering globally for your entire application. This is i
     );
     ```
 
+    You can also use your own HTML renderer:
+
+    ```tsx fileName="AppProvider.tsx"
+    import { HTMLProvider } from "preact-intlayer/html";
+
+    export const AppProvider = ({ children }) => (
+      <HTMLProvider
+        renderHTML={async (html) => {
+          const { renderHTML } = await import('preact-intlayer/html');
+          return renderHTML(html);
+        }}
+      >
+        {children}
+      </HTMLProvider>
+    );
+    ```
+
+    > Importing your HTML renderer dynamically is a good way to reduce the bundle size of your application.
+
   </Tab>
   <Tab label="Solid" value="solid">
 
@@ -336,6 +416,25 @@ You can configure HTML rendering globally for your entire application. This is i
     );
     ```
 
+    You can also use your own HTML renderer:
+
+    ```tsx fileName="AppProvider.tsx"
+    import { HTMLProvider } from "solid-intlayer/html";
+
+    export const AppProvider = (props) => (
+      <HTMLProvider
+        renderHTML={async (html) => {
+          const { renderHTML } = await import('solid-intlayer/html');
+          return renderHTML(html);
+        }}
+      >
+        {props.children}
+      </HTMLProvider>
+    );
+    ```
+
+    > Importing your HTML renderer dynamically is a good way to reduce the bundle size of your application.
+
   </Tab>
   <Tab label="Angular" value="angular">
 
@@ -354,7 +453,24 @@ You can configure HTML rendering globally for your entire application. This is i
     };
     ```
 
-> Importing your HTML renderer dynamically is a good way to reduce the bundle size of your application.
+    You can also use your own HTML renderer:
+
+    ```typescript fileName="app.config.ts"
+    import { createIntlayerHTMLProvider } from "angular-intlayer/html";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [
+        createIntlayerHTMLProvider({
+          renderHTML: async (html) => {
+            const { renderHTML } = await import('angular-intlayer/html');
+            return renderHTML(html);
+          },
+        }),
+      ],
+    };
+    ```
+
+    > Importing your HTML renderer dynamically is a good way to reduce the bundle size of your application.
 
   </Tab>
 </Tabs>

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

@@ -51,6 +51,7 @@ You can declare Markdown content using the `md` function or simply as a string (
 
 <Tabs>
   <Tab label=".content.md" value=".content.md">
+
     Starting from version `8.10.0`, you can declare Markdown content directly in `.content.md` files. Intlayer will automatically detect and parse the Markdown content.
 
     ```md fileName="markdown-file.en-GB.content.md"
@@ -99,6 +100,7 @@ You can declare Markdown content using the `md` function or simply as a string (
     ```
 
   </Tab>
+
   <Tab label="External Files" value="external-files">
     Import `.md` files directly using the `file` function.
 
@@ -132,6 +134,7 @@ You can declare Markdown content using the `md` function or simply as a string (
     ```
 
   </Tab>
+
 </Tabs>
 
 ## Rendering Markdown
@@ -960,7 +963,21 @@ The `MarkdownProvider` (or its framework equivalent) configures the Markdown ren
   </Tab>
   <Tab label="Angular" value="angular">
 
-> MDX is supported — any component name used inside your Markdown (e.g. `<MyCustomJSXComponent />`) is resolved against the `components` map.
+    ```typescript fileName="app.config.ts"
+    import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [
+        createIntlayerMarkdownProvider({
+          components: {
+            h1: { class: "text-2xl font-bold" },
+          },
+        }),
+      ],
+    };
+    ```
+
+    > MDX is supported — any component name used inside your Markdown (e.g. `<MyCustomJSXComponent />`) is resolved against the `components` map.
 
 You can also use your own markdown renderer:
 

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

@@ -35,9 +35,12 @@ To use plural content in Angular components, retrieve it via the `useIntlayer` h
 
 ## When to Use `plural` vs `enu`
 
-To use plural content inside a React component, retrieve it via the `useIntlayer` hook and call it with a count. The active locale and the count are combined to pick the matching CLDR category.
+| Use case                                                                 | Helper   |
+| ------------------------------------------------------------------------ | -------- |
+| Locale-aware grammatical plural forms (one apple / two apples / 5 яблок) | `plural` |
+| Custom numeric ranges (`<5`, `>=10`) or non-CLDR buckets                 | `enu`    |
 
-To use plural content in Next.js Client Components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+If you only target English (which has just `one` / `other`), either works. For any language with `few` / `many` / `two` distinctions, prefer `plural`.
 
 ## Setting Up Plural Content
 

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

@@ -29,7 +29,6 @@ author: aymericzip
 
 With `react-intlayer`, you can use translations in React components. Here's an example:
 
-  </Tab>
   <Tab label="Next.js" value="nextjs">
 
 ```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
@@ -68,6 +67,7 @@ const MyComponent: Component = () => {
 export default MyComponent;
 ```
 
+  </Tab>
 ## Configuration for Locales
 
 To ensure proper translation handling, you can configure the accepted locales in `intlayer.config.ts`. This configuration allows you to define the languages that your application supports:

package/docs/en-GB/how_works_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-12
-updatedAt: 2025-06-29
+updatedAt: 2026-08-30
 title: How Intlayer Works
 description: Learn how Intlayer operates internally. Understand the architecture and components that make Intlayer powerful.
 keywords:
@@ -259,3 +259,95 @@ The `@intlayer/backend` package exports backend types and will eventually offer
 ## Chat with our smart documentation
 
 - [Ask your questions to our smart documentation](https://intlayer.org/doc/chat)
+
+## Frequently Asked Questions
+
+<FAQ>
+
+<Question title="When are dictionaries built, at build time or at runtime?">
+
+At build time. The bundler plugin, or `npx intlayer build`, scans your `.content.ts` files, resolves them into dictionaries in the `.intlayer` folder, and generates the matching TypeScript types. At runtime your components only read the result, so no parsing or file loading happens on the request path.
+
+</Question>
+
+<Question title="How much does i18n add to my bundle size?">
+
+Much less than a namespace based setup, because a page never downloads a catalogue it does not render. Server rendered markup resolves its content on the server, and the build time compiler replaces `useIntlayer` calls with the exact dictionary entries a component uses, so unused keys and unused languages are dropped. [Dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/index.md) split the rest per locale. Measured against the usual alternatives, Intlayer reduces bundle and page size by up to 50%. See [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/bundle_optimization.md) and the [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/index.md).
+
+</Question>
+
+<Question title="Can I migrate from `i18next`, `next-intl` or `react-i18next` without rewriting my components?">
+
+Yes, and there are two paths. You can migrate the content progressively with the [i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_i18next_to_intlayer.md) or the [next-intl migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_next-intl_to_intlayer.md). Or you can keep your current API entirely: the [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/index.md) expose the exact same API as `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` and `Lingui`, but served by Intlayer dictionaries, so imports change and component code does not.
+
+</Question>
+
+<Question title="Can I keep my existing JSON translation files?">
+
+Yes. The [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-json.md) keeps your `/messages/{locale}/{namespace}.json` files as the source of truth and generates Intlayer dictionaries from them, in both directions. A [sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-po.md) does the same for gettext catalogues, and [per locale files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/per_locale_file.md) let you split content by language instead of grouping locales in one file.
+
+</Question>
+
+<Question title="Do I have to move my content key by key?">
+
+No. Run `npx intlayer extract` and Intlayer reads your source files, pulls the user facing strings out and writes a `.content` file next to each one, so you review a diff instead of copying strings into a catalogue one at a time. See the [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md).
+
+For a fully automated pipeline, the [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compiler.md) does the same at build time on JSX, TSX, Vue and Svelte source, generating the dictionaries on every change so there are no keys to maintain by hand. It works by static analysis, so strings that only exist at runtime stay out of reach, and it needs a few annotations to tell user facing text apart from application logic.
+
+</Question>
+
+<Question title="What editor and AI agent tooling is available?">
+
+Five pieces, all optional:
+
+- **[VS Code extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md)**: jump from a `useIntlayer` key to the content file that declares it, extract content from a component, and run build, fill, test, push and pull from the command palette or a dedicated Intlayer tab.
+- **[LSP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/lsp.md)**: the same awareness in any editor that speaks LSP, with go to definition, find all references, hover previews of a translated value, autocompletion of keys and fields, and a warning when a key is not declared anywhere. It also resolves `i18next`, `react-i18next`, `next-intl` and `use-intl` calls, which helps while you migrate.
+- **[MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/mcp_server.md)**: exposes the Intlayer documentation and CLI to Cursor, VS Code, Claude Desktop, Claude Code and ChatGPT, so an assistant answers from current docs instead of guessing, and can run commands such as `intlayer fill` itself.
+- **[Agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/agent_skills.md)**: focused skills such as `intlayer-config`, `intlayer-cli` and `intlayer-content`, plus one per framework, that teach an agent your routing setup and the content node types.
+- **[ESLint plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/eslint.md)**: `no-raw-text` flags hardcoded strings, with further rules for static dictionary keys and unused content.
+
+</Question>
+
+<Question title="What is the .intlayer folder and should I commit it?">
+
+It is the generated output: the compiled dictionaries and the generated types. It is derived from your content files, so it should be listed in `.gitignore` and rebuilt by your build step, exactly like a `dist` folder.
+
+</Question>
+
+<Question title="How is the active locale determined?">
+
+From the sources listed in `routing.storage`, in order: the URL prefix when `routing.mode` uses one, then a cookie, then the `Accept-Language` header, then your default locale. A locale the user picks explicitly is persisted, so it survives the next visit. See the [configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
+
+</Question>
+
+<Question title="What is the difference between local and remote dictionaries?">
+
+A local dictionary is declared in your code base and compiled with your application. A remote dictionary is managed in the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md) and resolved at runtime, so it can change without a deployment. Both are read through the same hooks, and remote content falls back to the local declaration when it is unavailable.
+
+</Question>
+
+<Question title="Does Intlayer work without TypeScript?">
+
+Yes. Content files can be written in TypeScript, JavaScript, ESM, CommonJS or JSON. TypeScript is what unlocks the generated types and the autocompletion, so it is the recommended setup, but it is not required.
+
+</Question>
+
+<Question title="How do server rendering and client rendering share the same content?">
+
+The server resolves the content of server rendered components directly, so no dictionary is sent to the client for that markup. Client components read the same dictionaries through the provider, which receives the locale resolved on the server, so the first client render matches the server HTML and does not flash a different language.
+
+</Question>
+
+<Question title="How does Intlayer avoid a hydration mismatch on locale?">
+
+The locale is resolved once on the server and passed to the provider, rather than being detected again in the browser. Because the client starts from the same locale the server rendered, the markup matches, which is what usually breaks with client side locale detection.
+
+</Question>
+
+<Question title="Do I need to rebuild when I add a translation?">
+
+In development, no: the plugin watches your content files and rebuilds the affected dictionaries on save. In production the dictionaries are part of the build, unless the content is remote, in which case the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md) and [live sync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/live.md) apply the change without a deployment.
+
+</Question>
+
+</FAQ>

package/docs/en-GB/interest_of_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-14
-updatedAt: 2026-05-31
+updatedAt: 2026-08-30
 title: Interest of Intlayer
 description: Discover the benefits and advantages of using Intlayer in your projects. Understand why Intlayer stands out among other frameworks.
 keywords:
@@ -39,7 +39,6 @@ author: aymericzip
 Compared to main solutions like `next-intl` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
 <AccordionGroup>
-
 <Accordion header="Bundle size">
 
 Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps **reduce your bundle and page sizes by up to 50%**.
@@ -292,3 +291,99 @@ GitHub stars are a strong indicator of a project's popularity, community trust,
 Using `intlayer`, you can declare your content in the format of your favorite i18n library, and intlayer will generate your namespaces in the location of your choice (example: `/messages/{{locale}}/{{namespace}}.json`).
 
 If you want to keep using the API of your current i18n library, `intlayer` also provides **compat adapters**: packages exposing the exact same API as `react-i18next`, `next-intl`, `react-intl`, `vue-i18n`, and more, but served by Intlayer dictionaries. This lets you migrate progressively without rewriting your code. See the [Compat Adapters documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md).
+
+## Frequently Asked Questions
+
+<FAQ>
+
+<Question title="What are the different solutions available to internationalize a JavaScript app?">
+
+Three generations coexist:
+
+- **Runtime catalogue libraries**: `i18next`, `react-i18next`, `next-i18next`, `vue-i18n`, `ngx-translate`, `svelte-i18n`. JSON namespaces loaded at runtime. Mature, framework agnostic, untyped, and shipped whole to the page.
+- **Compile time message libraries**: `Lingui`, `Paraglide`, and `next-intl` or `react-intl` with an extraction step. Better bundle behaviour and partial typing, still a centralized catalogue.
+- **Content layer libraries**: `Intlayer`. Content is declared and compiled per component, so typing, tree shaking, editing tools and AI translation all come from the same declarations.
+
+</Question>
+
+<Question title="How much does i18n add to my bundle size?">
+
+Much less than a namespace based setup, because a page never downloads a catalogue it does not render. Server rendered markup resolves its content on the server, and the build time compiler replaces `useIntlayer` calls with the exact dictionary entries a component uses, so unused keys and unused languages are dropped. [Dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/index.md) split the rest per locale. Measured against the usual alternatives, Intlayer reduces bundle and page size by up to 50%. See [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/bundle_optimization.md) and the [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/index.md).
+
+</Question>
+
+<Question title="Can I migrate from `i18next`, `next-intl` or `react-i18next` without rewriting my components?">
+
+Yes, and there are two paths. You can migrate the content progressively with the [i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_i18next_to_intlayer.md) or the [next-intl migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_next-intl_to_intlayer.md). Or you can keep your current API entirely: the [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/index.md) expose the exact same API as `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` and `Lingui`, but served by Intlayer dictionaries, so imports change and component code does not.
+
+</Question>
+
+<Question title="Can I keep my existing JSON translation files?">
+
+Yes. The [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-json.md) keeps your `/messages/{locale}/{namespace}.json` files as the source of truth and generates Intlayer dictionaries from them, in both directions. A [sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-po.md) does the same for gettext catalogues, and [per locale files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/per_locale_file.md) let you split content by language instead of grouping locales in one file.
+
+</Question>
+
+<Question title="Do I have to move my content key by key?">
+
+No. Run `npx intlayer extract` and Intlayer reads your source files, pulls the user facing strings out and writes a `.content` file next to each one, so you review a diff instead of copying strings into a catalogue one at a time. See the [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md).
+
+For a fully automated pipeline, the [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compiler.md) does the same at build time on JSX, TSX, Vue and Svelte source, generating the dictionaries on every change so there are no keys to maintain by hand. It works by static analysis, so strings that only exist at runtime stay out of reach, and it needs a few annotations to tell user facing text apart from application logic.
+
+</Question>
+
+<Question title="What editor and AI agent tooling is available?">
+
+Five pieces, all optional:
+
+- **[VS Code extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md)**: jump from a `useIntlayer` key to the content file that declares it, extract content from a component, and run build, fill, test, push and pull from the command palette or a dedicated Intlayer tab.
+- **[LSP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/lsp.md)**: the same awareness in any editor that speaks LSP, with go to definition, find all references, hover previews of a translated value, autocompletion of keys and fields, and a warning when a key is not declared anywhere. It also resolves `i18next`, `react-i18next`, `next-intl` and `use-intl` calls, which helps while you migrate.
+- **[MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/mcp_server.md)**: exposes the Intlayer documentation and CLI to Cursor, VS Code, Claude Desktop, Claude Code and ChatGPT, so an assistant answers from current docs instead of guessing, and can run commands such as `intlayer fill` itself.
+- **[Agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/agent_skills.md)**: focused skills such as `intlayer-config`, `intlayer-cli` and `intlayer-content`, plus one per framework, that teach an agent your routing setup and the content node types.
+- **[ESLint plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/eslint.md)**: `no-raw-text` flags hardcoded strings, with further rules for static dictionary keys and unused content.
+
+</Question>
+
+<Question title="How is Intlayer different from next-intl?">
+
+`next-intl` is a message layer for Next.js: you keep JSON message files per locale and read them through `useTranslations`. Intlayer is a content layer: declarations live next to the component, are typed from the declaration itself, and are compiled per component so a page ships only what it renders. Intlayer also covers what `next-intl` leaves to you, namely AI translation, a visual editor, a CMS and missing translation checks in CI. If you want to keep the `next-intl` API, the [compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/index.md) serves it from Intlayer dictionaries.
+
+</Question>
+
+<Question title="How is Intlayer different from i18next and react-i18next?">
+
+`i18next` resolves string keys against namespaces at runtime, which means a renamed or misspelled key fails silently and every namespace a page touches is downloaded in full. Intlayer resolves content at build time against generated types, so a bad key is a compile error, and only the entries a component renders reach the bundle. `i18next` has the larger plugin ecosystem and a longer track record; Intlayer has typing, bundle size, and the editing and automation tooling. See the [i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_i18next_to_intlayer.md) or the [compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/index.md).
+
+</Question>
+
+<Question title="Is Intlayer faster or lighter than the alternatives?">
+
+On bundle and page size, yes: not loading catalogues a page does not render cuts bundle and page size by up to 50% against namespace based setups. The [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/index.md) publishes the method and the numbers per framework, including [Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/nextjs.md), [TanStack Start](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/tanstack.md), [Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/vue.md) and [Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/svelte.md), so you can reproduce them rather than take the claim on trust.
+
+</Question>
+
+<Question title="Is it worth migrating an existing app?">
+
+It depends on what hurts today. If your pain is bundle size, silent missing translations, or translators who cannot work without a developer, the migration pays for itself. If your catalogues are small and stable, the gain is smaller. Either way the migration does not have to be a rewrite: the [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/index.md) keep your current API, and the [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-json.md) keeps your existing JSON files as the source of truth while both layers coexist.
+
+</Question>
+
+<Question title="What does Intlayer offer that other i18n libraries do not?">
+
+[Markdown content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/markdown.md), [content fetched from an external source](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md), file content loading, [live content updates](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/live.md), a [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md), a [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md), a [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compiler.md) that extracts content from existing components, [content variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/variants.md) for A/B testing, [analytics](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/analytics.md) on content exposure, an [MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/mcp_server.md), an [LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/lsp.md) and [agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/agent_skills.md).
+
+</Question>
+
+<Question title="Can I use Intlayer only as a translation manager and keep my current library?">
+
+Yes. Intlayer can generate your namespaces in the format and location your current library expects, for example `/messages/{locale}/{namespace}.json`, so you get the AI translation, the editor and the CI checks while your application code keeps using its existing i18n library.
+
+</Question>
+
+<Question title="Is Intlayer free and open source?">
+
+Yes, under the Apache 2.0 licence, commercial use included. The hosted CMS is an optional paid service that can also be [self hosted](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/self_hosting.md).
+
+</Question>
+
+</FAQ>

package/docs/en-GB/intlayer_CMS.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2026-07-08
+updatedAt: 2026-08-30
 title: Intlayer CMS | Externalise your content into the Intlayer CMS
 description: Externalise your content into the Intlayer CMS to delegate the management of your content to your team.
 keywords:
@@ -431,3 +431,95 @@ If you encounter any issues with the CMS, check the following:
 - Ensure that the project configuration was pushed to the Intlayer CMS.
 
 - The visual editor uses an iframe to display your website. Ensure that the Content Security Policy (CSP) of your website allows the CMS URL as `frame-ancestors` ('https://app.intlayer.org' by default). Check the editor console for any errors.
+
+## Frequently Asked Questions
+
+<FAQ>
+
+<Question title="What is the difference between the Intlayer CMS and the visual editor?">
+
+The [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md) edits local dictionaries and writes the change back into your code base, so the app is rebuilt and the change goes through your normal review and deployment. The CMS edits remote dictionaries: the change does not touch your code base and the running site picks it up without a deployment. Teams often use both, the editor for content owned by developers and the CMS for content that marketing changes weekly.
+
+</Question>
+
+<Question title="How much does i18n add to my bundle size?">
+
+Much less than a namespace based setup, because a page never downloads a catalogue it does not render. Server rendered markup resolves its content on the server, and the build time compiler replaces `useIntlayer` calls with the exact dictionary entries a component uses, so unused keys and unused languages are dropped. [Dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/index.md) split the rest per locale. Measured against the usual alternatives, Intlayer reduces bundle and page size by up to 50%. See [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/bundle_optimization.md) and the [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/index.md).
+
+</Question>
+
+<Question title="Can I migrate from `i18next`, `next-intl` or `react-i18next` without rewriting my components?">
+
+Yes, and there are two paths. You can migrate the content progressively with the [i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_i18next_to_intlayer.md) or the [next-intl migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_next-intl_to_intlayer.md). Or you can keep your current API entirely: the [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/index.md) expose the exact same API as `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` and `Lingui`, but served by Intlayer dictionaries, so imports change and component code does not.
+
+</Question>
+
+<Question title="Can I keep my existing JSON translation files?">
+
+Yes. The [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-json.md) keeps your `/messages/{locale}/{namespace}.json` files as the source of truth and generates Intlayer dictionaries from them, in both directions. A [sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-po.md) does the same for gettext catalogues, and [per locale files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/per_locale_file.md) let you split content by language instead of grouping locales in one file.
+
+</Question>
+
+<Question title="Do I have to move my content key by key?">
+
+No. Run `npx intlayer extract` and Intlayer reads your source files, pulls the user facing strings out and writes a `.content` file next to each one, so you review a diff instead of copying strings into a catalogue one at a time. See the [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md).
+
+For a fully automated pipeline, the [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compiler.md) does the same at build time on JSX, TSX, Vue and Svelte source, generating the dictionaries on every change so there are no keys to maintain by hand. It works by static analysis, so strings that only exist at runtime stay out of reach, and it needs a few annotations to tell user facing text apart from application logic.
+
+</Question>
+
+<Question title="What editor and AI agent tooling is available?">
+
+Five pieces, all optional:
+
+- **[VS Code extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md)**: jump from a `useIntlayer` key to the content file that declares it, extract content from a component, and run build, fill, test, push and pull from the command palette or a dedicated Intlayer tab.
+- **[LSP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/lsp.md)**: the same awareness in any editor that speaks LSP, with go to definition, find all references, hover previews of a translated value, autocompletion of keys and fields, and a warning when a key is not declared anywhere. It also resolves `i18next`, `react-i18next`, `next-intl` and `use-intl` calls, which helps while you migrate.
+- **[MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/mcp_server.md)**: exposes the Intlayer documentation and CLI to Cursor, VS Code, Claude Desktop, Claude Code and ChatGPT, so an assistant answers from current docs instead of guessing, and can run commands such as `intlayer fill` itself.
+- **[Agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/agent_skills.md)**: focused skills such as `intlayer-config`, `intlayer-cli` and `intlayer-content`, plus one per framework, that teach an agent your routing setup and the content node types.
+- **[ESLint plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/eslint.md)**: `no-raw-text` flags hardcoded strings, with further rules for static dictionary keys and unused content.
+
+</Question>
+
+<Question title="Which content should be moved to the CMS?">
+
+Content that changes often and does not belong to a release: landing page copy, pricing wording, announcements, anything a marketing team owns. Content that is part of the interface, such as button labels and form errors, is better left as local dictionaries, where it is reviewed with the code that uses it.
+
+</Question>
+
+<Question title="What happens if the CMS is unreachable?">
+
+The application falls back to the local declaration of the dictionary, so a network failure or an outage degrades to the content shipped with your build rather than to an empty page. This is why keeping a local declaration for every remote dictionary matters.
+
+</Question>
+
+<Question title="Can I self host the CMS?">
+
+Yes. The CMS can run on your own infrastructure, which is the usual answer when content must not leave your network. See [self hosting Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/self_hosting.md).
+
+</Question>
+
+<Question title="Do content editors need a developer to publish a change?">
+
+No. That is the point of remote dictionaries: an editor changes the text in the CMS and the site reflects it, with [live sync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/live.md) applying the update at runtime instead of waiting for a build.
+
+</Question>
+
+<Question title="Can I automate the CMS instead of using the interface?">
+
+Yes. The `@intlayer/api` SDK exposes the same endpoints as the interface, so you can fetch projects, read dictionaries and push updates from a script or a pipeline. The section above shows the authenticator and the endpoints.
+
+</Question>
+
+<Question title="Does the CMS support A/B testing translations?">
+
+Yes. Remote dictionaries support [content variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/variants.md), and [analytics](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/analytics.md) reports how each variant is exposed, so a wording change can be measured rather than argued about.
+
+</Question>
+
+<Question title="Is the CMS free?">
+
+The Intlayer library, CLI, compiler and visual editor are free and open source under the Apache 2.0 licence. The hosted CMS is an optional paid service, and it can be [self hosted](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/self_hosting.md) instead.
+
+</Question>
+
+</FAQ>