@intlayer/docs 9.4.1 → 9.4.3

package/blog/en/list_i18n_technologies/frameworks/react.md

@@ -1,16 +1,16 @@
 ---
 createdAt: 2025-01-16
-updatedAt: 2026-05-31
-title: Best React i18n Libraries 2026 — Compared by DX & Bundle
-description: Best solution for bundle size, SEO, performances & maintainability. Make your React app multilingual in 2026, LLM translation, Agent Skills & MCP.
+updatedAt: 2026-09-02
+title: React i18n - how the provider model works and what it costs
+description: React has no built-in i18n. How the context-provider model works, why t("a.b") has no types, how plurals and lazy loading behave, and how the libraries differ.
 keywords:
-  - React
-  - i18n
-  - multilingual
-  - SEO
-  - Internationalization
-  - Blog
-  - JavaScript
+  - react i18n
+  - react internationalization
+  - react-i18next
+  - react-intl
+  - Lingui
+  - useTranslation
+  - Intlayer
 slugs:
   - blog
   - i18n-technologies
@@ -19,138 +19,218 @@ slugs:
 author: aymericzip
 ---
 
-# Exploring i18n Solutions to Translate Your React Website
+# React i18n: the provider model, and what it costs you
 
-In today's digital landscape, expanding your website’s reach to cater to a global audience is essential. For developers building with React, implementing internationalization (i18n) is key to managing translations efficiently while preserving application structure, SEO value, and user experience. In this article, we explore various i18n approaches from dedicated libraries to custom-coded solutions helping you decide which one best suits your project needs.
+React has no i18n primitive. There is no `useTranslation` in `react`, no message format, no locale negotiation, so every React app picks a library on day one and lives with that decision for years. This post covers the model all of them share, the four places it costs you something, and how `react-i18next`, `react-intl`, Lingui and Intlayer differ once you get past the hello world.
 
----
+## Table of Contents
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
+<TOC/>
 
-## What is Internationalization (i18n)?
+## The starting point
 
-Internationalization, abbreviated as i18n, is the process of designing and preparing your website to support multiple languages and cultural contexts. In React, this means setting up your app so that strings, date formats, number formats, and even the layout can be adapted easily for users from different regions. Preparing your React app for i18n lays the groundwork for cleanly integrating translations and other localization features.
+Before any library, the code looks like this and it is wrong in a way that only shows up later:
 
-Learn more about i18n by reading our article: [What is Internationalization (i18n)? Definition and Challenges](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md).
+```tsx fileName="src/components/CartSummary.tsx"
+export const CartSummary = ({ count }: { count: number }) => (
+  <section>
+    <h2>Your cart</h2>
+    <p>{count} items</p>
+  </section>
+);
+```
 
----
+Two hardcoded strings, one broken plural (`1 items`), and a number that will need grouping separators in `de-DE`. Multiply by three hundred components and you have the actual problem: not translating strings, but keeping three hundred components and N locale files in sync for two years.
 
-## The Translation Challenge for React Applications
+If the vocabulary is new, start with [what internationalization actually covers](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md).
 
-Translating a React website presents several challenges:
+## Every React i18n library is the same shape
 
-- **Component-Based Architecture:** React’s modular design means that text can be spread across multiple components, making it critical to centralize and organize translation strings.
-- **Dynamic Content:** Managing translations for content that updates in real time or is fetched from APIs can add an extra layer of complexity.
-- **SEO Considerations:** For server-side rendered React apps (using frameworks like Next.js), ensuring that translations contribute positively to SEO involves managing localized URLs, metadata, and sitemaps.
-- **State and Context Management:** Ensuring that the correct language is maintained across routes and components requires thoughtful state management.
-- **Development Overhead:** Maintaining translation files, ensuring context accuracy, and keeping your application scalable are ongoing considerations.
+Whatever you pick, you get the same three pieces:
 
----
+1. A **store** holding the active locale and the loaded messages.
+2. A **provider** putting that store into React context.
+3. A **hook** reading from context inside components.
 
-## Leading i18n Solutions for React
+```tsx fileName="src/main.tsx"
+<I18nProvider locale={locale} messages={messages}>
+  <App />
+</I18nProvider>
+```
 
