@intlayer/docs 8.9.4-canary.0 → 8.9.5

package/docs/en-GB/mcp_server.md

@@ -23,7 +23,7 @@ history:
     changes: "Add set up of Claude Desktop"
   - version: 5.5.12
     date: 2025-07-10
-    changes: "Add SSE transport and distant server"
+    changes: "Add Streamable HTTP transport and distant server"
   - version: 5.5.10
     date: 2025-06-29
     changes: "Initialise history"
@@ -51,12 +51,12 @@ By enabling the Intlayer MCP Server in your IDE, you unlock:
 
   > View the full list of commands and options in the [Intlayer CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/index.md).
 
-## Local server (stdio) vs Remote server (SSE)
+## Local server (stdio) vs Remote server (Streamable HTTP)
 
 The MCP server can be used in two ways:
 
 - Local server (stdio)
-- Remote server (SSE)
+- Remote server (Streamable HTTP)
 
 ### Local server (stdio) (recommended)
 
@@ -64,9 +64,9 @@ Intlayer provides an NPM package that can be installed locally on your machine.
 
 This server is the recommended way to use the MCP server, as it integrates all the features of the MCP server, including the CLI tools.
 
-### Remote server (SSE)
+### Remote server (Streamable HTTP)
 
-The MCP server can also be used remotely, using the SSE transport method. This server is hosted by Intlayer and is available at https://mcp.intlayer.org. This server can be accessed publicly, without any authentication, and is free to use.
+The MCP server can also be used remotely, using the Streamable HTTP transport method. This server is hosted by Intlayer and is available at https://mcp.intlayer.org. This server can be accessed publicly, without any authentication, and is free to use.
 
 Note that the remote server does not integrate CLI tools, AI autocompletion, etc. The remote server is only for interaction with the documentation to assist your AI assistant with the Intlayer ecosystem.
 
@@ -97,7 +97,7 @@ bun x intlayer init mcp
 This command will:
 
 1. Ask you which platform you are using (Cursor, VS Code, Claude Desktop, etc.).
-2. Ask you which transport method you want to use (Local server (stdio) or Remote server (SSE)).
+2. Ask you which transport method you want to use (Local server (stdio) or Remote server (Streamable HTTP)).
 3. Automatically update your configuration file (e.g., `.cursor/mcp.json`, `.vscode/mcp.json`, or the global Claude Desktop config).
 
 ---
@@ -107,7 +107,7 @@ This command will:
 1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
 2. Type `Intlayer: Setup AI Agent Skills`
 3. Pick the platform you use (e.g. `VS Code`, `Cursor`, `Windsurf`, `OpenCode`, `Claude Code`, `GitHub Copilot Workspace`, etc.).
-4. Pick the MCP to install (stdio, SSE)
+4. Pick the MCP to install (stdio, Streamable HTTP)
 5. Press Enter.
 
 ---
@@ -131,16 +131,16 @@ In your project root, add the following `.cursor/mcp.json` configuration file:
 }
 ```
 
-### Remote server (SSE)
+### Remote server (Streamable HTTP)
 
-For connecting to a remote Intlayer MCP server using Server-Sent Events (SSE), you can configure your MCP client to connect to the hosted service.
+For connecting to a remote Intlayer MCP server using Server-Sent Events (Streamable HTTP), you can configure your MCP client to connect to the hosted service.
 
 ```json fileName=".cursor/mcp.json"
 {
   "mcpServers": {
-    "intlayer": {
-      "url": "https://mcp.intlayer.org",
-      "transport": "sse"
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
     }
   }
 }
@@ -172,16 +172,16 @@ Create a `.vscode/mcp.json` file in your project root:
 }
 ```
 
-### Remote server (SSE)
+### Remote server (Streamable HTTP)
 
-For connecting to a remote Intlayer MCP server using Server-Sent Events (SSE), you can configure your MCP client to connect to the hosted service.
+For connecting to a remote Intlayer MCP server using Server-Sent Events (Streamable HTTP), you can configure your MCP client to connect to the hosted service.
 
 ```json fileName=".vscode/mcp.json"
 {
   "servers": {
-    "intlayer": {
-      "url": "https://mcp.intlayer.org",
-      "type": "sse"
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
     }
   }
 }
