@intlayer/docs 8.9.4 → 8.9.6-canary.0

package/docs/en/dictionary/content_file.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-02-07
-updatedAt: 2026-01-28
+updatedAt: 2026-05-12
 title: Content File
 description: Learn how to customize the extensions for your content declaration files. Follow this documentation to implement conditions efficiently in your project.
 keywords:
@@ -12,6 +12,9 @@ slugs:
   - concept
   - content
 history:
+  - version: 8.9.0
+    date: 2026-05-12
+    changes: "Add `plural` content node type"
   - version: 8.0.0
     date: 2026-01-28
     changes: "Add `html` content node type"
@@ -69,6 +72,7 @@ import { type ReactNode } from "react";
 import {
   t,
   enu,
+  plural,
   cond,
   nest,
   md,
@@ -88,6 +92,7 @@ interface Content {
   };
   multilingualContent: string;
   quantityContent: string;
+  pluralContent: string;
   conditionalContent: string;
   markdownContent: never;
   htmlContent: never;
@@ -123,6 +128,10 @@ export default {
       ">5": "Some cars",
       ">19": "Many cars",
     }),
+    pluralContent: plural({
+      one: "One car",
+      other: "{{count}} cars",
+    }),
     conditionalContent: cond({
       true: "Validation is enabled",
       false: "Validation is disabled",
@@ -178,6 +187,13 @@ export default {
         ">19": "Many cars",
       },
     },
+    "pluralContent": {
+      "nodeType": "plural",
+      "plural": {
+        "one": "One car",
+        "other": "{{count}} cars",
+      },
+    },
     "conditionalContent": {
       "nodeType": "condition",
       "condition": {
@@ -233,6 +249,7 @@ Intlayer supports various content types through typed nodes:
 - **Translation Content**: Multilingual text with locale-specific values [see Translation Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/translation_content.md)
 - **Condition Content**: Conditional content based on boolean expressions [see Condition Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/condition_content.md)
 - **Enumeration Content**: Content that varies based on enumerated values [see Enumeration Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/enumeration_content.md)
+- **Plural Content**: Content that varies based on plural rules [see Plural Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/plural.md)
 - **Insertion Content**: Content that can be inserted into other content [see Insertion Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/insertion_content.md)
 - **Markdown Content**: Rich text content in Markdown format [see Markdown Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/markdown_content.md)
 - **HTML Content**: Rich HTML content with optional custom components [see HTML Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/html.md)
@@ -547,6 +564,8 @@ multilingualContent: t({
 });
 ```
 
+> See [Translation Doc](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/translation.md) for more information.
+
 ### Condition Content (`cond`)
 
 Content that changes based on boolean conditions:
@@ -560,6 +579,23 @@ conditionalContent: cond({
 });
 ```
 
+> See [Condition Doc](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/condition.md) for more information.
+
+### Plural Content (`plural`)
+
+Content that varies based on plural rules:
+
+```typescript
+import { plural } from "intlayer";
+
+pluralContent: plural({
+  one: "One car",
+  other: "{{count}} cars",
+});
+```
+
+> See [Plural Doc](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/plural.md) for more information.
+
 ### Enumeration Content (`enu`)
 
 Content that varies based on enumerated values:
@@ -574,6 +610,8 @@ statusContent: enu({
 });
 ```
 
+> See [Enumeration Doc](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/enumeration.md) for more information.
+
 ### Insertion Content (`insert`)
 
 Content that can be inserted into other content:
@@ -584,6 +622,8 @@ import { insert } from "intlayer";
 insertionContent: insert("This text can be inserted anywhere");
 ```
 
+> See [Insertion Doc](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/insertion.md) for more information.
+
 ### Nested Content (`nest`)
 
 References to other dictionaries:
@@ -594,6 +634,8 @@ import { nest } from "intlayer";
 nestedContent: nest("about-page");
 ```
 
+> See [Nested Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/nesting.md) for more information.
+
 ### Markdown Content (`md`)
 
 Rich text content in Markdown format:
@@ -611,6 +653,8 @@ localizedMarkdownContent: t({
 });
 ```
 
+> See [Markdown Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/markdown.md) for more information.
+
 ### HTML Content (`html`)
 
 Rich HTML content that can use standard tags or custom components:
@@ -628,6 +672,8 @@ localizedHtmlContent: t({
 });
 ```
 
+> See [HTML Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/html.md) for more information.
+
 ### Gender Content (`gender`)
 
 Content that varies based on gender:
@@ -642,6 +688,8 @@ genderContent: gender({
 });
 ```
 
+> See [Gender Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/gender.md) for more information.
+
 ### File Content (`file`)
 
 References to external files:
@@ -652,6 +700,8 @@ import { file } from "intlayer";
 fileContent: file("./path/to/content.txt");
 ```
 
+> See [File Content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/file.md) for more information.
+
 ## Creating Content Files
 
 ### Basic Content File Structure

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

@@ -160,30 +160,9 @@ 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
-  format?: 'icu' | 'i18next' | 'vue-i18n', // optional, only needed when your msgstr values use a specific interpolation syntax
 });
 ```
 
-#### `format` ('icu' | 'i18next' | 'vue-i18n')
-
-PO files are always Gettext Portable Object files — that is fixed. This option only describes the **interpolation syntax** used inside the `msgstr` values, so Intlayer can convert them to its own format at parse time (via `formatDictionary`) and back when writing output.
-
-- `undefined` _(default)_: `msgstr` values are treated as plain strings — no transformation. Use this for most PO files.
-- `'icu'`: `msgstr` values use ICU message syntax (e.g. `{count, plural, one {# item} other {# items}}`).
-- `'i18next'`: `msgstr` values use i18next interpolation syntax (e.g. `{{variable}}`).
-- `'vue-i18n'`: `msgstr` values use Vue I18n syntax.
-
-> Transformation is applied by `@intlayer/chokidar`'s `formatDictionary` on load, and reversed with `formatDictionaryOutput` on write. For complex rules like ICU plurals, round-trip fidelity is not guaranteed.
-
-**Example — PO files contain i18next-style interpolation:**
-
-```ts
-syncPO({
-  source: ({ key, locale }) => `./locales/${locale}/${key}.po`,
-  format: "i18next",
-}),
-```
-
 ### 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.

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).

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

@@ -0,0 +1,148 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Best i18n solution for Svelte in 2026 - Benchmark Report
+description: Compare Svelte internationalisation (i18n) libraries like svelte-i18n, Paraglide, and Intlayer. Detailed performance report on bundle size, leakage, and reactivity.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - svelte
+  - performance
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - svelte
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n-svelte-template
+history:
+  - version: 8.7.12
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# Svelte i18n Libraries — 2026 Benchmark Report
+
+This page is a benchmark report for i18n solutions on Svelte.
+
+## Table of Contents
+
+<Toc/>
+
+## Interactive Benchmark
+
+<I18nBenchmark framework="vite-svelte" 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_svelte.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_svelte.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 Svelte 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**: The most performance-efficient choice (v8.7.12) with the smallest footprint.
+- **Paraglide**: Strong contender for tree-shaking but has a more complex developer experience and reactivity overhead.
+- **svelte-i18n**: Comprehensive and standard for Svelte, but carries much larger bundle weight (~7× Intlayer).
+
+## 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)
+- `svelte-intlayer` (v8.7.12)
+- `svelte-i18n` (v4.0.1)
+- `@inlang/paraglide-js` (v2.17.0)
+
+The framework is `Svelte` 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 svelte ecosystem.
+
+### 2 — Acceptable solutions
+
+**(Paraglide)** (`@inlang/paraglide-js@2.17.0`):
+
+`Paraglide` offers an innovative, well-thought-out approach. In the context of a Vite + Svelte app, the tree-shaking their company advertises worked as expected, which is great.
+But in the case of React + TanStack Start, tree-shaking did not work as expected, same for Next.js. That said, Paraglide's usage in a Svelte and TanStack Start project would be worth a double check.
+The workflow and DX are also more complex than other options.
+Personally I am not a fan of having to regenerate JS files before every push, which creates constant merge conflict risk via PRs. The tool also seems more focused on Vite than Next.js.
+Finally, in comparison with other solutions, Paraglide does not use a store (e.g. Svelte store) 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.
+
+> Note on paraglide: the solution injects code into your codebase for imports; as a result, the 'lib size' metric in the benchmark report is almost 0. Code generation is a good thing, because the function used will include only the necessary logic (prefix everywhere vs no prefix, cookie vs storage, etc.). In comparison, Intlayer performs this filtering via environment variable injections in the build to force the bundler to tree-shake the 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.
+
+**(svelte-i18n)** (`svelte-i18n@3.4.0`):
+
+This solution answers all i18n needs in a Svelte project. But as it is the case for i18next or other major i18n solutions, it is a bit heavy (~15.9kb, which is about 7× `svelte-intlayer`).
+
+### 3 — Recommendations
+
+**(Intlayer)** (`svelte-intlayer@8.7.12`):
+
+I will not personally judge `svelte-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 Svelte apps, injecting a function as a `Slot` is, in my view, an anti-pattern. It also adds avoidable complexity and JavaScript execution overhead (even if it is barely noticeable).

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

@@ -57,6 +57,13 @@ In practice, for the least optimised implementations, an internationalised page
 
 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**: Provides the best performance and smallest bundle size (v8.7.12) for TanStack Start.
+- **react-i18next** & **use-intl**: Mature alternatives with large ecosystems, but significantly heavier and more complex to optimise.
+- **Paraglide**: Innovative tree-shaking idea that does not work in practice. Complex DX and reactivity overhead in TanStack Start.
+- **Avoid**: **General Translation (GT)** and **Lingo.dev** due to severe performance issues, AI quota limits, and vendor lock-in.
+
 ## Test your app
 
 To quickly spot i18n leakage issues, I set up a free scanner available [here](https://intlayer.org/i18n-seo-scanner).
@@ -87,12 +94,12 @@ Syntaxes built around `const t = useTranslation()` + `t('a.b.c')` are very conve
 For this benchmark, we compared the following libraries:
 
 - `Base App` (No i18n library)
-- `react-intlayer` (v8.7.5-canary.0)
+- `react-intlayer` (v8.7.12)
 - `react-i18next` (v17.0.2)
 - `use-intl` (v4.9.1)
 - `@lingui/core` (v5.3.0)
 - `@inlang/paraglide-js` (v2.15.1)
-- `tolgee` (v7.0.0)
+- `@tolgee/react` (v7.0.0)
 - `react-intl` (v10.1.1)
 - `wuchale` (v0.22.11)
 - `gt-react` (vlatest)
@@ -150,7 +157,9 @@ The idea behind `Wuchale` is interesting but not yet a viable solution. I hit re
 
 `Paraglide` offers an innovative, well-thought-out approach. Even so, in this benchmark the tree-shaking their company advertises did not work for my Next.js implementation or for TanStack Start. The workflow and DX are also more complex than other options. Personally I am not a fan of having to regenerate JS files before every push, which creates constant merge conflict risk for developers via PRs.
 
-**(Tolgee)** (`tolgee@7.0.0`):
+> Note on paraglide: the solution injects code into your codebase for imports; as a result, the 'lib size' metric in the benchmark report is almost 0. Code generation is a good thing, because the function used will include only the necessary logic (prefix everywhere vs no prefix, cookie vs storage, etc.). In comparison, Intlayer performs this filtering via environment variable injections in the build to force the bundler to tree-shake the 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.
+
+**(Tolgee)** (`@tolgee/react@7.0.0`):
 
 `Tolgee` addresses many of the issues mentioned earlier. I found it harder to get started with than other tools with similar approaches. It does not provide type safety, which also makes catching missing keys at compile time much harder. I had to wrap Tolgee’s APIs with my own to add missing-key detection.