@intlayer/docs 9.4.1 → 9.4.3

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

@@ -1,16 +1,17 @@
 ---
 createdAt: 2025-01-16
-updatedAt: 2026-05-31
-title: Best Angular i18n Libraries 2026 — Compared by DX & Bundle
-description: Best solution for bundle size, SEO, performances & maintainability. Make your Angular app multilingual in 2026, LLM translation, Agent Skills & MCP.
+updatedAt: 2026-09-02
+title: Angular i18n - why the official one is build-time
+description: How @angular/localize compiles one bundle per locale, why that blocks in-app language switching, and when ngx-translate, Transloco or Intlayer fit better.
 keywords:
-  - Angular
-  - i18n
-  - multilingual
-  - SEO
-  - Internationalization
-  - Blog
-  - JavaScript
+  - angular i18n
+  - "@angular/localize"
+  - ngx-translate
+  - Transloco
+  - Angular internationalization
+  - XLIFF
+  - Angular signals
+  - Intlayer
 slugs:
   - blog
   - i18n-technologies
@@ -19,130 +20,205 @@ slugs:
 author: aymericzip
 ---
 
-# Exploring i18n Solutions to Translate Your Angular Website
+# Angular i18n: build-time by default, and what that costs you
 
-In today's interconnected world, offering your website in multiple languages can significantly expand your reach and improve user experience. For developers working with Angular, implementing internationalization (i18n) is crucial for efficiently managing translations while preserving application structure, SEO, and performance. In this article, we'll explore various i18n approaches from Angular's built-in solutions to popular third-party libraries to help you determine the best fit for your project.
+Angular is the only major front-end framework whose official i18n is build-time. `@angular/localize` extracts messages from your templates, merges a translation file per language, and emits one compiled application per locale. That single design choice decides your deployment shape, your SEO story, and whether an in-app language switcher is even possible.
 
----
-
-![i18n illustration](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
-
-## What is Internationalization (i18n)?
-
-Internationalization, often referred to as i18n, is the process of designing and preparing your application to support multiple languages and cultural contexts. In Angular, it entails configuring your app so that text, dates, numbers, and even UI layouts can adapt seamlessly to different locales. Laying this groundwork properly ensures that integrating future translations remains organized and efficient.
-
-Learn more about i18n basics 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).
-
----
-
-## The Translation Challenge for Angular Applications
-
-Translating an Angular application introduces several challenges:
-
-- **Component-Based Structure**: Angular's modular approach (with components, modules, and services) means translation strings can be scattered across your codebase, making it crucial to centralize and manage them effectively.
-- **Dynamic Content**: Handling real-time content (e.g., data from REST APIs, user-generated content) requires careful consideration to ensure new strings are also translated.
-- **SEO Considerations**: If you're using Angular Universal for server-side rendering, you'll need to set up localized URLs, meta tags, and sitemaps to make your multilingual pages search-engine-friendly.
-- **Routing and State**: Ensuring the correct language is maintained while navigating between routes involves state management and possibly custom route guards or interceptors.
-- **Scalability & Maintenance**: Translation files can grow quickly, and keeping them organized, versioned, and in sync with your application's evolution can be an ongoing task.
-
----
+## Table of Contents
 
-## Leading i18n Solutions for Angular
+<TOC/>
 
-Angular offers a built-in i18n framework, and there are several third-party libraries designed to simplify your multilingual setup. Below are some of the most popular solutions.
+## The fact that drives every other decision
 
-### 1. Intlayer
+In React or Vue, "i18n" means a runtime lookup: a string goes in, a translated string comes out, and switching locale is a state change. In Angular's official path, the lookup happens at compile time. By the time the browser has the code, the text is already French.
 
-> Website: [https://intlayer.org/](https://intlayer.org/)
+That is why `LOCALE_ID` is not something you set at runtime in a localized build, and why the Angular docs talk about deploying `/fr/` and `/es/` as separate directories rather than about a language dropdown. 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).
 
-**Overview**  
-**Intlayer** is an innovative, open-source internationalization (i18n) library designed to simplify multilingual support in modern Angular (and other) web applications. It offers a declarative approach, letting you define translation dictionaries directly within your components.
+## How `@angular/localize` works
 
