@intlayer/docs 8.9.4-canary.0 → 8.9.5

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

@@ -0,0 +1,333 @@
+---
+createdAt: 2026-05-10
+updatedAt: 2026-05-10
+title: Sync PO plugin
+description: Synchronize 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:
+
+- Externalization 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 hood, 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`: Synchronize PO files with Intlayer dictionaries.
+  - This plugin is used to synchronize 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 localized 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 synchronize 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
+});
+```
+
+### Behavior 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 synchronized PO files will be considered as other `.content` files. That means, all intlayer commands will be available for the synchronized PO files. Including:
+
+- `intlayer content test` to test if there are missing translations
+- `intlayer content list` to list the synchronized PO files
+- `intlayer content fill` to fill the missing translations
+- `intlayer content push` to push the synchronized PO files
+- `intlayer content pull` to pull the synchronized 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 synchronization 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/en-GB/benchmark/index.md

@@ -30,6 +30,3 @@ Find the detailed reports and technical documentation for each framework below:
 - [**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/en-GB/benchmark/nextjs.md

@@ -61,6 +61,13 @@ Because the problem is hard, many solutions exist—some focused on DX, others o
 
 Intlayer tries to optimise across these dimensions.
 
+## TL;DR
+
+- **Intlayer** & **next-translate**: Best choices for Next.js performance, offering the smallest footprint and best static rendering support.
+- **next-intl**: The trendiest option, but heavy and complex to optimise for large applications.
+- **next-i18next**: Popular and plugin-rich, but carries significant bundle weight (~3× Intlayer).
+- **Avoid**: **gt-next** and **lingo.dev** due to severe performance issues, vendor lock-in, and build-breaking bugs.
+
 ## Test your app
 
 To surface these issues, I built a free scanner you can try [here](https://intlayer.org/i18n-seo-scanner).
@@ -99,14 +106,14 @@ Finally, `Intlayer` applies a build-time optimisation so `useIntlayer('my-key')`
 For this benchmark, we compared the following libraries:
 
 - `Base App` (No i18n library)
-- `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 @@ Issues encountered:
 
 **(General Translation)** (`gt-next@6.16.5`):
 
-- For a 110kb app, `gt-react` adds more than 440kb extra.
+- For a 110kb app, `gt-next` adds more than 440kb extra.
 - `Quota Exceeded, please upgrade your plan` on the very first build with General Translation.
 - Translations are not rendered; I get the error `Error: <T> used on the client-side outside of <GTProvider>`, which seems to be a bug in the library.
-- While implementing **gt-tanstack-start-react**, I also came across an [issue](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) with the library: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, which was making the application break. After reporting this issue, the maintainer fixed it within 24 hours.
+- While implementing **gt-next**, I also came across an [issue](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) with the library: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, which was making the application break. After reporting this issue, the maintainer fixed it within 24 hours.
 - The library blocks static rendering of Next.js pages.
 
 **(Lingo.dev)** (`@lingo.dev/compiler@0.4.0`):
@@ -187,9 +194,11 @@ Personally I dislike having to regenerate JS files before every push, which crea
 Even if in theory the tree-shaking strategy works, it does includes all locales in the bundle anyway. Paraglide offers not way to lazy-load the content. That says your page size will grow up correlated to the number of locales you have.
 Finally, in comparison of other solutions, Paraglide does not use store (e.g. React context) to retrieve the current locale to render the content. For each node parsed, it will request the locale from the localeStorage / cookie etc. It leads to execution of unnecessary logic that impact the component reactivity.
 
+> Note on paraglide: the solution injects code into your codebase for import, as a result the 'lib size' metric in the benchmark report is nearly 0. Code generation is a good thing, because the function used will include only the necessary logic (all prefixes vs no prefixes, cookies vs storage, etc.). In comparison, Intlayer performs this filtering via environment variable injections in the build to force the bundler to tree-shake content depending on the logic. Thanks to this, paraglide and intlayer end up being 6 to 10 times lighter solutions than i18next or next-intl.
+
 ### 3 — Acceptable solutions
 
-**(Tolgee)** (`tolgee@7.0.0`):
+**(Tolgee)** (`@tolgee/react@7.0.0`):
 
 `Tolgee` addresses many of the issues mentioned earlier. I found it harder to adopt than similar tools. It does not provide type safety, which also makes catching missing keys at compile time harder. I had to wrap Tolgee’s functions with my own to add missing-key detection.
 
@@ -217,7 +226,7 @@ Message formats also differ: `next-intl` uses ICU MessageFormat, while `i18next`
 
 `next-translate` is my main recommendation if you like a `t()`-style API. It is elegant via `next-translate-plugin`, loading namespaces through `getStaticProps` with a Webpack / Turbopack loader. It is also the lightest option here (~2.5kb). For namespacing, defining namespaces per page or route in config is well thought out and easier to maintain than main alternatives like **next-intl** or **next-i18next**. In version `3.1.2`, I noted that static rendering did not work; Next.js fell back to dynamic rendering.
 
-**(Intlayer)** (`next-intlayer@8.7.5`):
+**(Intlayer)** (`next-intlayer@8.7.12`):
 
 I will not personally judge `next-intlayer` for objectivity’s sake, since it is my own solution.
 

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

@@ -0,0 +1,155 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Best i18n solution for Solid in 2026 - Benchmark Report
+description: Compare Solid internationalisation (i18n) libraries like solid-primitives, solid-i18next, and Intlayer. Detailed performance report on bundle size, leakage, and reactivity.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - solid
+  - performance
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - solid
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n-solid-template
+history:
+  - version: 8.7.12
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Solid i18n Libraries — 2026 Benchmark Report
+
+This page is a benchmark report for i18n solutions on Solid.
+
+## Table of Contents
+
+<Toc/>
+
+## Interactive Benchmark
+
+<I18nBenchmark framework="vite-solid" vertical/>
+
+## Results reference:
+
+<iframe 
+  src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vite_solid.md" 
+  width="100%" 
+  height="600px"
+  style="border:none;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vite_solid.md
+
+See complete benchmark repository [here](https://github.com/intlayer-org/benchmark-i18n/tree/main).
+
+## Introduction
+
+Internationalisation solutions are among the heaviest dependencies in a Solid app. The main risk is shipping unnecessary content: translations for other pages and other locales in a single route’s bundle.
+
+As your app grows, that problem can quickly blow up the JavaScript sent to the client and slow down navigation.
+
+In practice, for the least optimised implementations, an internationalised page can end up several times heavier than the version without i18n.
+
+The other impact is on developer experience: how you declare content, types, namespace organisation, dynamic loading, and reactivity when the locale changes.
+
+## TL;DR
+
+- **Intlayer**: Recommended choice for professional Solid applications needing advanced features and optimisation (v8.7.12).
+- **@solid-primitives/i18n**: Excellent lightweight alternative for simple projects, though lacks advanced features like lazy loading.
+- **solid-i18next**: Standard but heavy option (~4.7× Intlayer) with same downsides as React i18next.
+- **Paraglide**: Innovative approach but complex DX and tree-shaking issues in some setups.
+
+## Test your app
+
+To quickly spot i18n leakage issues, I set up a free scanner available [here](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## The problem
+
+Two levers are essential to limit the cost of a multilingual app:
+
+- Split content by page / namespace so you do not load whole dictionaries when you do not need them
+- Load the right locale dynamically, only when needed
+
+Understanding the technical limitations of these approaches:
+
+**Dynamic loading**
+
+Without dynamic loading, most solutions keep messages in memory from the first render, which adds significant overhead for apps with many routes and locales.
+
+With dynamic loading, you accept a trade-off: less initial JS, but sometimes an extra request when switching language.
+
+**Content splitting**
+
+Syntaxes built around `t('a.b.c')` are very convenient but often encourage keeping large JSON objects at runtime. That model makes tree-shaking hard unless the library offers a real per-page split strategy.
+
+## Methodology
+
+For this benchmark, we compared the following libraries:
+
+- `Base App` (No i18n library)
+- `solid-intlayer` (v8.7.12)
+- `@solid-primitives/i18n` (v2.2.1)
+- `solid-i18next` (v17.0.2)
+- `@inlang/paraglide-js` (v2.17.0)
+
+The framework is `Solid` with a multilingual app of **10 pages** and **10 languages**.
+
+We compared **four loading strategies**:
+
+| Strategy            | No namespaces (global)                       | With namespaces (scoped)                                             |
+| :------------------ | :------------------------------------------- | :------------------------------------------------------------------- |
+| **Static loading**  | **Static**: Everything in memory at startup. | **Scoped static**: Split by namespace; everything loaded at startup. |
+| **Dynamic loading** | **Dynamic**: On-demand loading per locale.   | **Scoped dynamic**: Granular loading per namespace and locale.       |
+
+## Strategy summary
+
+- **Static**: Simple; no network latency after the initial load. Downside: large bundle size.
+- **Dynamic**: Reduces initial weight (lazy-loading). Ideal when you have many locales.
+- **Scoped static**: Keeps code organised (logical separation) without complex extra network requests.
+- **Scoped dynamic**: Best approach for _code splitting_ and performance. Minimises memory by loading only what the current view and active locale need.
+
+## Results in detail
+
+### 1 — Solutions to avoid
+
+> No clear solution to avoid in solid ecosystem.
+
+### 2 — Acceptable solutions
+
+**(solid-i18next)** (`solid-i18next@17.0.2`):
+
+`solid-i18next` is probably the most popular option because it was among the first to serve JavaScript app i18n needs. It also has a wide set of community plugins for specific problems.
+
+The package is heavy (~14.6kb, which is about 4.7× `solid-intlayer`).
+
+Still, it shares the same major downsides as stacks built on `t('a.b.c')`: optimisations are possible but very time-consuming, and large projects risk bad practices (namespaces + dynamic loading + types).
+
+**(@solid-primitives/i18n)** (`@solid-primitives/i18n@2.2.1`):
+
+Solid primitive is extremely light and efficient. I recommend that solution for light projects, but it can quickly become lacking features for professional solutions including cookie management, proxy redirection, formatters etc.
+It also misses lazy loading and scoping namespaces for page size optimisation.
+
+**(Paraglide)** (`@inlang/paraglide-js@2.17.0`):
+
+`Paraglide` offers an innovative, well-thought-out approach. Even so, in this benchmark the tree-shaking their company advertises did not work for my implementation. The workflow and DX are also more complex than other options.
+Personally I dislike having to regenerate JS files before every push, which creates constant merge conflict risk via PRs.
+Finally, in comparison with other solutions, Paraglide does not use a store (e.g. Solid signal) to retrieve the current locale to render the content. For each node parsed, it will request the locale from the localStorage / cookie etc. It leads to execution of unnecessary logic that impacts the component reactivity.
+
+### 3 — Recommendations
+
+**(Intlayer)** (`solid-intlayer@8.7.12`):
+
+I will not personally judge `solid-intlayer` for objectivity’s sake, since it is my own solution.
+
+### Personal note
+
+This note is personal and does not affect the benchmark results. Still, in the i18n world you often see consensus around a pattern like `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` for translated content.
+
+In Solid apps, injecting a function as a `JSX.Element` is, in my view, an anti-pattern. It also adds avoidable complexity and JavaScript execution overhead (even if it is barely noticeable).