-Below are several popular approaches to managing multilingual content in React applications, each designed to streamline the translation process in different ways.
+That is the whole model. It has one structural consequence worth understanding before you compare APIs: **whatever you hand the provider travels into the client bundle**. `messages` is a plain JS object serialized into your JS chunks (or into the SSR payload, then hydrated). A component that renders one heading pulls in the context, and the context holds every message that was loaded, for every page.
 
-### 1. Intlayer
+This is why "i18n made my bundle big" reports are almost never about the library. They are about the catalog. The [TanStack Start benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/tanstack.md) measures the two separately for exactly this reason: library code in an empty component, and content per route.
 
-> Website: [https://intlayer.org/](https://intlayer.org/)
+## Key-based versus component-based
 
-**Overview**  
-**Intlayer** is an innovative, open-source internationalization (i18n) library designed to simplify multilingual support in modern React (and other) web applications. It offers a declarative approach, letting you define translation dictionaries directly within your components.
+Two ways to reference a string. This is the real fork in the road, more than any API detail.
 
-**Key Features**
+**Key-based** (`react-i18next`, `react-intl`, `next-intl`): the component holds an identifier, the text lives in a catalog.
 
-- **Translation Declaration**: Allows the declaration off all translations in a single file, placed at the component level, making it easier to maintain and scale.
-- **TypeScript & Autocompletion**: Offers autogenerated type definitions for translation keys, providing robust autocompletion and error detection.
-- **Server Components & SSR**: Built with both server-side rendering (SSR) and server components in mind, ensuring that localized content is rendered efficiently on both the client and the server.
-- **Localized Metadata & URLs for SEO**: Easily handle dynamic locale-based routes, sitemaps, and robots.txt entries to improve discoverability and SEO.
-- **Seamless Integration**: Compatible with major bundlers and frameworks like Create React App, Next.js, and Vite, making setup straightforward.
-- **Asynchronous Loading**: Dynamically load translation dictionaries, reducing initial bundle size and improving performance.
+```tsx
+const { t } = useTranslation("cart");
+return <h2>{t("summary.title")}</h2>;
+```
 
-**Considerations**
+**Component-based** (Lingui's `<Trans>`, Intlayer's nodes): the source text or a typed node lives at the call site, extraction happens at build time.
 
-- **Community & Ecosystem**: Though growing, the ecosystem is newer, so community-driven plugins and tooling may be more limited compared to more established solutions.
+```tsx
+return <Trans>Your cart</Trans>;
+```
 
----
+Key-based wins when translators work in a TMS and never see your code. Component-based wins on review, because a diff shows the actual copy, and on dead-code detection, because deleting the component deletes the string.
 
-### 2. React-i18next
+## Why `t("some.key")` gives you nothing
 
-Website: [https://react.i18next.com/](https://react.i18next.com/)
+`t` is typed `(key: string) => string`. That is the default in every key-based library, and it means:
 
-**Overview**  
-**React-i18next** is one of the most widely used React libraries for internationalization, built on top of the popular **i18next** framework. It provides a flexible, plugin-based architecture for handling complex translation scenarios.
+- A typo compiles. You find it at runtime, in the locale nobody tests.
+- Renaming a nesting level in `en.json` breaks the other ten locales silently.
+- Deleting a component leaves its keys in every catalog forever. Nothing warns you.
 
-**Key Features**
+You can fix this. `react-i18next` supports declaration merging on `CustomTypeOptions` so `t` is narrowed to the keys of your resources; `react-intl` gets there through `formatjs` extraction plus a generated union. Both work, and both are extra wiring that has to survive lazily loaded namespaces, where the type describes messages that may not be loaded yet.
 
-- **Seamless React Integration**: Works with React hooks, higher-order components (HOCs), and render props for maximum flexibility.
-- **Asynchronous Loading**: Dynamically load translation resources, reducing initial bundle size and improving performance.
-- **Rich Translation Capabilities**: Supports nested translations, plurals, interpolation, and more.
-- **TypeScript & Autocompletion**: With additional configuration, you can enjoy typed translation keys, though setup can be more manual.
-- **Localized Metadata & URLs**: Can be integrated with Next.js for localized routes, sitemaps, and robots.txt, improving SEO.
-- **Server Components & SSR**: With Next.js or other SSR setups, you can serve fully localized content from the server.
+The honest summary: type safety on keys is achievable everywhere, it is on by default almost nowhere.
 
-**Considerations**
+## Plurals and interpolation
 
-- **Maintainability**: Configuration can become complex, especially for large or multi-team projects; careful structuring of translation files is essential.
-- **Plugin Ecosystem**: A broad ecosystem of plugins and middlewares is available, which also means you’ll need to sift through various packages to find the right tools.
-- **Server Components**: Requires additional setup to ensure server components pick up the correct locales, especially if using frameworks other than Next.js.
+Three incompatible formats, one problem.
 
----
+| Library         | Plural syntax                                        | Note                                               |
+| :-------------- | :--------------------------------------------------- | :------------------------------------------------- |
+| `react-i18next` | Suffix keys: `item_one`, `item_other`                | i18next's own format, driven by `Intl.PluralRules` |
+| `react-intl`    | ICU: `{count, plural, one {# item} other {# items}}` | Standard, portable to most TMS platforms           |
+| Lingui          | ICU via macros, compiled                             | Same format, compiled to a compact runtime         |
+| Intlayer        | `plural({ one, other })` helper                      | CLDR categories, not ICU strings                   |
 
-### 3. React Intl (from FormatJS)
+ICU is the interchange format your translation vendor most likely speaks. If you are already receiving ICU strings, that constrains the choice more than bundle size does. There is a longer write-up on [ICU MessageFormat and where it helps](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/icu_message_format.md).
 
-Website: [https://formatjs.io/docs/react-intl/](https://formatjs.io/docs/react-intl/)
+Interpolation has a second trap: putting a `<Link>` inside a translated sentence. Every library has an answer (`<Trans>` in i18next and Lingui, rich text tags in `react-intl`), and all of them are more awkward than the plain string case. Budget for it.
 
-**Overview**  
-**React Intl**, part of the **FormatJS** suite, focuses on standardizing message formatting, date/number/time localization, and relative time messages. It uses a message extraction workflow to handle your translations efficiently.
+## Lazy loading per route
 
-**Key Features**
+The mechanism is the same everywhere: split catalogs into namespaces, load the namespace a route needs, use `React.lazy` or your router's loader to fetch it.
 
-- **Format-Focused Components**: `<FormattedMessage>`, `<FormattedDate>`, `<FormattedTime>`, and more to simplify formatting in React.
-- **Server Components & SSR**: Offers support for SSR setups so that localized content can be served for improved performance and SEO.
-- **Localized Metadata & URLs**: Can integrate with frameworks like Next.js for generating localized sitemaps, handling dynamic routes, and customizing robots.txt.
-- **TypeScript & Autocompletion**: Can be combined with TypeScript but may need extra tooling for autocompletion of message IDs.
-- **Polyfills for Unsupported Browsers**: Ensures consistent behavior across legacy environments.
+```tsx
+const { t } = useTranslation("checkout"); // loads locales/en/checkout.json
+```
 
-**Considerations**
+Two things go wrong in practice. First, a namespace once loaded stays in the store, so navigating through five routes leaves you with five catalogs in memory and in the hydration payload. Second, nothing enforces the mapping. A shared `<Button>` reaching for `t("common:cta")` quietly makes `common` a dependency of every route.
 
-- **Verbosity & Boilerplate**: Reliance on dedicated components can lead to more verbose code, especially in large applications.
-- **Splitting Translations**: Core library doesn’t provide built-in support for splitting translations into multiple files requires additional setup or plugins.
-- **Maintainability**: The straightforward approach to formatting can be beneficial, but message extraction and organizational overhead can grow quickly.
+The result shows in the benchmark as **leakage**: content from other locales or other routes riding along in a page's bundle. It is a discipline problem, not a library bug, and discipline erodes across teams.
 
-### 4. LinguiJS
+## If you later move to a framework
 
-Website: [https://lingui.js.org/](https://lingui.js.org/)
+Plain React means everything is a Client Component, so this does not bite yet. It bites the day you move to Next.js App Router or another RSC-based framework: React context does not cross the server/client boundary, so a hook-based `t()` forces `"use client"` on any component that renders text.
 
-**Overview:**
+The workarounds are a server-side async `getTranslations()` alongside the client hook, which is two APIs for one job. Worth knowing before you standardize on a pattern across a large codebase. The [Next.js i18n post](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/nextjs.md) covers that boundary; for routing-specific setups see the [React Router](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/react-router.md), [TanStack Start](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/tanstack-start.md) and [React Native](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/react-native.md) posts.
 
-**Overview**  
-**LinguiJS** offers a modern, developer-friendly approach for managing i18n in JavaScript and React. It focuses on reducing configuration while empowering you with a robust CLI and message extraction workflow.
+## The four realistic options
 
-**Key Features**
+Library sizes below are from the TanStack Start benchmark, measured after bundling, tree-shaking and minification, on a 10-page / 10-locale app. They cover provider plus hook in an empty component, not your content.
 
-- **Automatic Message Extraction**: A dedicated CLI that discovers and extracts messages from your code, minimizing manual steps.
-- **Minimal Runtime Overhead**: Compiled translations reduce bundle size and runtime performance costs.
-- **TypeScript & Autocompletion**: Supports typed IDs if you configure your translation catalogs accordingly, improving the developer experience.
-- **Server Components & SSR**: Compatible with server-side rendering strategies; can be integrated with Next.js or other SSR frameworks.
-- **Localized Metadata & URLs**: While not as explicit as some other libraries, it can be integrated with your routing setup to handle sitemaps, robots.txt, and localized paths.
+| Library                | Model                                | Types on keys                  | Library size                          |
+| :--------------------- | :----------------------------------- | :----------------------------- | :------------------------------------ |
+| `react-i18next@17.0.2` | Key-based, runtime catalogs          | Opt-in via `CustomTypeOptions` | ~17.3 kB, about 3.5× `react-intlayer` |
+| `react-intl@10.1.1`    | Key-based, ICU-native                | Opt-in via extraction          | ~14.4 kB, about 3× `react-intlayer`   |
+| `@lingui/core@5.3.0`   | Macros compiled at build time        | Good, from the compiler        | Compiled catalogs, small runtime      |
+| `react-intlayer`       | Per-component declarations, compiled | Generated, on by default       | Baseline in the benchmark             |
 
-**Considerations**
+**`react-i18next` is the right answer for most teams.** It has the largest plugin ecosystem, backends for every TMS, detectors, and a decade of Stack Overflow answers. If you have no specific constraint, picking it is not a mistake. The costs are real but boring: heaviest of the four, its own plural format, and the type wiring is yours to maintain.
 
-- **Maintainability**: Automatic extraction helps keep code clean, but structuring multiple translation files for large apps requires disciplined organization.
-- **Community & Plugins**: The ecosystem is growing but still smaller compared to i18next or FormatJS.
-- **Server Components**: May need more explicit configuration to ensure that server components receive the correct locale data.
+**`react-intl`** is the one to pick if ICU compliance matters and your translators live in a platform that speaks it. The DX is verbose: `const intl = useIntl()` then `intl.formatMessage({ id })` for every string.
 
----
+**Lingui** trades runtime for a compiler. `lingui extract` / `lingui compile` is an extra build step and the macro syntax has several forms (`t()`, tagged templates, `i18n.t()`, `<Trans>`) that are easy to mix up, but the bundle result is good.
+
+For a feature-by-feature table, there is a dedicated [react-i18next vs react-intl vs Intlayer comparison](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/react-i18next_vs_react-intl_vs_intlayer.md).
+
+## Intlayer: content declared next to the component
+
+Intlayer moves the catalog. Instead of `locales/en.json`, each component gets a `.content.ts` file beside it, and a build plugin compiles those declarations into per-component dictionaries.
+
+```ts fileName="src/components/cartSummary.content.ts"
+import { plural, t, type Dictionary } from "intlayer";
+
+const cartSummaryContent = {
+  key: "cart-summary",
+  content: {
+    title: t({ en: "Your cart", fr: "Votre panier", es: "Tu carrito" }),
+    items: t({
+      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
+      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
+      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
+    }),
+  },
+} satisfies Dictionary;
+
+export default cartSummaryContent;
+```
+
+```tsx fileName="src/components/CartSummary.tsx"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+export const CartSummary: FC<{ count: number }> = ({ count }) => {
+  const { title, items } = useIntlayer("cart-summary");
+
+  return (
+    <section>
+      <h2>{title}</h2>
+      <p>{items(count)}</p>
+    </section>
+  );
+};
+```
+
+`useIntlayer` returns typed nodes, so `title` autocompletes and a typo fails `tsc`, with no declaration merging to set up. Locale switching goes through `useLocale()`, which returns `locale`, `availableLocales` and `setLocale`.
+
+The scoping falls out of the file layout: because the dictionary key is declared in one file and read in one component, the compiler ships only what a route renders, and deleting the folder deletes the strings.
+
+<Tabs defaultTab="code">
+  <Tab label="Code" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-vite-react-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+  <Tab label="Demo" value="demo">
+
+<iframe
+  src="https://intlayer-vite-react-template.vercel.app"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo - intlayer-vite-react-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+**What it costs you.** A bundler plugin is mandatory: no `vite-intlayer` or equivalent, no dictionaries, so there is no way to use it in a no-build setup. The ecosystem is far smaller than i18next's, which means fewer TMS backends and fewer answers when you get stuck. ICU message format support is still partial, so if your vendor delivers ICU strings today that is a genuine blocker. And handing a translator one big JSON file requires tooling, since the content is spread across the codebase by design.
+
+On an existing `react-i18next` codebase, the [`@intlayer/react-i18next` compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/react-i18next.md) aliases `react-i18next` imports at the bundler level so `useTranslation`, `<Trans>` and suffix plurals keep working, and the [step-by-step migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_react-i18next_to_intlayer.md) covers moving off the adapter afterwards. There are equivalents for [`react-intl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/react-intl.md) and [Lingui](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/lingui.md).
 
-### Final Thoughts
+## Common mistakes
 
-When choosing an i18n library for React:
+- **Loading every locale into the provider.** The most common cause of a heavy bundle. Load the active locale, fetch the rest on switch.
+- **Letting shared components own namespaces.** A `common` namespace referenced by a `<Button>` becomes a dependency of every route.
+- **Switching locale with a `<button>`.** Crawlers do not click. Render locale switchers as `<a>` pointing at the localized URL.
+- **Skipping the type wiring "for now".** It is much cheaper to set up at 20 keys than at 2000.
+- **Treating catalogs as append-only.** Nothing detects dead keys in a key-based setup. Schedule a sweep, or pick a model where content is scoped to a component.
+- **Formatting dates and numbers by hand.** `Intl.DateTimeFormat` and `Intl.NumberFormat` are in every runtime you target. Every library above wraps them; none of them need a helper you wrote.
 
-- **Evaluate Your Requirements**: Consider project size, developer experience, and how you plan to handle translations (manual vs. automated extraction).
-- **Check Server Compatibility**: If you rely on SSR or server components (especially in Next.js), ensure your chosen library supports it seamlessly.
-- **TypeScript & Autocompletion**: If TypeScript is a priority, select a library that easily integrates with typed keys and provides robust developer tooling.
-- **Maintainability & Scalability**: Larger projects often need a clear, maintainable structure for translations, so factor in your long-term roadmap.
-- **SEO & Metadata**: If SEO is crucial, confirm that your chosen solution supports localized metadata, routes, and sitemaps/robots for each language.
+## Going further
 
-All these libraries can power a multilingual React application each with slightly different priorities and strengths. Select the one that most closely aligns with your project’s **performance**, **DX (developer experience)**, and **business goals**.
+- [i18n library benchmark: bundle size, leakage and locale-switch timings](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
+- [Set up i18n in a Vite + React app](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react.md)
+- [Drop-in `react-i18next` compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/react-i18next.md) and the [full migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_react-i18next_to_intlayer.md)
+- [react-i18next vs react-intl vs Intlayer, feature by feature](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/react-i18next_vs_react-intl_vs_intlayer.md)
+- [Per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md)
+- [Compiler-based vs declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/compiler_vs_declarative_i18n.md)
+- [How bundle optimization works at build time](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md)

package/blog/en/list_i18n_technologies/frameworks/solid.md

@@ -0,0 +1,268 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Solid i18n: why translations freeze on locale change"
+description: Why Solid components capture translations as constants, how @solid-primitives/i18n works, lazy catalogs, SolidStart locale routing, and what Intlayer changes.
+keywords:
+  - solidjs i18n
+  - solid start i18n
+  - solid internationalization
+  - solid-primitives i18n
+  - solid-i18next
+  - fine-grained reactivity
+  - locale routing
+  - Intlayer
+slugs:
+  - blog
+  - i18n-technologies
+  - frameworks
+  - solid
+author: aymericzip
+---
+
+# Solid i18n: the translation that never updates
+
+Solid's reactivity model changes what an i18n library has to do, and it changes the bugs you get. The most common one is a page that switches language everywhere except in the three components where someone stored a translation in a `const`. This post explains why that happens, then covers the real options: `@solid-primitives/i18n`, lazy catalogs, SolidStart locale routing, and Intlayer.
+
+## Table of Contents
+
+<TOC/>
+
+## The bug you will hit first
+
+Here is a component that looks correct and is not.
+
+```tsx fileName="src/components/CartSummary.tsx"
+import { useI18n } from "~/i18n";
+
+export const CartSummary = () => {
+  const t = useI18n();
+
+  const total = t("cart.total"); // evaluated once, during setup
+
+  return (
+    <section>
+      <h2>{total}</h2>
+      <p>{t("cart.items", { count: 3 })}</p>
+    </section>
+  );
+};
+```
+
+Switch the locale and the `<p>` updates. The `<h2>` does not. It stays in whatever language was active the first time the component ran, and it will stay there until the component is destroyed and recreated.
+
+In React this code works, because a locale change re-renders the component and re-evaluates every line of its body. In Solid nothing re-runs, so the difference between the two lines is real and permanent.
+
+## Why: components run once
+
+A Solid component is a factory, not a render function. It executes exactly once, returns DOM nodes, and is never called again. What updates afterwards is not the component, it is the individual reactive computations Solid's compiler created inside the JSX.
+
+`{t("cart.items", { count: 3 })}` inside JSX compiles to a getter that Solid wraps in an effect. Reading the locale signal inside it subscribes that one text node. `const total = t("cart.total")` runs in the setup body, outside any tracking scope, so it subscribes to nothing and produces a plain string.
+
+This is the same rule that forbids destructuring props in Solid. Applied to i18n, it means every translated value must stay behind a function call that is executed inside a tracked scope.
+
+The fix is to keep the read lazy:
+
+```tsx fileName="src/components/CartSummary.tsx"
+import { createMemo } from "solid-js";
+import { useI18n } from "~/i18n";
+
+export const CartSummary = () => {
+  const t = useI18n();
+
+  const total = createMemo(() => t("cart.total")); // an accessor, not a string
+
+  return <h2>{total()}</h2>;
+};
+```
+
+Two consequences worth internalizing:
+
+- A translation you pass to a non-JSX API (a `document.title` assignment, a chart config, an `aria-label` computed in setup) is a snapshot. It needs its own effect or memo.
+- A translation stored in a store, a module-level variable or a closure created at setup is a snapshot too. Locale changes will not reach it.
+
+## `@solid-primitives/i18n` is the community default
+
+The Solid ecosystem is small, and this is the option most projects land on. It is not a framework, it is a set of primitives: you own the dictionaries, the locale signal, and the loading strategy.
+
+```ts fileName="src/i18n/index.ts"
+import * as i18n from "@solid-primitives/i18n";
+import { createSignal } from "solid-js";
+
+const en = {
+  cart: { total: "Total", items: "{{ count }} items" },
+};
+
+export type RawDictionary = typeof en;
+export type Dictionary = i18n.Flatten<RawDictionary>;
+
+const [locale, setLocale] = createSignal<"en" | "fr">("en");
+
+const dictionary = () => i18n.flatten(en);
+const t = i18n.translator(dictionary, i18n.resolveTemplate);
+
+t("cart.items", { count: 3 }); // "3 items"
+```
+
+`flatten` turns the nested object into `"cart.total"` style keys, and `translator` takes an _accessor_, not a value. That signature is the whole design: because the dictionary arrives as a function, `t` reads it inside your tracking scope, and the resulting text is reactive as long as you call `t` in a reactive position.
+
+Types are derived from the English dictionary, so a typo in a key is a compile error without any extra codegen. That is a genuine advantage over `t("a.b.c")` in most other libraries.
+
+What it does not give you: no namespace scoping, no route-aware splitting, no cookie handling, no locale routing, no formatters. On a 10 page app that is fine. On a 40 page app you are writing that layer yourself.
+
+## Lazy loading catalogs
+
+Because `translator` accepts an accessor that may return `undefined`, a resource plugs straight in.
+
+```ts fileName="src/i18n/index.ts"
+import * as i18n from "@solid-primitives/i18n";
+import { createResource, createSignal } from "solid-js";
+
+const fetchDictionary = async (locale: string): Promise<Dictionary> => {
+  const module = await import(`./locales/${locale}.ts`);
+  return i18n.flatten(module.dictionary);
+};
+
+const [locale, setLocale] = createSignal("en");
+const [dictionary] = createResource(locale, fetchDictionary);
+
+export const t = i18n.translator(dictionary, i18n.resolveTemplate);
+```
+
+During the fetch, `t` returns `undefined` and your UI renders empty strings unless you wrap it in a `<Suspense>` or supply a fallback. That transient blank is the price of the split, and it is easy to miss in development where the import resolves instantly.
+
+This splits by locale, not by page. Every route still pays for every other route's copy. Getting per-page splitting out of a flat dictionary means maintaining one file per page per locale by hand.
+
+## SolidStart: the locale has to be resolved on the server
+
+Client-side locale detection does not work for SSR. If the server renders in English and the client then reads a cookie and switches to French, you get a hydration mismatch and a visible flash.
+
+The reliable source of truth is the URL, because the server and the client both see it. SolidStart's file router supports an optional dynamic segment, and `[[locale]]` compiles to `:locale?`:
+
+```plaintext
+src/routes/
+  [[locale]].tsx          layout that validates the segment
+  [[locale]]/
+    index.tsx             /        /fr        /es
+    about.tsx             /about   /fr/about  /es/about
+  [...404].tsx
+```
+
+The catch is that `@solidjs/router` expands `:locale?` into two patterns and tries them by specificity. Without a match filter, `/unknown` matches the locale segment and silently renders your home page with `locale="unknown"` instead of a 404. Constrain it in the layout's `route` export:
+
+```tsx fileName="src/routes/[[locale]].tsx"
+import type { RouteSectionProps } from "@solidjs/router";
+import { locales } from "intlayer";
+
+export const route = {
+  matchFilters: { locale: locales },
+};
+
+export default function LocaleLayout(props: RouteSectionProps) {
+  return <>{props.children}</>;
+}
+```
+
+Two more server-side pieces are yours to write with any library: setting `<html lang>` and `dir` in `entry-server.tsx`, which sits outside the `Router`, and emitting `canonical` plus `hreflang` links. At the time of writing, `@solidjs/meta` tags are applied on the client after hydration and are not in the server-rendered `<head>` in SolidStart v2, so anything a crawler must see without JavaScript belongs in `entry-server.tsx`. The [hreflang guide](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/internationalization_and_SEO.md) covers what those tags need to say.
+
+## The options
+
+| Library                  | Model                                              | Types on keys                       | Notes                                                          |
+| :----------------------- | :------------------------------------------------- | :---------------------------------- | :------------------------------------------------------------- |
+| `@solid-primitives/i18n` | Flat dictionary you own                            | Inferred from the source dictionary | Very small, no scoping, no routing, no formatters              |
+| `solid-i18next`          | i18next catalogs and namespaces                    | Manual declaration                  | Mature plugin ecosystem, heaviest of the set                   |
+| `@inlang/paraglide-js`   | Generated message functions                        | Generated                           | Compiled messages, but a regeneration step before every commit |
+| Intlayer                 | One `.content.ts` per component, compiled at build | Generated, on by default            | Requires a build plugin, smaller ecosystem                     |
+
+The [Solid i18n benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/solid.md) measures these on a 10 page, 10 locale app. `solid-i18next@17.0.2` weighs about **14.6 kB** after bundling and minification, roughly **4.7x `solid-intlayer`**. Paraglide's advertised tree-shaking did not take effect in that implementation, and it reads the locale from storage on each node rather than from a signal, which adds work on every render.
+
+## Intlayer: content next to the component
+
+Intlayer's design choice is that content lives in a file beside the component, and a build plugin compiles those declarations into per-component dictionaries.
+
+```ts fileName="src/components/cartSummary.content.ts"
+import { type Dictionary, plural, t } from "intlayer";
+
+const cartSummaryContent = {
+  key: "cart-summary",
+  content: {
+    total: t({ en: "Total", fr: "Total", es: "Total" }),
+    items: plural({
+      one: t({ en: "{{count}} item", fr: "{{count}} article" }),
+      other: t({ en: "{{count}} items", fr: "{{count}} articles" }),
+    }),
+  },
+} satisfies Dictionary;
+
+export default cartSummaryContent;
+```
+
+```tsx fileName="src/components/CartSummary.tsx"
+import { useIntlayer } from "solid-intlayer";
+import { createSignal } from "solid-js";
+
+export const CartSummary = () => {
+  const [count, setCount] = createSignal(3);
+  const content = useIntlayer("cart-summary");
+
+  return (
+    <section>
+      <h2>{content.total}</h2>
+      <p>{content.items(count())}</p>
+    </section>
+  );
+};
+```
+
+`useIntlayer` returns reactive nodes backed by a signal, so a locale change updates only the DOM nodes that read them, with no component re-run. The same Solid rule still applies: `{content.total}` in JSX is tracked, `const title = content.total.value` in the setup body is a frozen string. Use `.value` for string attributes, and wrap it in a memo if it has to react.
+
+<Tabs defaultTab="code">
+  <Tab label="Code" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-solid-start-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to Internationalize your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+  <Tab label="Demo" value="demo">
+
+<iframe
+  src="https://intlayer-solid-start-template.vercel.app"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo - intlayer-solid-start-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+Setup is `npx intlayer init`, then the `intlayer()` plugin in `vite.config.ts`. On SolidStart the plugin also registers a Nitro handler that reads the locale from the URL prefix, then the cookie, then `Accept-Language`, and redirects accordingly.
+
+**What it costs you.** A build step is mandatory: no plugin, no dictionaries. The ecosystem is much smaller than i18next's, and smaller than most alternatives listed above, so expect fewer Stack Overflow answers. There is one SolidStart-specific trap: every file under `src/routes` with a default export becomes a route, so page-level `.content.ts` files must live outside that directory. Component content can stay co-located.
+
+If you are on `solid-i18next` today, the [`@intlayer/i18next` compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/i18next.md) aliases i18next imports at the bundler level so existing calls keep working while Intlayer serves the content, and the [migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_i18next_to_intlayer.md) covers moving off it afterwards.
+
+## Common mistakes
+
+- **Storing a translation in a `const` at setup.** The one bug this whole post is about. If it is not called inside JSX, an effect or a memo, it will never update.
+- **Passing `t` to a helper that calls it once.** A formatting utility that takes the string instead of the accessor freezes it just as effectively.
+- **Detecting the locale on the client in SolidStart.** The server already rendered. Read it from the URL so both sides agree.
+- **Omitting `matchFilters` on `[[locale]]`.** `/unknown` renders your home page with a garbage locale instead of returning 404, and search engines index the duplicate.
+- **Switching locale with a `<button>`.** Crawlers do not click. Render the switcher as real anchors pointing at each localized URL.
+- **Assuming a per-component model is free.** You gain scoping and generated types, you lose the ability to hand a translator one JSON file without tooling.
+
+## Going further
+
+- [Solid i18n benchmark: bundle size, leakage and locale-switch timings](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/solid.md)
+- [Set up i18n in a SolidStart app, step by step](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_solid_start.md)
+- [Set up i18n in a Vite + Solid app](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+solid.md)
+- [Drop-in i18next compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/i18next.md) and the [i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_i18next_to_intlayer.md)
+- [Per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md)
+- [The same problem in Svelte, where runes change the rules](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/svelte.md)
+- [TanStack Start i18n: locale routing, SSR and the type tax](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/tanstack-start.md)
+- [How bundle optimization works at build time](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md)