-**Key Features**
+You mark text in templates with the `i18n` attribute, and text in TypeScript with the `$localize` tagged template.
 
-- **Translation Declaration**: Allows the declaration of 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 Angular Universal 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 Angular CLI and Angular Universal, making setup straightforward.
-- **Asynchronous Loading**: Dynamically load translation dictionaries, reducing initial bundle size and improving performance.
+```html fileName="src/app/welcome.component.html"
+<h1 i18n="site header|Banner shown on the home page@@welcomeTitle">Welcome</h1>
 
-**Considerations**
+<p i18n>
+  Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{minutes}}
+  minutes ago}}
+</p>
+```
 
-- **Community & Ecosystem**: Though growing, the ecosystem is newer, so community-driven plugins and tooling may be more limited compared to more established solutions.
+```ts fileName="src/app/welcome.component.ts"
+const greeting = $localize`Hello ${userName}:name:`;
+```
 
----
-
-### 2. Angular's Built-In i18n
-
-**Overview**  
-Angular ships with a **built-in i18n** system that includes tooling for extracting translation strings, handling pluralization and interpolation, and integrating translations at compile time. This official solution is powerful for smaller projects or those that can align closely with Angular's recommended structure.
-
-**Key Features**
-
-- **Native Integration**: No extra library is required; it works out of the box with Angular projects.
-- **Compile-Time Translations**: The Angular CLI extracts text for translations, and you build separate bundles per language. This approach can lead to faster runtime performance because translations are compiled in.
-- **Easy Plural & Gender Handling**: Built-in features for complex pluralization and message interpolation.
-- **AOT & Production Builds**: Fully compatible with Angular's Ahead-of-Time (AOT) compilation, ensuring optimized production bundles.
-
-**Considerations**
+Then you extract, translate, and build:
 
-- **Multiple Builds**: Each language requires its own build, which can lead to more complex deployment scenarios.
-- **Dynamic Content**: Handling real-time or user-driven content may require custom logic since Angular's built-in solution focuses heavily on compile-time translations.
-- **Limited Runtime Flexibility**: Switching languages on the fly (without reloading the app) can be challenging because translations are baked in at build time.
+```bash
+ng add @angular/localize
+ng extract-i18n --format=xlf2 --output-path=src/locale
+# hand src/locale/messages.xlf to translators, get messages.fr.xlf back
+ng build --localize
+```
 
