@intlayer/docs 9.4.2 → 9.4.4

package/blog/en/list_i18n_technologies/frameworks/tanstack-start.md

@@ -0,0 +1,280 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "TanStack Start i18n: locale routing, SSR and the type tax"
+description: How to wire i18n into TanStack Start, a $locale route segment, beforeLoad negotiation, SSR and prerender, and why the generated route tree fights back.
+keywords:
+  - tanstack start i18n
+  - TanStack Router locale
+  - TanStack Start internationalization
+  - locale routing
+  - react-i18next
+  - SSR hydration
+  - prerender
+slugs:
+  - blog
+  - i18n-technologies
+  - frameworks
+  - tanstack-start
+author: aymericzip
+---
+
+# TanStack Start i18n: locale routing, SSR and the type tax
+
+TanStack Start ships no i18n layer, and unlike Next.js or Nuxt there is no first-party module to fill the gap. So the interesting question is not "which library", it is how a locale fits into a generated, type-safe route tree without breaking every `Link` in the app. This post covers the wiring: the route segment, the negotiation, SSR and prerender, and the honest state of the options.
+
+<iframe title="The best i18n solution for Tanstack Start? Discover Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/_XTdKVWaeqg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
+
+## Table of Contents
+
+<TOC/>
+
+## Put the locale in the URL, not in a cookie
+
+The tempting shortcut is a cookie: read it on the server, set the locale, done. It works in development and fails everywhere else. One URL then serves several languages, so you cannot emit `hreflang`, you cannot prerender a page per locale, and a crawler sees whichever language your negotiation happens to pick.
+
+A route segment fixes all three at once. In TanStack Router's file-based routing that means a directory:
+
+```txt
+src/routes/
+  __root.tsx
+  {-$locale}/
+    route.tsx        // locale layout + validation
+    index.tsx        // /en, /fr, /
+    about.tsx        // /en/about, /fr/about
+    $.tsx            // catch-all 404 inside the locale
+```
+
+The braces make the segment optional. `{-$locale}` matches `/about` and `/fr/about`, which is what you want when the default locale has no prefix. If every locale is prefixed, use plain `$locale` instead. Be careful stacking it with other dynamic segments in the same route, `{-$locale}/$slug` is ambiguous by construction.
+
+## Negotiate in `beforeLoad`, not in a component
+
+`beforeLoad` runs on the server and on the client, before the route renders, and it can throw a redirect. That is the right hook for locale work: an unknown prefix must 404 rather than silently resolve.
+
+```tsx fileName="src/routes/{-$locale}/route.tsx"
+import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
+import { validatePrefix } from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}")({
+  beforeLoad: ({ params }) => {
+    const { isValid, localePrefix } = validatePrefix(params.locale);
+
+    if (!isValid) {
+      throw redirect({
+        to: "/{-$locale}/404",
+        params: { locale: localePrefix },
+      });
+    }
+  },
+  component: Outlet,
+});
+```
+
+Without that check, `/xx/about` matches the segment, renders in your default language, and gets indexed as a duplicate of `/about`. This is the single most common i18n bug I see on file-based routers.
+
+`Accept-Language` negotiation for a first visit belongs one layer lower, in server middleware, so the redirect happens before the router boots. Intlayer's Vite plugin registers a proxy that does this and writes the locale cookie; if you wire it yourself, remember to exclude `/api` and asset paths.
+
+## The type tax nobody mentions
+
+This is the part that surprises people. TanStack Router generates `routeTree.gen.ts` and types every `to` prop against it. Add a locale directory and every path in your app changes shape:
+
+```tsx
+// before
+<Link to="/about" />
+
+// after: this no longer type-checks
+<Link to="/{-$locale}/about" params={{ locale: "fr" }} />
+```
+
+You do not want that literal in three hundred call sites. The usual fix is one wrapper component that strips the prefix from the public type and re-adds it at runtime:
+
+```tsx fileName="src/components/localized-link.tsx"
+import { Link, type LinkComponentProps } from "@tanstack/react-router";
+import { getPrefix } from "intlayer";
+import { useLocale } from "react-intlayer";
+
+export const LOCALE_ROUTE = "{-$locale}" as const;
+
+export type StripLocalePrefix<T extends string | undefined> =
+  T extends `/${typeof LOCALE_ROUTE}/${infer Rest}` ? `/${Rest}` : T;
+
+export type To = StripLocalePrefix<LinkComponentProps["to"]>;
+
+export const LocalizedLink = (
+  props: { to?: To } & Omit<LinkComponentProps, "to">
+) => {
+  const { locale } = useLocale();
+  const { localePrefix } = getPrefix(locale);
+
+  return (
+    <Link
+      {...props}
+      to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]}
+      params={{
+        locale: localePrefix,
+        ...(typeof props.params === "object" ? props.params : {}),
+      }}
+    />
+  );
+};
+```
+
+Do the same for `useNavigate`. Budget an afternoon for this and a codemod pass over existing links: it is real work, and it is independent of which translation library you pick.
+
+## SSR, hydration and prerender
+
+Resolve the locale from route params in the root shell, and server and client cannot disagree, because both read the same URL:
+
+```tsx fileName="src/routes/__root.tsx"
+const localeRoute = getRouteApi("/{-$locale}");
+
+function RootDocument({ children }: { children: ReactNode }) {
+  const locale = localeRoute.useParams()?.locale ?? defaultLocale;
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
+
+Read the locale from `navigator.language` or `localStorage` during render instead, and you get a hydration mismatch on every visitor whose browser disagrees with the server. The symptom is React error #418 in production and text that flickers from one language to another.
+
+Prerendering is where the URL choice pays off. You expand your path list across locales and hand TanStack Start a page per localized route:
+
+```ts fileName="vite.config.ts"
+import { localeFlatMap } from "intlayer";
+
+const pathList = ["", "/about", "/404"];
+
+const localizedPages = localeFlatMap(({ urlPrefix }) =>
+  pathList.map((path) => ({
+    path: `${urlPrefix}${path}`,
+    prerender: { enabled: true },
+  }))
+);
+```
+
+One gotcha specific to this stack: if you colocate content files inside `src/routes`, the router will try to turn them into routes. Exclude them with `routeFileIgnorePattern` in the `tanstackStart()` plugin options.
+
+## Loaders vs static strings
+
+Two different things get conflated. UI strings ("Add to cart", "Loading") are static, known at build time, and belong in the component, not in a loader. Localized _data_ (a product description from your CMS) is a fetch, and belongs in `loader` so it streams with the route.
+
+Route metadata sits between the two, because `head` runs outside the React tree. You have three options and they trade off differently:
+
+|                  | Sync read in `head`  | Async read in `head`                                               | Read in `loader`, use in `head`       |
+| :--------------- | :------------------- | :----------------------------------------------------------------- | :------------------------------------ |
+| `head` signature | synchronous          | `async`                                                            | synchronous, reads `loaderData`       |
+| Locales shipped  | all declared locales | requested locale only                                              | requested locale only                 |
+| Cost             | bigger route chunk   | dictionary import on the head critical path, so slightly worse LCP | content threaded through `loaderData` |
+
+The loader variant with `staleTime: Infinity` is the one I would default to on a real site: loaders of matched routes run in parallel, and the result is cached per locale.
+
+## The options today
+
+The ecosystem here is thin. Most TanStack Start apps wire `react-i18next` by hand, because that is what the React answers on the internet describe, and it does work.
+
+| Option          | How you wire it                                                                     | Note                                                                                                                                                                                   |
+| :-------------- | :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `react-i18next` | Manual: provider in the root shell, catalogs per namespace, your own loader for SSR | Largest ecosystem. Around 17.3 kB in the [TanStack benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/tanstack.md), and namespace discipline is on you |
+| `use-intl`      | Manual, same shape, ICU messages                                                    | Avoids the Next.js specific traps of `next-intl`; leakage problem is identical                                                                                                         |
+| Lingui          | `lingui extract` / `lingui compile` in the build                                    | Compile step, ICU. I found the workflow heavier than it needed to be with no clear win here                                                                                            |
+| Paraglide       | Codegen of message functions                                                        | The advertised tree-shaking did not hold up in the benchmark, and it re-reads the locale from storage per node instead of a store                                                      |
+| Intlayer        | Vite plugin, build-time compilation                                                 | Covers routing, prerender and sitemap; smaller ecosystem                                                                                                                               |
+
+None of them solve the route-tree typing problem for you. That wrapper is yours to write either way.
+
+## Intlayer on TanStack Start
+
+Intlayer's model is one content file per component, compiled at build time into per-component dictionaries. For this stack the practical difference is that locale routing, the prerender pass and the sitemap are covered by the same package rather than assembled from three.
+
+```ts fileName="src/routes/{-$locale}/about.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "about",
+  content: {
+    title: t({ en: "About", fr: "À propos", es: "Acerca de" }),
+    intro: t({
+      en: "We build tooling for multilingual apps.",
+      fr: "Nous construisons des outils pour les apps multilingues.",
+      es: "Creamos herramientas para apps multilingües.",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="src/routes/{-$locale}/about.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+import { useIntlayer } from "react-intlayer";
+
+export const Route = createFileRoute("/{-$locale}/about")({
+  component: () => {
+    const { title, intro } = useIntlayer("about");
+    return (
+      <>
+        <h1>{title}</h1>
+        <p>{intro}</p>
+      </>
+    );
+  },
+});
+```
+
+`useIntlayer` inside components, `getIntlayer` or `getIntlayerAsync` outside the React tree (route `head`, loaders, server functions). In a server function, `getLocale` reads the cookie or header for you. Setup is `npx intlayer init`, plus the `intlayer()` plugin in `vite.config.ts`. As a data point, intlayer.org itself runs on TanStack Start.
+
+<Tabs defaultTab="code">
+  <Tab label="Code" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-tanstack-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-tanstack-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-tanstack-start-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+**What it costs you.** A build plugin is mandatory: no plugin, no dictionaries, and that includes your test runner config. The project is younger and much smaller than i18next, so when something breaks on a TanStack Start canary you are reading source, not Stack Overflow. ICU message format is not fully supported, which matters if a translation vendor delivers ICU strings today. And the per-component model means you cannot hand a translator one big JSON file without going through the CLI or the CMS.
+
+Coming from an existing codebase, the [`@intlayer/react-i18next` compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/react-i18next.md) keeps `useTranslation()` and `t()` working while Intlayer serves the content, and the [migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_react-i18next_to_intlayer.md) covers moving off it afterwards.
+
+## Common mistakes
+
+- **Locale in a cookie only.** No `hreflang`, no prerender, one URL per page for every language. Fix the URL scheme first, pick the library second.
+- **No prefix validation.** `/xx/about` rendering your default language is a duplicate-content bug that only shows up in Search Console, months later.
+- **Reading the locale on the client during render.** Route params are the only source both sides agree on.
+- **A `<button>` locale switcher.** Crawlers do not click. Render locale links as anchors pointing at the localized URL.
+- **Content files inside `src/routes`.** They become routes unless you set `routeFileIgnorePattern`.
+- **Awaiting dictionaries serially in `head`.** Use `Promise.all` if a head reads more than one.
+
+## Going further
+
+- [Full TanStack Start setup guide, step by step](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_tanstack.md)
+- [TanStack Start i18n benchmark: bundle size, leakage, locale-switch timings](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/tanstack.md)
+- [Drop-in `react-i18next` compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/react-i18next.md) and the [react-i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_react-i18next_to_intlayer.md)
+- [The wider React i18n landscape](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/react.md)
+- [Per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md)
+- [Getting hreflang right on a multilingual site](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/hreflang_guide_multilingual_seo.md)
+- [Routing modes, domains and URL schemes in the configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)

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

@@ -1,16 +1,16 @@
 ---
 createdAt: 2025-01-16
-updatedAt: 2026-05-31
-title: Best Vue i18n Libraries 2026 — Compared by DX & Bundle
-description: Best solution for bundle size, SEO, performances & maintainability. Make your Vue app multilingual in 2026, LLM translation, Agent Skills & MCP.
+updatedAt: 2026-09-02
+title: Vue i18n - how it works and where it breaks at scale
+description: How vue-i18n works in Vue 3, the three places it hurts once your app grows (key sprawl, untyped keys, bundle size), and the alternatives worth a look.
 keywords:
-  - Vue
-  - i18n
-  - multilingual
-  - SEO
-  - Internationalization
-  - Blog
-  - JavaScript
+  - vue i18n
+  - vue-i18n
+  - Vue 3 internationalization
+  - useI18n
+  - Nuxt i18n
+  - Composition API
+  - Intlayer
 slugs:
   - blog
   - i18n-technologies
@@ -19,127 +19,199 @@ slugs:
 author: aymericzip
 ---
 
-# Exploring i18n Solutions to Translate Your Vue.js Website
+# Vue i18n: how it works, and where it starts to hurt
 
-In an increasingly globalized digital landscape, extending your Vue.js website’s reach to users in multiple languages is no longer a “nice-to-have” it’s a competitive necessity. Internationalization (i18n) enables developers to manage translations and adapt their applications for various locales while preserving SEO value, user experience, and maintainable code structures. In this article, we’ll explore different approaches ranging from dedicated libraries to custom-coded solutions that help you integrate i18n into your Vue.js project smoothly.
+If you searched "vue i18n" you have already found `vue-i18n`, and it is the right default for most Vue apps. What is less documented is how it behaves once you pass ten pages and five locales. This post covers the mechanics, the three friction points that show up at scale, and what the alternatives actually change.
 
----
+<iframe title="The best i18n solution for Vite and Vue? Discover Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/IE3XWkZ6a5U?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
+## Table of Contents
 
-## What is Internationalization (i18n)?
+<TOC/>
 
-Internationalization (i18n) is the practice of preparing a software application (or website) for multiple languages and cultural conventions. Within the Vue.js ecosystem, this includes establishing how text, dates, numbers, currency, and other localizable elements can be adapted to various locales. By setting up i18n from the start, you ensure an organized, scalable structure for adding new languages and handling future localization needs.
+## The two things "Vue i18n" means
 
-To learn more about i18n basics, check out our reference: [What is Internationalization (i18n)? Definition and Challenges](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md).
+One is the practice: shipping a Vue app in several languages, with localized routes, formatted dates and numbers, and correct `hreflang`. The other is `vue-i18n`, the Intlify library that most Vue apps use to do it.
 
----
+They are not the same decision. Picking the library is ten minutes; the practice is what you live with for the next two years. If the concept itself is new, start with [what internationalization actually covers](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md) and the [difference between i18n, l10n and t9n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18n_meaning.md).
 
-## The Translation Challenge for Vue Applications
+## How vue-i18n works
 
-Translating a Vue.js application brings its own set of challenges:
+You build one message catalog per locale and register it as a plugin.
 
-- **Component-Based Architecture:** Similar to React, Vue’s single-file components (SFCs) may each contain text and locale-specific settings. You’ll need a strategy to centralize translation strings.
-- **Dynamic Content:** Data fetched from APIs or manipulated in real time requires a flexible approach to load and apply translations on the fly.
-- **SEO Considerations:** With server-side rendering via Nuxt or other SSR setups, it’s critical to manage localized URLs, meta tags, and sitemaps to maintain strong SEO.
-- **State and Reactive Context:** Ensuring that the current locale is maintained across routes and components reactively updating texts and formats requires a thoughtful approach, especially when dealing with Vuex or Pinia for state management.
-- **Development Overhead:** Keeping translation files organized, consistent, and up to date can quickly become a major task if not managed carefully.
+```ts fileName="src/i18n.ts"
+import { createI18n } from "vue-i18n";
 
----
+export const i18n = createI18n({
+  legacy: false, // Composition API mode
+  locale: "en",
+  fallbackLocale: "en",
+  messages: {
+    en: {
+      cart: { total: "Total", items: "no item | one item | {count} items" },
+    },
+    fr: {
+      cart: {
+        total: "Total",
+        items: "aucun article | un article | {count} articles",
+      },
+    },
+  },
+});
+```
 
-## Leading i18n Solutions for Vue.js
+Inside a single-file component you read from it with `useI18n()`:
 
-Below are several popular libraries and approaches you can use to incorporate internationalization into your Vue applications. Each aims to streamline translation, SEO, and performance considerations in different ways.
+```vue fileName="src/components/CartSummary.vue"
+<script setup lang="ts">
+import { useI18n } from "vue-i18n";
 
----
+const { t, n, locale } = useI18n();
+</script>
 
-### 1. Intlayer
+<template>
+  <h2>{{ t("cart.total") }}</h2>
+  <p>{{ t("cart.items", { count: 3 }, 3) }}</p>
+  <p>{{ n(42.5, "currency") }}</p>
+</template>
+```
 
-> Website: [https://intlayer.org/](https://intlayer.org/)
+Three mechanics matter more than the API surface:
 
-**Overview**  
-**Intlayer** is an open-source i18n solution that aims to simplify multi-language support across multiple frameworks, including **Vue**. It emphasizes a declarative approach, strong typing, and SSR support in other ecosystems, although SSR is not typical in standard Vue.
+- **Legacy vs Composition mode.** `legacy: true` keeps the Vue 2 behaviour and exposes `$t` / `$tc` globally on every component instance. `legacy: false` gives you `useI18n()` and proper types. New apps should use `false`; mixing the two in one codebase is where most "why is `$t` undefined here" bugs come from.
+- **Messages are compiled, not interpolated at read time.** Each message string is turned into a render function. With the default build that compilation happens in the browser, at runtime. Adding `@intlify/unplugin-vue-i18n` moves it to build time and lets you ship the runtime-only build, which is both smaller and CSP-friendly, since the runtime compiler relies on `new Function`.
+- **Plurals are pipe-separated, not ICU.** `"no item | one item | {count} items"` is vue-i18n's own format. It is compact, but it is not portable to any other tool, and translators need to be told about it.
 
-**Key Features**
+## Where it starts to hurt
 
-- **Declarative Translation**: Define translation dictionaries either at the widget level or in a centralized file for a cleaner architecture.
-- **TypeScript & Autocompletion (Web)**: While this feature primarily benefits web frameworks, the typed translation approach can still guide structured code in Vue.
-- **Asynchronous Loading**: Load translation assets dynamically, potentially reducing the initial bundle size for multi-language apps.
-- **Integration with Vue**: A basic integration can be set up to leverage the Intlayer approach for structured translations.
+### 1. Keys are strings with no link back to the component
 
-### 2. Vue I18n
+`t("cart.items")` is a string. Nothing connects it to `CartSummary.vue`. Delete the component and the key stays in every locale file forever; rename a nesting level and you find out at runtime, in the locale nobody tests.
 
-> Website: [https://vue-i18n.intlify.dev/](https://vue-i18n.intlify.dev/)
+At ten components this is fine. At three hundred, across a `locales/en.json` that several teams edit, key sprawl is the actual maintenance cost, not the translation itself.
 
-**Overview**  
-**Vue I18n** is the most widely used localization library in the Vue ecosystem, providing a straightforward and feature-rich way to handle translations in Vue 2, Vue 3, and Nuxt-based projects.
+### 2. Key type safety is opt-in and awkward
 
-**Key Features**
+vue-i18n can be typed by passing a message schema generic to `createI18n`, which gives autocompletion on `t()`. It works, but you have to wire it yourself, and it fights with lazily loaded catalogs: the schema describes messages that may not be loaded yet, so the types stop reflecting runtime reality.
 
-- **Simple Setup**  
-  Quickly configure localized messages and switch locales using a well-documented API.
-- **Reactivity**  
-  Locale changes instantly update text across components thanks to Vue’s reactivity system.
-- **Pluralization & Date/Number Formatting**  
-  Built-in methods handle common use cases, including plural forms, date/time formatting, number/currency formatting, and more.
-- **Nuxt.js Support**  
-  Nuxt I18n module extends Vue I18n for automatic route generation, SEO-friendly URLs, and sitemaps for each locale.
-- **TypeScript Support**  
-  Can be integrated with TypeScript-based Vue apps, though autocompletion for translation keys may require additional configuration.
-- **SSR & Code Splitting**  
-  Works seamlessly with Nuxt for server-side rendering, and supports code splitting for translation files to boost performance.
+Out of the box, a typo in a key produces a warning in the console and the raw key on screen.
 
-**Considerations**
+### 3. Lazy loading exists, scoping does not
 
-- **Configuration Overhead**  
-  Large or multi-team projects may require a clear folder structure and naming conventions to manage translation files efficiently.
-- **Plugin Ecosystem**  
-  While robust, you may need to carefully select from multiple plugins or modules (Nuxt I18n, Vue I18n, etc.) to build a perfect setup.
+vue-i18n supports async messages, so you can avoid shipping all locales at once:
 
----
+```ts
+const messages = await import(`./locales/${locale}.json`);
+i18n.global.setLocaleMessage(locale, messages.default);
+```
 
-### 3. LinguiJS (Vue Integration)
+What it does not give you is a per-page split. A locale catalog is one object; loading it loads every page's copy. In a plain SPA nobody notices. In a Nuxt app with `@nuxt/i18n` and more than ten pages, every route ends up carrying the messages of every other route.
 
-> Website: [https://lingui.js.org/](https://lingui.js.org/)
+The [Vue i18n benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/vue.md) measures the library cost separately from the content cost, on a 10-page / 10-locale app: `vue-i18n@11.4.0` weighs about **24.3 kB** after bundling and minification, roughly **9× `vue-intlayer`**. `fluent-vue` comes in around **92.7 kB**, about 34×, and its Vite plugin loads all content in all languages into every page.
 
-**Overview**  
-Originally known for its React integration, **LinguiJS** also offers a Vue plugin that focuses on minimal runtime overhead and an automated message extraction workflow.
+## Vite and Nuxt are not the same setup
 
-**Key Features**
+| Concern                        | Plain Vite + Vue Router | Nuxt                                         |
+| :----------------------------- | :---------------------- | :------------------------------------------- |
+| Locale-prefixed routes         | You write them          | `@nuxt/i18n` generates them                  |
+| `hreflang`, sitemap, redirects | Manual                  | Module handles most of it                    |
+| SSR / prerender                | Not by default          | Yes, and messages must resolve on the server |
+| Catalog splitting              | Your problem            | Still your problem                           |
 
-- **Automatic Message Extraction**  
-  Use the Lingui CLI to scan your Vue code for translations, reducing manual entry of message IDs.
-- **Compact & Performant**  
-  Compiled translations lead to a smaller runtime footprint, essential for high-performing Vue applications.
-- **TypeScript & Autocompletion**  
-  While slightly more manual to configure, typed IDs and catalogs can improve the developer experience in TypeScript-based Vue projects.
-- **Nuxt & SSR Compatibility**  
-  Can integrate with SSR setups to serve fully localized pages, improving SEO and performance for each supported locale.
-- **Pluralization & Formatting**  
-  Built-in support for plurals, number formatting, dates, and more aligning with ICU message format standards.
+Most "vue i18n is slow" reports come from Nuxt apps, because SSR makes the catalog cost visible in the HTML payload as well as the JS bundle.
 
-**Considerations**
+## The alternatives
 
-- **Less Vue-Specific Documentation**  
-  While LinguiJS has official support for Vue, its documentation primarily focuses on React; you may need to rely on community examples.
-- **Smaller Community**  
-  Compared to Vue I18n, there’s a relatively smaller ecosystem. Officially maintained plugins and third-party add-ons can be more limited.
+| Library      | Content model                                             | Type safety on keys         | Note                                                              |
+| :----------- | :-------------------------------------------------------- | :-------------------------- | :---------------------------------------------------------------- |
+| `vue-i18n`   | Central catalogs per locale, optional SFC `<i18n>` blocks | Opt-in via a schema generic | The ecosystem default, largest community, ICU-adjacent formatting |
+| `fluent-vue` | `.ftl` files (Mozilla Fluent)                             | None                        | Nice message syntax, very heavy in the benchmark                  |
+| Intlayer     | One `.content.ts` per component, colocated                | Generated, on by default    | Requires a build plugin, smaller ecosystem                        |
 
----
+## Intlayer: content declared next to the component
+
+Intlayer's difference is one design choice: the content lives in a file beside the component that renders it, and a build plugin compiles those declarations into per-component dictionaries.
+
+```ts fileName="src/components/cartSummary.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const cartSummaryContent = {
+  key: "cart-summary",
+  content: {
+    total: t({ en: "Total", fr: "Total", es: "Total" }),
+    vatNotice: t({
+      en: "VAT included",
+      fr: "TVA incluse",
+      es: "IVA incluido",
+    }),
+  },
+} satisfies Dictionary;
+
+export default cartSummaryContent;
+```
+
+```vue fileName="src/components/CartSummary.vue"
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+
+const { total, vatNotice } = useIntlayer("cart-summary");
+</script>
+
+<template>
+  <h2><total /></h2>
+  <small>{{ vatNotice }}</small>
+</template>
+```
+
+Both forms work: `<total />` renders a node that stays editable in the visual editor, `{{ vatNotice }}` gives you the plain string. Locale switching goes through `useLocale()`, which returns `locale`, `availableLocales` and `setLocale`.
+
+Because the key is declared in one file and consumed in one component, deleting the component deletes its content, and the compiler ships only the entries a route renders.
+
+<Tabs defaultTab="code">
+  <Tab label="Code" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-vite-vue-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-vue-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-vue-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` or `"nuxt-intlayer"` in `nuxt.config.ts`.
+
+**What it costs you.** A build step is mandatory: no bundler plugin, no dictionaries. The ecosystem is much smaller than vue-i18n's, so there are fewer Stack Overflow answers and fewer third-party integrations. ICU message format is still a work in progress, so if your translation vendor delivers ICU strings today, that is a real blocker.
+
+If you already have a vue-i18n codebase, the [`@intlayer/vue-i18n` compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/vue-i18n.md) aliases `vue-i18n` imports at the bundler level, so `useI18n()`, `$t`, pipe plurals and the `v-t` directive keep working while the content is served by Intlayer. The [step-by-step migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_vue-i18n_to_intlayer.md) covers moving off the adapter afterwards, component by component.
 
-## Final Thoughts
+## Trade-offs and common mistakes
 
-When deciding on an i18n solution for your Vue.js application:
+- **Shipping the full vue-i18n build.** If you are not using `@intlify/unplugin-vue-i18n`, you are shipping the message compiler to the browser and paying for it on every page.
+- **Leaving `legacy: true` in a Vue 3 app.** It works, but you lose `useI18n()` typing and you carry the Vue 2 compatibility layer.
+- **Treating locale files as append-only.** Nothing warns you about dead keys. Budget a periodic sweep, or pick a model where content is scoped to a component.
+- **Switching locale with a button instead of a link.** Crawlers do not click. Render locale switchers as `<a>` / `NuxtLink` pointing at the localized URL.
+- **Assuming a per-component model is free.** It is not: you gain scoping and types, you lose the ability to hand a translator one big JSON file without tooling.
 
-1. **Assess Your Requirements**  
-   Project size, developer skill set, and the complexity of localization all factor into your choice.
-2. **Evaluate SSR Compatibility**  
-   If you’re building a Nuxt app or otherwise depending on SSR, confirm that your chosen approach supports server rendering smoothly.
-3. **TypeScript & Autocompletion**  
-   If you value a strong developer experience with minimal translation key typos, ensure your solution offers typed definitions or can be integrated with them.
-4. **Manageability & Scalability**  
-   As you add more locales or expand your application, an organized translation file structure is crucial.
-5. **SEO & Metadata**  
-   For multilingual sites to rank well, your solution should simplify localized meta tags, URLs, sitemaps, and `robots.txt` for each locale.
+## Going further
 
-No matter which path you choose Intlayer, Vue I18n, LinguiJS, or a custom-coded approach you’ll be well on your way to delivering a global-friendly Vue.js application. Each solution offers different trade-offs regarding performance, developer experience, and scalability. By carefully assessing your project’s needs, you can confidently pick the i18n setup that sets you and your multilingual audience up for success.
+- [Vue i18n benchmark: bundle size, leakage and locale-switch timings](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/vue.md)
+- [Set up i18n in a Vite + Vue app](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+vue.md)
+- [Set up i18n in a Nuxt app](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nuxt.md)
+- [Drop-in `vue-i18n` compat adapter](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/vue-i18n.md) and the [full migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/migration_from_vue-i18n_to_intlayer.md)
+- [vue-i18n vs Intlayer, feature by feature](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/vue-i18n_vs_intlayer.md)
+- [Per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_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/what_is_internationalization.md

@@ -20,8 +20,6 @@ author: aymericzip
 
 # What is Internationalization (i18n)? Definition and challenges
 
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
 ## Understanding Internationalization (i18n)
 
 **Internationalization**, often abbreviated as **i18n**, is the process of designing and preparing an application to support multiple languages, cultures, and regional conventions **without** major changes to the codebase. The name i18n is derived from the fact that there are 18 letters between the **i** and the **n** in the word “internationalization.”