@intlayer/docs 9.4.2 → 9.4.4

package/blog/en-GB/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "How to test translations without writing brittle tests"
+description: What is worth testing in an i18n app and what is not. Provider-based rendering tests, pseudolocalisation, RTL and plural coverage, and the snapshot trap.
+keywords:
+  - test translations
+  - i18n testing
+  - testing library i18n
+  - pseudolocalisation
+  - locale provider test
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# How to test translations without writing brittle tests
+
+Most i18n test suites fail in one of two ways. Either they assert on literal copy, so every wording change breaks fifty tests and the team deletes them. Or they render everything in the default locale, so they prove nothing about the other seventeen. Both end in the same place, a suite nobody trusts.
+
+## Table of Contents
+
+<TOC/>
+
+## The patterns are library-agnostic
+
+Every pattern below works on any i18n stack. Swap the provider for `I18nextProvider`, `NextIntlClientProvider` or `IntlProvider` and the tests are otherwise identical, because they assert on rendered output rather than on a library API.
+
+The coverage tooling ports too: with the [Sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-json.md) pointed at your existing catalogues, or a [compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/index.md) aliasing your current imports, the coverage assertion runs against the JSON you already have.
+
+## Decide what you are actually testing
+
+Translation quality is not a test. No assertion tells you whether the German is idiomatic, and pretending otherwise is how you get a suite full of hardcoded strings.
+
+What is worth testing is mechanical:
+
+| Worth testing                              | Not worth testing               |
+| :----------------------------------------- | :------------------------------ |
+| Every required locale has a value          | Whether the wording is good     |
+| The right locale reaches the component     | Exact copy of every label       |
+| Plurals resolve for each category          | That a translator did their job |
+| RTL locales set direction and mirror       | Every string in every locale    |
+| Formatted dates and numbers use the locale | Third-party `Intl` correctness  |
+
+Coverage belongs in one data-driven test, not in your component tests. That is covered in [finding missing translations](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en-GB/detecting_missing_translations.md); this post is about the rest.
+
+## Render under a provider, assert on role
+
+The core pattern is to mount the component inside a locale provider and query by role or test id rather than by copy.
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("renders the summary heading in French", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+Querying `getByRole("heading")` survives a copy change. `getByText("Récapitulatif")` does not. Use the literal only when the string itself is the thing under test, which is rare.
+
+For attributes such as `aria-label` you need the raw string rather than a renderable node. In React, `useIntlayer` entries expose a `.value` field for that.
+
+## Parameterise across locales
+
+One test body, every locale, is worth more than one test per locale.
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("locale %s", (locale) => {
+  it("renders without falling back to the key", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // A rendered key means the lookup failed.
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("sets the correct text direction", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+The first assertion is the cheap generic win: if a lookup fails and your library renders the key, the DOM contains something shaped like `cart.summary.title`. That catches a whole class of bugs without naming a single string.
+
+## Pseudolocalisation finds what catalogues cannot
+
+Add a fake locale that transforms every string, for example `Checkout` becoming `[!!! Çĥéçķöũţ !!!]`. Then render a page in it.
+
+Anything still in plain English is hardcoded, and no catalogue-based check can see that, because as far as the tooling is concerned the string does not exist. The brackets do a second job: they expand the text by roughly 30 percent, which surfaces layout that breaks in German before German does.
+
+This is worth running as a visual or end-to-end pass rather than a unit test, since the failure is something you look at.
+
+## Plurals need a test per category, not per language
+
+Plural bugs hide because English has two forms and most developers only ever exercise those. Polish has four, Arabic six.
+
+```ts fileName="plural.test.ts"
+// Arabic exercises zero, one, two, few, many, other.
+describe.each([0, 1, 2, 3, 11, 100])("count %i", (count) => {
+  it("produces a non-empty string in Arabic", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+Pick counts that hit each CLDR category for your worst-case language rather than testing 1 and 2 everywhere. `Intl.PluralRules` tells you which category a number falls into, so you can derive the sample set instead of guessing. More on the categories in [the ICU message format post](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en-GB/icu_message_format.md).
+
+## The snapshot trap
+
+Snapshots and i18n are a bad match. A snapshot of a localised component encodes every string in it, so a translator fixing a typo in Portuguese turns a green suite red, in a file no reviewer can evaluate. After the third time, someone runs `-u` without reading the diff, and the snapshots stop meaning anything.
+
+If you want snapshots, take them in one locale only, and treat that as a structural check rather than a content check. Everything locale-specific belongs in explicit assertions.
+
+## Test the negotiation, not just the rendering
+
+The most common production i18n bug is not a missing string. It is the wrong locale being selected: a URL says `/fr/`, the client reads `navigator.language`, and they disagree.
+
+Test the resolution order directly, as a pure function, separate from any component:
+
+```ts fileName="locale-resolution.test.ts"
+it("prefers the URL over the stored preference", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("falls back to the header when the URL has no prefix", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+This is the single highest-value i18n test most codebases are missing, and it needs no DOM.
+
+## What to run where
+
+- **Unit**: locale negotiation, formatters, plural categories. Fast, no DOM.
+- **Component**: one provider-based render per locale, asserting on roles and on the absence of raw keys.
+- **Coverage**: one data-driven test asserting no missing required locales.
+- **Visual or end-to-end**: pseudolocalisation pass and one RTL page, because those failures are visual.
+
+Keep the first three in the pipeline on every commit. The last one is cheap to run nightly and expensive to run on every push.
+
+## Common mistakes
+
+- **Asserting on literal copy everywhere.** Guarantees the suite is deleted within a quarter.
+- **Snapshotting localised components.** Translators break your build, reviewers rubber-stamp the update.
+- **Testing only the default locale.** The one locale that cannot be missing.
+- **Testing 1 and 2 for plurals.** Misses every category English does not have.
+- **Mocking the i18n library away.** You are then testing that your mock returns strings.
+- **Never testing negotiation.** The most common real-world failure, and the easiest to test.
+
+## Going further
+
+- [Testing your content: CLI audit, programmatic API and UI assertions](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/testing.md)
+- [ESLint plugin: catching hardcoded strings and dead content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/eslint.md)
+- [Formatters and locale utilities, including `getHTMLTextDir`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/formatters.md)
+- [Benchmark reports across frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/index.md)
+- [Drop-in react-i18next compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/react-i18next.md)
+- [How to find missing translations](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en-GB/detecting_missing_translations.md)
+- [ICU message format: plurals, select and skeletons](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en-GB/icu_message_format.md)

package/blog/en-GB/intlayer_with_i18next.md

@@ -83,15 +83,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.

package/blog/en-GB/intlayer_with_next-i18next.md

@@ -77,15 +77,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.

package/blog/en-GB/intlayer_with_next-intl.md

@@ -78,15 +78,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.

package/blog/en-GB/intlayer_with_react-i18next.md

@@ -77,15 +77,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.

package/blog/en-GB/intlayer_with_react-intl.md

@@ -75,15 +75,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.

package/blog/en-GB/intlayer_with_vue-i18n.md

@@ -77,15 +77,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.

package/blog/en-GB/is_i18next_outdated.md

@@ -0,0 +1,315 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: Is i18next Outdated in 2026?
+description: i18next powers millions of websites, but its 2011 runtime architecture is showing its age. A look at bundle bloat, tree-shaking limits, and stalled innovation.
+keywords:
+  - i18next
+  - react-i18next
+  - next-i18next
+  - Intlayer
+  - Internationalisation
+  - i18n
+  - Bundle size
+  - Blog
+slugs:
+  - blog
+  - is-i18next-outdated
+author: aymericzip
+---
+
+# Is i18next Outdated in 2026?
+
+`i18next` launched in 2011, long before React components, Webpack bundling, or TypeScript became standard. It won the ecosystem by being flexible and omnipresent, earning plugins for every stack and an answer on StackOverflow for every possible bug.
+
+It isn't abandoned; patches still land regularly. But there is a real difference between keeping an older engine running and actively evolving with modern frontend architecture.
+
+Over the last few years, frontend moved toward build-time compilation, React Server Components (RSC), aggressive tree-shaking, and AI-driven workflows. i18next's core remains what it was over a decade ago: a runtime singleton resolving string keys on the client.
+
+<TOC/>
+
+## Key Takeaways
+
+**Maintenance mode:**
+
+Over the past year, `next-i18next` logged ~63 commits (roughly one a week) and `react-i18next` ~157, mostly for dependency bumps and minor fixes.
+
+**Heavy runtime penalty:**
+
+`react-i18next` and `next-i18next` inject ~17–18 KB gzipped (~60 KB minified) before rendering a single translated word, nearly 4x `next-intlayer` (~4.7 KB).
+
+**Severe bundle leakage:**
+
+In default static setups, up to **89.8%** of the localisation payload sent to a page belongs to other routes or unread languages.
+
+**Tree-shaking is impossible:**
+
+Dynamic string calls like `t("home.hero.title")` cannot be analysed by bundlers, forcing entire JSON catalogues into the client chunk.
+
+**Business incentives:**
+
+The maintainers run Locize. Building a zero-cost, local AI translation pipeline directly into the CLI would directly compete with their primary revenue stream.
+
+## Maintenance vs. Active Evolution
+
+GitHub stars reflect historical adoption rather than current architectural momentum.
+
+| Repository              | Stars                                                                                                                                                      | Total commits                                                                                                                                                           | Commits / year                                                                                                                                                         | Last commit                                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `i18next/i18next`       | [![stars](https://img.shields.io/github/stars/i18next/i18next?style=for-the-badge&label=stars)](https://github.com/i18next/i18next/stargazers)             | [![commits](https://img.shields.io/github/commit-activity/t/i18next/i18next?style=for-the-badge&label=commits)](https://github.com/i18next/i18next/commits)             | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/i18next/commits)             | [![last](https://img.shields.io/github/last-commit/i18next/i18next?style=for-the-badge)](https://github.com/i18next/i18next/commits)             |
+| `i18next/react-i18next` | [![stars](https://img.shields.io/github/stars/i18next/react-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/react-i18next/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/i18next/react-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/react-i18next/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/react-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/react-i18next/commits) | [![last](https://img.shields.io/github/last-commit/i18next/react-i18next?style=for-the-badge)](https://github.com/i18next/react-i18next/commits) |
+| `i18next/next-i18next`  | [![stars](https://img.shields.io/github/stars/i18next/next-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/next-i18next/stargazers)   | [![commits](https://img.shields.io/github/commit-activity/t/i18next/next-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/next-i18next/commits)   | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/next-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/next-i18next/commits)   | [![last](https://img.shields.io/github/last-commit/i18next/next-i18next?style=for-the-badge)](https://github.com/i18next/next-i18next/commits)   |
+| `aymericzip/intlayer`   | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers)     | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)     | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits)     | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)     |
+
+Activity across the trailing twelve months:
+
+| Project         | Lifetime commits | Last 12 months | Focus                                     |
+| --------------- | ---------------- | -------------- | ----------------------------------------- |
+| `next-i18next`  | 1,311            | **63**         | Next.js compatibility bumps & patch fixes |
+| `react-i18next` | 1,988            | **157**        | Types & maintenance                       |
+| `i18next` core  | 2,626            | **259**        | Minor patches                             |
+| Intlayer        | 7,156            | **4,343**      | Compiler, IDE tooling & AI engine         |
+
+[![Star History Chart](https://api.star-history.com/chart?repos=i18next%2Fi18next%2Ci18next%2Freact-i18next%2Ci18next%2Fnext-i18next%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/i18next&i18next/react-i18next&i18next/next-i18next&aymericzip/intlayer)
+
+A small library can be complete and stable. But i18n tooling didn't freeze: modern bundlers now eliminate unreferenced copy at build time, LLMs handle translations instantly in CI, and editors rely on dedicated Language Servers (LSP) and AI agents. Because i18next relies on an open runtime plugin model, compilers cannot inspect it, leaving it stuck in place.
+
+## Measuring the Bundle Cost
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Measured in a production browser build across 10 routes and 10 locales with gzip compression. Details in the [i18n benchmark report](https://intlayer.org/doc/benchmark).
+
+### Baseline Framework Overhead
+
+Footprint before adding any translated text:
+
+| Library                | Gzipped    | Minified    |
+| ---------------------- | ---------- | ----------- |
+| `next-i18next@16.0.5`  | 17.8 KB    | 61.2 KB     |
+| `react-i18next@17.0.2` | 17.3 KB    | 59.8 KB     |
+| `intlayer@8.7.12`      | **4.7 KB** | **12.8 KB** |
+
+### Page Weight and Leakage
+
+Tested in React / TanStack Start (static strategy):
+
+| Library               | Page JS avg (gz) | Locale leak | Other-page leak | Avg component (gz) | Hydration   |
+| --------------------- | ---------------- | ----------- | --------------- | ------------------ | ----------- |
+| `react-i18next`       | 180.3 KB         | **50.0%**   | **89.8%**       | 24.3 KB            | 85.1 ms     |
+| Intlayer              | **127.8 KB**     | 50.0%       | **0.8%**        | **7.1 KB**         | **24.1 ms** |
+| Intlayer (scoped dyn) | **118.1 KB**     | **0.0%**    | **0.8%**        | **4.6 KB**         | 23.7 ms     |
+
+On Next.js:
+
+| Library         | Page JS avg (gz) | Other-page leak | Avg component (gz) |
+| --------------- | ---------------- | --------------- | ------------------ |
+| Base (no i18n)  | 150.8 KB         | 0.0%            | 0.7 KB             |
+| `next-i18next`  | **227.5 KB**     | **89.8%**       | 24.5 KB            |
+| `next-intlayer` | **152.1 KB**     | **0.0%**        | **7.2 KB**         |
+
+### Key Findings
+
+**Page weight:**
+
+On Next.js, `next-i18next` adds **76.7 KB gzipped** over baseline, a ~50% jump. `next-intlayer` adds just 1.3 KB.
+
+**Copy leakage:**
+
+In default setups, nearly **90% of localised text** sent to a route belongs to other pages. Manual namespacing helps, but requires brittle route-by-route bookkeeping.
+
+**Hydration lag:**
+
+Components using `react-i18next` took **85 ms** to hydrate versus **24 ms** with Intlayer. Passing large message trees to client components hurts time-to-interactive.
+
+## Why Is i18next Heavy?
+
+### Decades of Runtime Feature Creep
+
+Operating purely in the browser means shipping every capability upfront: interpolation, pluralisation rules, context resolution, formatting registries, and event buses. Even basic string swaps pay for the entire engine.
+
+### Dynamic String Keys Break Tree-Shaking
+
+Because `"hero.title"` is evaluated dynamically at runtime, bundlers cannot verify which keys are accessed. Unused strings in your message files cannot be tree-shaken.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```tsx fileName="Component.tsx"
+const { t } = useTranslation("home");
+
+return <h1>{t("hero.title")}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```tsx fileName="Hero.tsx"
+const { title } = useIntlayer("hero");
+
+return <h1>{title}</h1>;
+```
+
+  </Tab>
+</Tabs>
+
+The [Intlayer compiler](https://intlayer.org/doc/compiler) inspects what `Hero.tsx` actually consumes and tree-shakes unreferenced fields before emitting client bundles. See [bundle optimisation](https://intlayer.org/doc/concept/bundle-optimization) for architectural details.
+
+## Developer Experience
+
+### Disconnected JSON vs. Co-Location
+
+i18next separates copy from code across multiple JSON directories and hook calls. Intlayer co-locates content declarations right beside components.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```json fileName="locales/en/hero.json"
+{
+  "title": "Ship in every language"
+}
+```
+
+```json fileName="locales/fr/hero.json"
+{
+  "title": "Livrez dans toutes les langues"
+}
+```
+
+```tsx fileName="Hero.tsx"
+import { useTranslation } from "react-i18next";
+
+export const Hero = () => {
+  const { t } = useTranslation("hero");
+  return <h1>{t("title")}</h1>;
+};
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      fr: "Livrez dans toutes les langues",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+When you move or delete `Hero.tsx`, its copy moves or gets deleted alongside it.
+
+### Autocomplete vs. Strict Type Safety
+
+Augmenting `CustomTypeOptions` gives IDE autocomplete for keys, but does not guarantee safety. Deleting a key from `fr/home.json` won't fail your build; it only triggers a runtime fallback.
+
+Intlayer infers types directly from content declarations, and [`strictMode`](https://intlayer.org/doc/concept/configuration) turns missing translations into strict build errors.
+
+### Tooling Comparison
+
+| Feature                   | i18next Ecosystem  | Intlayer                                                               |
+| ------------------------- | ------------------ | ---------------------------------------------------------------------- |
+| **VS Code Extension**     | Third-party only   | ✅ [First-party extension](https://intlayer.org/doc/vs-code-extension) |
+| **Language Server (LSP)** | ❌ None            | ✅ [Dedicated LSP](https://intlayer.org/doc/lsp)                       |
+| **MCP Server (for AI)**   | ❌ None            | ✅ [Built-in MCP server](https://intlayer.org/doc/mcp-server)          |
+| **Agent Skills**          | ❌ None            | ✅ [Agent skills](https://intlayer.org/doc/agent_skills)               |
+| **Visual In-Context CMS** | Locize (Paid SaaS) | ✅ [Free & Open Source](https://intlayer.org/doc/concept/editor)       |
+
+## Translation and the Locize Incentive
+
+Locize is the official commercial service created by the makers of i18next. While open source needs sustainable funding, this business model creates an obvious incentive: a library monetised through a SaaS translation platform has little reason to build a free, local AI translation command into its CLI.
+
+Intlayer takes an open approach:
+
+- [`intlayer fill`](https://intlayer.org/doc/concept/auto-fill) fills missing translations in your terminal or CI using your own OpenAI, Anthropic, Mistral, or Gemini API keys.
+- The [Intlayer CMS](https://intlayer.org/doc/concept/cms) is open source and self-hostable via Docker Compose.
+- The compiler, CLI, editor, and CMS are all Apache 2.0.
+
+## Where i18next Still Fits
+
+<AccordionGroup>
+<Accordion header="Stable legacy codebases">
+
+If your app runs smoothly and bundle size isn't a bottleneck, rewriting it isn't urgent.
+
+</Accordion>
+<Accordion header="Exotic platforms">
+
+i18next's vast plugin ecosystem supports setups (Electron, older jQuery apps, custom native bridges) modern compilers don't target.
+
+</Accordion>
+<Accordion header="Huge community archive">
+
+An established StackOverflow and GitHub footprint helps with niche edge cases.
+
+</Accordion>
+</AccordionGroup>
+
+## How to Improve My Existing i18next Setup?
+
+Intlayer offers drop-in compatibility packages that preserve the exact function signatures of i18next libraries (`i18next`, `react-i18next`, and `next-i18next`). You do not need to rewrite your components to start benefiting from a compiler-driven architecture.
+
+Setup takes a single command:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+This interactive CLI:
+
+1. Installs the `@intlayer/i18next` compatibility package.
+2. Configures bundler aliases so your existing imports (`useTranslation`, `Trans`, `t`) route to Intlayer, allowing you to remove the old library from `package.json`.
+3. Sets up out-of-the-box IDE language server (LSP) diagnostics, build-time tree-shaking optimizations, and local AI translation workflows.
+
+For step-by-step instructions, explore our dedicated guides:
+
+- **Compatibility shims:** Keep your current syntax with the [i18next compatibility layer](https://intlayer.org/doc/compatibility/i18next), [react-i18next compatibility layer](https://intlayer.org/doc/compatibility/react-i18next), or [next-i18next compatibility layer](https://intlayer.org/doc/compatibility/next-i18next).
+- **Full catalogue migration:** Convert legacy JSON files into type-safe dictionaries using our guides: [from i18next](https://intlayer.org/doc/migration/i18next), [from react-i18next](https://intlayer.org/doc/migration/react-i18next), or [from next-i18next](https://intlayer.org/doc/migration/next-i18next).
+- **Hybrid approach:** Retain your existing runtime while [using Intlayer alongside i18next](https://intlayer.org/blog/intlayer-with-i18next) to generate and translate catalogues automatically.
+
+Scan your live website with the [i18n SEO Scanner](https://intlayer.org/i18n-seo-scanner):
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Related Reading
+
+- [Next.js i18n Benchmark Deep Dive](https://intlayer.org/doc/benchmark/nextjs)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [Is next-intl Outdated in 2026?](https://intlayer.org/blog/is-next-intl-outdated)
+- [Compiler vs. Declarative i18n Architectures](https://intlayer.org/blog/compiler-vs-declarative-i18n)