----
-
-### 3. ngx-translate
-
-Website: [https://github.com/ngx-translate/core](https://github.com/ngx-translate/core)
+The locales are declared in `angular.json`, next to the file that holds their translations:
 
-**Overview**  
-**ngx-translate** is one of the most established third-party i18n libraries in the Angular ecosystem. It enables translation at runtime, letting you load language files on demand and switch locales dynamically without rebuilding your entire app.
+```json fileName="angular.json"
+{
+  "projects": {
+    "my-app": {
+      "i18n": {
+        "sourceLocale": "en-US",
+        "locales": {
+          "fr": {
+            "translation": "src/locale/messages.fr.xlf",
+            "baseHref": "/fr/"
+          },
+          "es": {
+            "translation": "src/locale/messages.es.xlf",
+            "baseHref": "/es/"
+          }
+        }
+      },
+      "architect": {
+        "build": { "options": { "localize": true } }
+      }
+    }
+  }
+}
+```
 
-**Key Features**
+Two mechanics matter more than the syntax:
 
-- **Runtime Translations**: Ideal for dynamic language switching and scenarios where you don't want multiple production builds.
-- **JSON Translation Files**: Store translations in simple JSON files, making them easy to structure and maintain.
-- **Async Loading**: Lazy-load translations to keep initial bundle sizes smaller.
-- **Multiple Language Support**: Switch locales instantly and listen for language changes across your components.
+- **It is one compilation, then N translation passes.** Since Ivy, `ng build --localize` compiles once and rewrites the emitted bundles per locale. Build time does not multiply by your locale count, but the output does: you get one full copy of the app per language.
+- **Message IDs are derived from the source text.** Change "Welcome" to "Welcome back" and the generated ID changes, so every existing translation for that message is orphaned. `@@welcomeTitle` pins the ID and avoids it, which is why you see custom IDs in every mature Angular codebase.
 
-**Considerations**
-
-- **State & Complexity**: Managing many translation files can become complex in larger applications.
-- **SEO & SSR**: If you need server-side rendering with Angular Universal, ngx-translate requires extra setup to ensure correct translations are served to crawlers and browsers on the first load.
-- **Performance**: While flexible at runtime, handling many translations on large pages can have performance implications, so caching strategies are recommended.
-
----
+## The deployment shape
 
-### 4. Transloco
+This is the part people underestimate. `--localize` gives you a folder per locale under `dist/`, and it is now your server's job to route to them.
+
+| Concern         | What you have to do                                                      |
+| :-------------- | :----------------------------------------------------------------------- |
+| Path routing    | Serve `dist/.../fr/` at `/fr/`, matching the `baseHref` you declared     |
+| Root URL        | Redirect `/` based on `Accept-Language`, or pick a default               |
+| Language switch | A full navigation to another origin path, not a client-side state change |
+| Dev server      | `ng serve --configuration=fr` serves one locale at a time                |
+| CDN / cache     | One cache entry set per locale, one deploy artifact per locale           |
 
-Website: [https://ngneat.github.io/transloco/](https://ngneat.github.io/transloco/)
+The SEO story that falls out of this is genuinely good. Each locale is a real URL serving fully translated HTML with no hydration flash, which is exactly what crawlers want. You still have to emit the `hreflang` tags yourself; see the [hreflang guide for multilingual SEO](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/hreflang_guide_multilingual_seo.md).
 
-**Overview**  
-**Transloco** is a modern, community-driven Angular i18n library that places emphasis on scalable architecture and a smooth developer experience. It provides a plugin-based approach to integrate seamlessly with your existing Angular setup.
+## Where build-time i18n stops working
 
-**Key Features**
+- **No in-app language switcher.** Switching locale means loading a different build at a different URL. For a marketing site that is fine. For an authenticated dashboard where a user flips language in their settings, it means a full reload and losing app state.
+- **Extraction only sees static text.** Strings that come from an API, get assembled at runtime, or live in a config object are invisible to `ng extract-i18n`. You end up with a second, manual mechanism for those, which defeats the point.
+- **The XLIFF round trip is slow.** Extract, send, wait, merge, rebuild. Nothing is wrong with it, but it does not fit a team that ships several times a day.
+- **`$localize` in TypeScript is awkward.** It works, but interpolation uses the `${value}:name:` placeholder syntax, and there is no type checking of anything.
 
-- **State Management Integration**: Out-of-the-box compatibility with state management libraries like NgRx and Akita.
-- **Lazy Loading**: Split translations into separate chunks and load them only when needed.
-- **Rich Plugin Ecosystem**: Handle everything from SSR integration to automatic message extraction.
-- **Runtime or Build-Time**: Offers flexibility for different translation workflows, whether you prefer runtime switching or pre-built localization.
+If none of those bite you, `@angular/localize` is a reasonable default and you should stop reading here.
 
-**Considerations**
+## The runtime alternatives
 
-- **Learning Curve**: While well-documented, the plugin-based approach may require extra steps for advanced use cases (e.g., SSR, multi-language routes).
-- **Community Size**: Transloco has an active community but is still growing compared to Angular's built-in solution or ngx-translate.
-- **Folder Structure**: Keeping translations organized can be challenging for very large apps. Good folder structure and naming conventions are crucial.
+**ngx-translate** is the long-standing answer. You load JSON catalogs over HTTP through `TranslateHttpLoader`, and read them through the `translate` pipe, the `[translate]` directive, or `TranslateService.instant()` / `.get()` / `.stream()`. It is simple, everyone knows it, and locale switching is one service call. Its downside is age: development has been intermittent and maintenance has changed hands, and the API predates signals and standalone components.
 
-### Final Thoughts
+**Transloco** (`@jsverse/transloco`) is the modern runtime option. Same idea, better ergonomics: the `*transloco="let t"` structural directive avoids one subscription per string, scopes let you split catalogs per feature and lazy-load them with the route, and the plugin ecosystem covers SSR and message extraction.
+
+Both share the same structural cost: your keys are strings with no link back to the component that renders them. Delete a component and the keys stay in every locale file forever. That trade is the same one every catalog-based library makes, and it is covered in [per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md).
+
+|                        | `@angular/localize` | ngx-translate             | Transloco                     | Intlayer                             |
+| :--------------------- | :------------------ | :------------------------ | :---------------------------- | :----------------------------------- |
+| Messages resolved      | Build time          | Runtime                   | Runtime                       | Build time, locale picked at runtime |
+| Builds to deploy       | One per locale      | One                       | One                           | One                                  |
+| Switch locale in place | No                  | Yes                       | Yes                           | Yes                                  |
+| Message format         | ICU in templates    | `{{param}}` interpolation | Interpolation, ICU via plugin | Own node types, ICU still partial    |
+| Typed keys             | No                  | No                        | Not out of the box            | Generated, on by default             |
+| Extra build tooling    | `@angular/localize` | None                      | None                          | Custom Angular builder               |
+
+## Signals, zoneless, and standalone
+
+Modern Angular is standalone by default and moving to signals, and this changes what a good i18n integration looks like. Observable-based services still work, but you end up bridging with `toSignal()` or sprinkling `async` pipes to keep templates reactive under zoneless change detection.
+
+A signal-based content API avoids that layer. In Intlayer's Angular adapter, `useIntlayer` returns a `Signal`, so the template re-renders on a locale change with no subscription and no pipe:
+
+```ts fileName="src/app/cart-summary.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;
+```
+
+```ts fileName="src/app/cart-summary.component.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-cart-summary",
+  standalone: true,
+  template: `
+    <h2>{{ content().total }}</h2>
+    <small>{{ content().vatNotice }}</small>
+  `,
+})
+export class CartSummaryComponent {
+  content = useIntlayer("cart-summary");
+}
+```
+
+The content file sits next to the component that renders it, and a build plugin compiles those declarations into per-component dictionaries. Locale switching goes through `useLocale()`, which exposes `locale`, `availableLocales` and `setLocale`. One build serves every locale, and the compiler ships only the entries a route actually renders, which is the mechanism described in [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md).
+
+<Tabs defaultTab="code">
+  <Tab label="Code" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-angular-22-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"
+/>
 
-When choosing an i18n approach for your Angular application:
+  </Tab>
+  <Tab label="Demo" value="demo">
 
-- **Assess Project Requirements**: Consider factors like dynamic language switching, development velocity, and third-party integration needs.
-- **Check SSR & SEO**: If using Angular Universal for server-side rendering, verify that your chosen solution integrates smoothly with localized metadata and route handling.
-- **Performance & Build Strategy**: Evaluate whether you need multiple build outputs (per language) or prefer a single bundle with runtime translations.
-- **Maintainability & Scaling**: For large apps, ensure your library supports a clean file structure, typed keys (if desired), and a straightforward update process.
-- **Developer Experience**: TypeScript autocompletion, plugin ecosystems, and CLI tooling can greatly reduce friction when updating or adding new translations.
+<iframe
+  src="https://intlayer-angular-22-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-angular-22-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+**What it costs you on Angular specifically.** The setup is heavier than on Vite-based frameworks: you swap the default Angular builder for `@angular-builders/custom-esbuild` (or `custom-webpack` on older projects) and register a plugin file. That is a real intrusion into `angular.json`, and it is the first thing to weigh. The project is also younger and much smaller than ngx-translate's ecosystem, and ICU message format support is still partial, which matters if your translation vendor delivers ICU strings. Finally, Angular is not yet part of the [benchmark suite](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md), which currently covers Next.js, TanStack Start, Vue, Solid and Svelte, so there are no published Angular bundle figures to point at.
+
+If you already have an Angular codebase, both runtime libraries have compat adapters: [migrating from ngx-translate](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/ngx-translate.md) keeps `TranslateService`, the `translate` pipe and the `[translate]` directive working, and [migrating from Transloco](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/transloco.md) maps Transloco scopes onto dictionary keys so `*transloco` and `| transloco` keep resolving.
 
-All the libraries discussed can power a robust, multilingual Angular application each with its own strengths. The best choice comes down to your unique needs for **performance**, **workflow**, **developer experience**, and **business goals**.
+## Trade-offs and common mistakes
+
+- **Not pinning message IDs.** Without `@@customId`, every copy edit silently orphans translations. Add custom IDs from day one, not after the first regression.
+- **Choosing `@angular/localize` for a product with a user language setting.** It is the wrong shape. Decide this before writing 400 `i18n` attributes.
+- **Forgetting `baseHref`.** Localized builds assume they are served from their own prefix. Lazy chunks 404 in production if the server does not match.
+- **Switching locale with a button instead of a link.** Crawlers do not click. Render locale switchers as anchors pointing at the localized URL, whichever library you use.
+- **Assuming per-component content is free.** You gain scoping and generated types, you lose the ability to hand a translator one big JSON file without tooling.
+- **Skipping a CI check.** Missing translations are silent in every one of these libraries until someone loads the page. Add a check that fails the build, such as [`intlayer test`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/testing.md) or Transloco's keys manager.
+
+## Going further
+
+- [Set up i18n in an Angular 22 app with Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_angular_21.md), and the [Webpack-based Angular 19 guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_angular_19.md) for older projects
+- [Migrate from ngx-translate](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/ngx-translate.md) or [from Transloco](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/transloco.md)
+- [Keep your existing JSON catalogs with the sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md)
+- [i18n library benchmarks: bundle size and locale-switch cost](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md)
+- [Vue i18n: how it works and where it starts to hurt](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/vue.md), the same analysis for the other big framework
+- [Per-component vs centralized i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/per-component_vs_centralized_i18n.md)
+- [ICU message format, and when you actually need it](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/icu_message_format.md)

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

@@ -0,0 +1,268 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Astro i18n: routing is built in, translations are not"
+description: Astro's built-in i18n covers locale routing only. What it gives you, where it stops, and how to translate content inside React, Vue or Svelte islands.
+keywords:
+  - astro i18n
+  - Astro internationalization
+  - Astro islands
+  - astro-i18n
+  - i18next
+  - locale routing
+  - hreflang
+slugs:
+  - blog
+  - i18n-technologies
+  - frameworks
+  - astro
+author: aymericzip
+---
+
+# Astro i18n: routing is built in, translations are not
+
+Astro ships an `i18n` config that handles locale prefixes, redirects and fallbacks. It does not ship a message catalog, an interpolation syntax or plural handling: you bring those. This post covers what Astro gives you natively, where it stops, and the specific problem nobody warns you about: getting translations into an island.
+
+## Table of Contents
+
+<TOC/>
+
+## What Astro actually gives you
+
+Enable it in `astro.config.mjs`:
+
+```js fileName="astro.config.mjs"
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en", "fr", "es"],
+    routing: {
+      prefixDefaultLocale: false,
+    },
+  },
+});
+```
+
+That buys you four things:
+
+| Feature                                             | What it does                                            |
+| --------------------------------------------------- | ------------------------------------------------------- |
+| `Astro.currentLocale`                               | The locale parsed from the URL, or `defaultLocale`      |
+| `Astro.preferredLocale`                             | Best match from the `Accept-Language` header (SSR only) |
+| `getRelativeLocaleUrl` / `getRelativeLocaleUrlList` | Build links to the same page in another language        |
+| `i18n.fallback`                                     | Redirect or rewrite a missing locale to another one     |
+
+And that's the list. There is no `t()`. Astro's own documentation is explicit about this: you supply the translation layer. The usual starting point is a hand-rolled object plus a helper.
+
+```ts fileName="src/i18n/ui.ts"
+export const defaultLang = "en";
+
+export const ui = {
+  en: { "nav.home": "Home", "cart.items": "items" },
+  fr: { "nav.home": "Accueil", "cart.items": "articles" },
+} as const;
+
+export const useTranslations =
+  (lang: keyof typeof ui) => (key: keyof (typeof ui)[typeof defaultLang]) =>
+    ui[lang][key] ?? ui[defaultLang][key];
+```
+
+In a `.astro` file this is genuinely fine. The frontmatter runs at build time, the strings are inlined into static HTML, and nothing ships to the browser. Astro is a good place to do i18n badly and get away with it.
+
+## Then you add an island
+
+Here is the same helper inside a React island:
+
+```tsx fileName="src/components/Cart.tsx"
+import { useTranslations } from "../i18n/ui";
+
+export const Cart = ({ count }: { count: number }) => {
+  const t = useTranslations("en"); // the island has no idea what locale the page is
+
+  return (
+    <span>
+      {count} {t("cart.items")}
+    </span>
+  );
+};
+```
+
+On `/fr/panier` this renders "3 items". The reason is the part of Astro people skip: **an island is a separate client entry point, not a child of the page**. `Astro.currentLocale` exists in frontmatter and nowhere else. The island gets props and its own bundle, and that is all.
+
+There are three ways out and each one costs something:
+
+1. **Pass the locale as a prop.** `<Cart count={3} lang={Astro.currentLocale} client:load />`. Correct, but now `import { ui }` pulls _every_ language's strings into the island's client bundle, because a static import isn't split by locale.
+2. **Pass the resolved strings as props.** No catalog in the bundle, but you hand-plumb every string through the page, and the props aren't checked against anything. Add a string to the island, forget the page, ship English.
+3. **Detect the locale in the island at runtime.** Read `document.documentElement.lang` on mount. With `client:load` the island is also rendered on the server, where there is no DOM to read, so the prerendered markup is in the default language and swaps on hydration. That's the flash of untranslated content.
+
+Add a second island framework and it compounds: a React island and a Vue island each need their own i18n runtime, their own initialization, and their own copy of the catalog. Same strings, two sources of truth.
+
+## How the common libraries handle it
+
+**i18next / react-i18next / vue-i18n.** Mature, well documented, plurals via `Intl.PluralRules`, interpolation, an enormous plugin ecosystem. In Astro you initialize an instance in the `.astro` frontmatter _and_ an instance inside each island. Namespace loading is manual, so it is easy to over-ship: if the island imports `common.json` and `common.json` is 40 KB across all locales, that's what the browser downloads. This is the safest choice if your team already knows i18next.
+
+**`astro-i18n` (community).** Astro-native, gives you a `t()` with interpolation and variants on the page side. The island side is still yours to solve.
+
+**Paraglide.** Compiles each message into a tree-shakeable function, so `import { cart_items } from "./paraglide/messages"` works identically in `.astro` frontmatter and in a React island, and the bundler drops what you don't call. Genuinely well suited to Astro's shape. The trade-off is the one described in [Compiler vs. declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/compiler_vs_declarative_i18n.md): the message layer lives in generated code rather than in your source.
+
+**Astro native + hand-rolled.** Zero dependencies, and for a five-page marketing site with no islands it's the right answer. It stops scaling the moment you need plurals in Polish or a translator who isn't you.
+
+## How Intlayer handles it
+
+Intlayer declares content per component in a `.content.ts` file and compiles it at build time. Astro is one of the few frameworks where that maps cleanly onto the runtime model: an island is already a component boundary, so the dictionary boundary and the bundle boundary are the same line.
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer react-intlayer @astrojs/react
+```
+
+```typescript fileName="astro.config.ts"
+import { intlayer } from "astro-intlayer";
+import react from "@astrojs/react";
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  integrations: [intlayer(), react()],
+});
+```
+
+Declare the content once, next to the component that uses it:
+
+```tsx fileName="src/components/cart.content.tsx"
+import { plural, t, type Dictionary } from "intlayer";
+
+const cartContent = {
+  key: "cart",
+  content: {
+    items: t({
+      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
+      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
+    }),
+  },
+} satisfies Dictionary;
+
+export default cartContent;
+```
+
+The `.astro` page reads it with `getIntlayer` and passes only the locale down:
+
+```astro fileName="src/pages/[...locale]/index.astro"
+---
+import {
+  getIntlayer,
+  getLocaleFromPath,
+  getLocalizedUrl,
+  getPrefix,
+  localeMap,
+  getHTMLTextDir,
+  type LocalesValues,
+} from "intlayer";
+import { Cart } from "../../components/Cart";
+
+export const getStaticPaths = () =>
+  localeMap(({ locale }) => ({
+    params: { locale: getPrefix(locale).localePrefix },
+  }));
+
+const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+const { title } = getIntlayer("app", locale);
+---
+
+<html lang={locale} dir={getHTMLTextDir(locale)}>
+  <head>
+    <title>{title}</title>
+    {
+      localeMap(({ locale: mapLocale }) => (
+        <link
+          rel="alternate"
+          hreflang={mapLocale}
+          href={new URL(
+            getLocalizedUrl(Astro.url.pathname, mapLocale),
+            Astro.site
+          )}
+        />
+      ))
+    }
+  </head>
+  <body>
+    <h1>{title}</h1>
+    <Cart count={3} locale={locale} client:only="react" />
+  </body>
+</html>
+```
+
+And the island resolves its own content from the locale it was handed:
+
+```tsx fileName="src/components/Cart.tsx"
+/** @jsxImportSource react */
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+import type { LocalesValues } from "intlayer";
+
+const CartContent = ({ count }: { count: number }) => {
+  const { items } = useIntlayer("cart");
+
+  return <span>{items(count)}</span>;
+};
+
+export const Cart = ({
+  count,
+  locale,
+}: {
+  count: number;
+  locale: LocalesValues;
+}) => (
+  <IntlayerProvider locale={locale}>
+    <CartContent count={count} />
+  </IntlayerProvider>
+);
+```
+
+Two things follow from this. The island receives the page's locale as a prop, so it hydrates in the right language instead of flashing the default one. And the same `cart` dictionary is readable from `astro-intlayer` on the page and from `vue-intlayer` or `svelte-intlayer` in another island, so you do not run one i18n library per island runtime.
+
+<Tabs defaultTab="code">
+  <Tab label="Code" value="code">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-astro-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-astro-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-astro-template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+</Tabs>
+
+## Trade-offs and common mistakes
+
+**Don't run two routing layers.** If you set Astro's `i18n.locales` _and_ Intlayer's `routing.mode`, you get two components deciding what `/fr/about` means, and prefix redirects can bounce. Pick one owner for the URL shape.
+
+**`client:only` islands are invisible to crawlers.** The Intlayer Astro guides use `client:only="react"`, which means that island renders nothing at build time. Keep anything you want indexed (headings, body copy, links) in `.astro` frontmatter, and reserve islands for interactive UI.
+
+**hreflang has to be built from the unlocalized path.** Generating alternates from `Astro.url.pathname` on `/fr/about` will produce `/es/fr/about` unless you strip the prefix first. `getLocalizedUrl` handles this; a hand-rolled version usually doesn't. See the [hreflang guide](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/hreflang_guide_multilingual_seo.md).
+
+**Intlayer's honest downsides.** It needs a build step: dictionaries are generated into `.intlayer/`, which you add to `tsconfig.json` `include` and to `.gitignore`. Its ecosystem is much smaller than i18next.s, with fewer StackOverflow answers and fewer third-party plugins, and the project is younger. If you already have JSON catalogs and a working i18next setup, migrating buys you bundle size and typing, not correctness. Check the [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/index.md) before deciding that trade is worth it.
+
+**Migration doesn't have to be a rewrite.** The [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md) expose the same public API as your current library and delegate to Intlayer underneath, so `useTranslation()` calls keep working while the content layer moves.
+
+## Going further
+
+- [Translate your Astro website with Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_astro.md): routing, sitemap, robots.txt and locale switcher for `.astro` pages
+- [Astro + React islands setup](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_astro_react.md), and the equivalents for [Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_astro_vue.md) and [Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_astro_svelte.md)
+- [Configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md): `routing.mode`, domains, locale storage
+- [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)
+- [Bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/bundle_optimization.md): what actually reaches the browser
+- [What is internationalization (i18n)?](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/what_is_internationalization.md) and [the meaning of i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18n_meaning.md)
+- Same series, other runtimes: [React i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/react.md), [Vue i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/vue.md), [Svelte i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/list_i18n_technologies/frameworks/svelte.md)