@@ -191,7 +191,7 @@ For connecting to a remote Intlayer MCP server using Server-Sent Events (SSE), y
 
 ## Set Up in ChatGPT
 
-### Remote server (SSE)
+### Remote server (Streamable HTTP)
 
 Follow the [official documentation](https://platform.openai.com/docs/mcp#test-and-connect-your-mcp-server) to configure the MCP server in ChatGPT.
 
@@ -232,6 +232,19 @@ Path of the config file:
 }
 ```
 
+### Remote server (Streamable HTTP)
+
+```json fileName="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "intlayer-sse": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote@latest", "https://mcp.intlayer.org"]
+    }
+  }
+}
+```
+
 ---
 
 ## Using the MCP Server via CLI

package/docs/en-GB/plugins/sync-po.md

@@ -0,0 +1,333 @@
+---
+createdAt: 2026-05-10
+updatedAt: 2026-05-10
+title: Sync PO plugin
+description: Synchronise Intlayer dictionaries with Gettext PO files. Keep your existing i18n while using Intlayer to manage, translate, and test your messages.
+keywords:
+  - Intlayer
+  - Sync PO
+  - Gettext
+  - i18n
+  - translations
+slugs:
+  - doc
+  - plugin
+  - sync-po
+youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
+history:
+  - version: 8.9.4
+    date: 2026-05-10
+    changes: "Initial Sync PO plugin documentation"
+---
+
+# Sync PO (i18n bridges) - Sync PO with ICU / i18next support
+
+Use Intlayer as an add‑on to your existing i18n stack. This plugin keeps your Gettext PO messages in sync with Intlayer dictionaries so you can:
+
+- Keep your existing PO-based translation workflow.
+- Manage and translate your messages with Intlayer (CLI, CI, providers, CMS), without refactoring your app.
+- Ship tutorials and SEO content targeting each ecosystem, while suggesting Intlayer as the PO management layer.
+
+Notes and current scope:
+
+- Externalisation to the CMS works for translations and classic text.
+- No support yet for insertions, plurals/ICU, or advanced runtime features of other libraries within the PO entries themselves.
+- The visual editor is not supported yet for third‑party i18n outputs.
+
+### When to use this plugin
+
+- You already use Gettext PO files for your translations.
+- You want AI‑assisted fill, test in CI, and content ops without changing your rendering runtime.
+
+## Installation
+
+```bash
+pnpm add -D @intlayer/sync-po-plugin
+# or
+npm i -D @intlayer/sync-po-plugin
+```
+
+## Plugins
+
+This package provides two plugins:
+
+- `loadPO`: Load PO files into Intlayer dictionaries.
+  - This plugin is used to load PO files from a source and will be loaded into Intlayer dictionaries. It can scan all the codebase and search for specific PO files.
+    This plugin can be used
+    - if you use an i18n library that imposes a specific location for your PO files to be loaded, but you want to place your content declaration where you want in your code base.
+    - It can also be used if you want to fetch your messages from a remote source (ex: a CMS, an API, etc.) and store your messages in PO files.
+
+  > Under the bonnet, this plugin will scan all the codebase and search for specific PO files and load them into Intlayer dictionaries.
+  > Note that this plugin will not write the output and translations back to the PO files.
+
+- `syncPO`: Synchronise PO files with Intlayer dictionaries.
+  - This plugin is used to synchronise PO files with Intlayer dictionaries. It can scan the given location and load the PO that match the pattern for specific PO files. This plugin is useful if you want to get the benefits of Intlayer while using another i18n library.
+
+## Using both plugins
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO, syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Keep your current PO files in sync with Intlayer dictionaries
+  plugins: [
+    /**
+     * Will load all the PO files in the src that match the pattern {key}.i18n.po
+     */
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Ensures these PO files take precedence over files at `./locales/en/${key}.po`
+    }),
+    /**
+     * Will load, and write the output and translations back to the PO files in the locales directory
+     */
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncPO` plugin
+
+### Quick start
+
+Add the plugin to your `intlayer.config.ts` and point it at your existing PO structure.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Keep your current PO files in sync with Intlayer dictionaries
+  plugins: [
+    syncPO({
+      // Per-locale, per-namespace layout
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternative: single file per locale:
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncPO({
+      source: ({ locale }) => `./locales/${locale}.po`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+#### How it works
+
+- Read: the plugin discovers PO files from your `source` builder and loads them as Intlayer dictionaries.
+- Write: after builds and fills, it writes localised PO back to the same paths (with proper Gettext headers).
+- Auto‑fill: the plugin declares an `autoFill` path for each dictionary. Running `intlayer fill` updates only missing translations in your PO files by default.
+
+API:
+
+```ts
+syncPO({
+  source: ({ key, locale }) => string, // required
+  location?: string, // optional label, default: "sync-po::path/to/source"
+  priority?: number, // optional priority for conflict resolution, default: 0
+});
+```
+
+### Multiple PO sources and priority
+
+You can add multiple `syncPO` plugins to synchronise different PO sources. This is useful when you have multiple translation sources or different PO structures in your project.
+
+#### Priority system
+
+When multiple plugins target the same dictionary key, the `priority` parameter determines which plugin takes precedence:
+
+- Higher priority numbers win over lower ones
+- Default priority of `.content` files is `0`
+- Default priority of plugins is `0`
+- Plugins with the same priority are processed in the order they appear in the configuration
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Primary PO source (highest priority)
+    syncPO({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Fallback PO source (lower priority)
+    syncPO({
+      source: ({ locale }) => `./fallback-locales/${locale}.po`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Legacy PO source (lowest priority)
+    syncPO({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.po`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+};
+
+export default config;
+```
+
+## Load PO plugin
+
+### Quick start
+
+Add the plugin to your `intlayer.config.ts` to ingest existing PO files as Intlayer dictionaries. This plugin is read‑only (no writes to disk):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Ingest PO messages located anywhere in your source tree
+    loadPO({
+      source: ({ key }) => `./src/**/${key}.i18n.po`,
+      // Load a single locale per plugin instance (defaults to the config defaultLocale)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
+
+export default config;
+```
+
+Alternative: per‑locale layout, still read‑only (only the selected locale is loaded):
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadPO } from "@intlayer/sync-po-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    loadPO({
+      // Only files for Locales.FRENCH will be loaded from this pattern
+      source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
+      locale: Locales.FRENCH,
+    }),
+  ],
+};
+
+export default config;
+```
+
+### How it works
+
+- Discover: builds a glob from your `source` builder and collects matching PO files.
+- Ingest: loads each PO file as an Intlayer dictionary with the provided `locale`.
+- Read‑only: does not write or format output files; use `syncPO` if you need round‑trip sync.
+- Auto‑fill ready: defines a `fill` path so `intlayer content fill` can populate missing keys.
+
+### API
+
+```ts
+loadPO({
+  // Build paths to your PO. `locale` is optional if your structure has no locale segment
+  source: ({ key, locale }) => string,
+
+  // Target locale for the dictionaries loaded by this plugin instance
+  // Defaults to configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Optional label to identify the source
+  location?: string, // default: "plugin"
+
+  // Priority used for conflict resolution against other sources
+  priority?: number, // default: 0
+});
+```
+
+### Behaviour and conventions
+
+- If your `source` mask includes a locale placeholder, only files for the selected `locale` are ingested.
+- If there is no `{key}` segment in your mask, the dictionary key is "index".
+- Keys are derived from file paths by substituting the `{key}` placeholder in your `source` builder.
+- The plugin only uses discovered files and does not fabricate missing locales or keys.
+- The `fill` path is inferred from your `source` and used to update missing values via CLI when you opt‑in.
+
+## Conflict resolution
+
+When the same translation key exists in multiple PO sources:
+
+1. The plugin with the highest priority determines the final value
+2. Lower priority sources are used as fallbacks for missing keys
+3. This allows you to maintain legacy translations while gradually migrating to new structures
+
+## CLI
+
+The synchronised PO files will be considered as other `.content` files. That means, all intlayer commands will be available for the synchronised PO files. Including:
+
+- `intlayer content test` to test if there are missing translations
+- `intlayer content list` to list the synchronised PO files
+- `intlayer content fill` to fill the missing translations
+- `intlayer content push` to push the synchronised PO files
+- `intlayer content pull` to pull the synchronised PO files
+
+See [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md) for more details.
+
+## Limitations (current)
+
+- No insertions or plurals/ICU support when targeting third‑party libraries.
+- Visual editor is not available for non‑Intlayer runtimes yet.
+- PO synchronisation only; non‑PO catalog formats are not supported.
+
+## Why this matters
+
+- We can recommend established i18n solutions and position Intlayer as an add‑on.
+- We leverage their SEO/keywords with tutorials that end by suggesting Intlayer to manage PO.
+- Expands the addressable audience from “new projects” to “any team already using i18n”.

package/docs/es/benchmark/index.md

@@ -30,6 +30,3 @@ A continuación encontrarás los informes detallados y la documentación técnic
 - [**Vue Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/vue.md)
 - [**Solid Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/solid.md)
 - [**Svelte Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/svelte.md)
-- [**Vue Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/vue.md)
-- [**Solid Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/solid.md)
-- [**Svelte Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/svelte.md)

package/docs/es/benchmark/nextjs.md

@@ -61,6 +61,13 @@ Debido a que el problema es difícil, existen muchas soluciones: algunas enfocad
 
 Intlayer intenta optimizar en todas estas dimensiones.
 
+## TL;DR
+
+- **Intlayer** y **next-translate**: Las mejores opciones para el rendimiento en Next.js, ofreciendo la menor huella y el mejor soporte para renderizado estático.
+- **next-intl**: La opción más de moda pero pesada y compleja de optimizar para aplicaciones grandes.
+- **next-i18next**: Popular y rica en plugins, pero conlleva un peso de bundle significativo (~3× Intlayer).
+- **Evitar**: **gt-next** y **lingo.dev** debido a graves problemas de rendimiento, bloqueo del proveedor (vendor lock-in) y errores que rompen la compilación.
+
 ## Pon a prueba tu aplicación
 
 Para sacar a la luz estos problemas, he creado un escáner gratuito que puedes probar [aquí](https://intlayer.org/i18n-seo-scanner).
@@ -99,14 +106,14 @@ Finalmente, `Intlayer` aplica una optimización en tiempo de compilación para q
 Para este benchmark, comparamos las siguientes librerías:
 
 - `Base App` (Sin librería i18n)
-- `next-intlayer` (v8.7.5)
+- `next-intlayer` (v8.7.12)
 - `next-i18next` (v16.0.5)
 - `next-intl` (v4.9.1)
 - `@lingui/core` (v5.3.0)
 - `next-translate` (v3.1.2)
 - `next-international` (v1.3.1)
 - `@inlang/paraglide-js` (v2.15.1)
-- `tolgee` (v7.0.0)
+- `@tolgee/react` (v7.0.0)
 - `@lingo.dev/compiler` (v0.4.0)
 - `wuchale` (v0.22.11)
 - `gt-next` (v6.16.5)
@@ -161,10 +168,10 @@ Problemas encontrados:
 
 **(General Translation)** (`gt-next@6.16.5`):
 
-- Para una aplicación de 110kb, `gt-react` añade más de 440kb extra.
+- Para una aplicación de 110kb, `gt-next` añade más de 440kb extra.
 - `Quota Exceeded, please upgrade your plan` en la primerísima compilación con General Translation.
 - Las traducciones no se renderizan; obtengo el error `Error: <T> used on the client-side outside of <GTProvider>`, lo que parece ser un bug de la librería.
-- Mientras implementaba **gt-tanstack-start-react**, también encontré un [problema](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) con la librería: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, que hacía que la aplicación se rompiera. Tras informar de este problema, el mantenedor lo solucionó en 24 horas.
+- Mientras implementaba **gt-next**, también encontré un [problema](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) con la librería: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, que hacía que la aplicación se rompiera. Tras informar de este problema, el mantenedor lo solucionó en 24 horas.
 - La librería bloquea el renderizado estático de las páginas de Next.js.
 
 **(Lingo.dev)** (`@lingo.dev/compiler@0.4.0`):
@@ -185,9 +192,11 @@ La idea detrás de `Wuchale` es interesante pero aún no es viable. Experimenté
 `Paraglide` ofrece un enfoque innovador y bien pensado. Aun así, en este benchmark, el tree-shaking que su empresa anuncia no funcionó para mis configuraciones de Next.js o TanStack Start. El flujo de trabajo y la DX son más complejos que otras opciones. Personalmente, no me gusta tener que regenerar archivos JS antes de cada push, lo que crea un riesgo constante de conflictos de fusión a través de las PR. La herramienta también parece más enfocada en Vite que en Next.js.
 Finalmente, en comparación con otras soluciones, Paraglide no usa un almacén (ej. contexto de React) para recuperar el idioma actual y renderizar el contenido. Por cada nodo analizado, solicita el idioma al localStorage / cookie, etc. Esto provoca la ejecución de lógica innecesaria que afecta a la reactividad del componente.
 
+> Nota sobre paraglide: la solución inyecta código en tu base de código para importar, como resultado la métrica 'tamaño de la lib' en el informe del benchmark es casi 0. La generación de código es algo bueno, porque la función utilizada incluirá solo la lógica necesaria (prefijo total vs sin prefijo, cookie vs almacenamiento, etc.). En comparación, Intlayer realiza este filtrado mediante inyecciones de variables de entorno en la compilación para forzar al bundler a aplicar tree-shaking al contenido según la lógica. Gracias a esto, paraglide e intlayer terminan siendo soluciones de 6 a 10 veces más ligeras que i18next o next-intl.
+
 ### 3 — Soluciones aceptables
 
-**(Tolgee)** (`tolgee@7.0.0`):
+**(Tolgee)** (`@tolgee/react@7.0.0`):
 
 `Tolgee` aborda muchos de los problemas mencionados anteriormente. Me resultó más difícil de adoptar que herramientas similares. No proporciona seguridad de tipos (type safety), lo que también dificulta detectar claves faltantes en tiempo de compilación. Tuve que envolver las funciones de Tolgee con las mías propias para añadir la detección de claves faltantes.
 
@@ -215,7 +224,7 @@ A menudo se elogia a `Lingui`. Personalmente, encontré el flujo de trabajo `lin
 
 `next-translate` es mi recomendación principal si te gusta una API de estilo `t()`. Es elegante a través de `next-translate-plugin`, cargando namespaces mediante `getStaticProps` con un cargador de Webpack / Turbopack. También es la opción más ligera aquí (~2.5kb). Para la segmentación por espacios de nombres, definirnamespaces por página o ruta en la configuración está bien pensado y es más fácil de mantener que las principales alternativas como **next-intl** o **next-i18next**. En la versión `3.1.2`, noté que el renderizado estático no funcionaba; Next.js recurría al renderizado dinámico.
 
-**(Intlayer)** (`next-intlayer@8.7.5`):
+**(Intlayer)** (`next-intlayer@8.7.12`):
 
 No seré yo quien juzgue personalmente a `next-intlayer` por objetividad, ya que es mi propia solución.