Sur cette page
Astro est le framework web static-first pour les sites orientés contenu : routage basé sur les fichiers, zéro JavaScript par défaut, des « islands » pour l'interactivité opt-in, un mode SSR à la demande pour les parties qui en ont besoin. Depuis la v4.0 (fin 2023, stable en v5+, actuelle en v7.x), Astro embarque le routage i18n intégré : préfixage d'URL (/en/, /de/), le helper Astro.currentLocale, la détection de la langue du navigateur et des helpers d'URL comme getRelativeLocaleUrl.
Ce que l'i18n intégré d'Astro ne fournit pas, c'est une fonction de traduction (t()), la pluralisation ou l'interpolation de messages. La recette i18n officielle d'Astro montre un pattern « construisez-le vous-même » : importez un fichier JSON par locale et écrivez un petit helper de lookup. Cela couvre les chaînes simples, et s'arrête là où commencent les pluriels, l'interpolation et les fallbacks. i18next comble ce manque, au build : il s'exécute pendant qu'Astro rend les pages, donc un build statique n'envoie toujours aucun JavaScript au navigateur. Locize gère les traductions : locize-cli télécharge le dernier JSON publié dans src/i18n/locales/{lng}/{ns}.json avant le build, et i18next lit ces fichiers.
Cet article décrit l'intégration de bout en bout. Le code complet vit sur github.com/locize/locize-astro-example.
Mise à jour (17 novembre 2026) : la première version de cet article utilisait un helper
t()écrit à la main. L'article utilise désormais i18next, qui ajoute les pluriels, l'interpolation au format JSON i18next que Locize utilise par défaut, et les fallbacks, toujours sans JavaScript dans le navigateur. L'exemple est passé à Astro 7.
Si vous êtes sur Nuxt à la place, suivez le walkthrough Nuxt 4. Si vous êtes sur React Router v7 (mode Framework), voir le walkthrough React Router v7 : tous deux couvrent des intégrations plus riches (éditeur in-context, saveMissing à l'exécution) qui ne s'insèrent pas directement dans le modèle static-by-default d'Astro.
TL;DR
- Configurez le routage i18n intégré d'Astro dans
astro.config.mjs: liste des locales +prefixDefaultLocale: truepour des URLs uniformes. - Utilisez des routes de pages dynamiques
[lang]/avecgetStaticPaths, pour que chaque locale soit pré-rendue statiquement. - Synchronisez les traductions dans l'app au moment du build via la commande
downloaddelocize-cli. Pas de saut CDN à l'exécution, pas de considération SSR. - Dans
src/i18n/index.ts, chargez une seule fois les fichiers téléchargés dans i18next ; chaque page obtient unt()pour sa langue avecgetFixedT. Dans un build statique, i18next ne tourne qu'au build, donc aucun JavaScript n'est envoyé au navigateur. - Écrivez les tags
<link rel="alternate" hreflang>dans votre layout : le routage d'Astro ne les ajoute pas. - Posez de nouvelles clés via
npm run syncLocalesou l'app web Locize, selon ce qui correspond à votre workflow. AucunsaveMissingà l'exécution n'est possible depuis la couche statique. - Besoin de saveMissing à l'exécution, de fetch CDN live ou de l'éditeur in-context ? Montez n'importe quelle island React/Vue/Svelte via
@astrojs/<framework>et utilisezi18next-locize-backend+ le packagelocizeà l'intérieur de l'island. - Exemple complet fonctionnel : github.com/locize/locize-astro-example
Comment les pièces s'emboîtent
Astro est static-by-default. Les pages sont pré-rendues en HTML au moment du build et servies comme fichiers statiques (ou, en mode SSR, via un adaptateur à la demande). L'i18n intégré d'Astro est propriétaire de la couche routage (préfixage d'URL, redirections sensibles à la locale, helpers de détection navigateur), mais reste délibérément en dehors de la couche traduction des messages. C'est pourquoi chaque tuto i18n Astro se termine par « maintenant écrivez votre propre helper t() ». i18next est cette couche, prête à l'emploi.
Locize est la couche de gestion des traductions. L'intégration est bundle-only à l'exécution :
- Au build :
locize-clitélécharge le dernier JSON publié depuis le CDN Locize danssrc/i18n/locales/{lng}/{ns}.json.src/i18n/index.tscharge dans i18next chaque fichier qui s'y trouve. t(), c'est i18next, appelé pendant qu'Astro rend chaque page : pluriels, interpolation, fallback vers la langue par défaut, un namespace par fichier. Dans un build statique, rien de tout cela n'atteint le navigateur : la sortie est du HTML pur.- Les mises à jour nécessitent un rebuild, comme tout autre changement de contenu Astro. Lancez
npm run downloadLocaleset redéployez.
Ce dernier point est le compromis. Un aller-retour « traduction publiée dans Locize → utilisateurs finaux la voient » signifie relancer le build. Si vous préférez un fetch CDN live (publication → la vue de page suivante le récupère, sans redéploiement), vous montez une framework island et utilisez i18next-locize-backend à l'intérieur. Le walkthrough React Router v7 couvre cette forme, et vous pouvez adopter le même pattern par-island dans Astro. Nous y reviendrons à la fin.
C'est parti
Prérequis
Node.js 22.23.4+ (Astro 7 l'exige), npm/pnpm/yarn, et une familiarité de base avec Astro. L'exemple ci-dessous cible Astro 7.4 et i18next 27.
Layout du projet
Générez une nouvelle app Astro, ou faites git clone de l'exemple :
npm create astro@latest my-app
cd my-appLa forme de l'arborescence pertinente après câblage de i18n + Locize :
my-app/
├── astro.config.mjs # Astro's built-in i18n config
├── package.json # locize-cli download/sync scripts
└── src/
├── pages/
│ ├── index.astro # root /, redirects to /en/
│ └── [lang]/
│ ├── index.astro # home, renders for each locale via getStaticPaths
│ └── second.astro # secondary page, same pattern
├── layouts/
│ └── Layout.astro # shared <html>/<head>/<body>
├── components/
│ └── LanguagePicker.astro # swaps the /{lang}/ prefix
└── i18n/
├── index.ts # loads the JSON into i18next; getT + pathForLang
└── locales/ # locize-cli download target (one JSON per ns)
├── en/
│ ├── common.json
│ ├── index.json
│ └── second.json
└── de/
├── common.json
├── index.json
└── second.jsonInstaller les dépendances
npm install astro i18next
npm install --save-dev locize-cliAucun package d'intégration Astro n'est nécessaire : i18next tel quel fonctionne dans les fichiers .astro. C'est la seule dépendance runtime, et dans un build statique elle ne tourne que pendant le build du site.
Configurer l'i18n intégré d'Astro dans astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
site: 'https://example.com', // your domain: the hreflang links need absolute URLs
i18n: {
defaultLocale: 'en',
locales: ['en', 'de'],
routing: {
prefixDefaultLocale: true // /en/, /de/ # uniform URLs
}
}
})Astro prend désormais en charge :
- Le routage des URLs pour chaque page sous
src/pages/[lang]/:/en/,/de/,/en/second,/de/second, etc. Astro.currentLocaledisponible dans chaque page/composant gratuitement.- La détection de la langue du navigateur via
Astro.preferredLocaleetAstro.preferredLocaleList(routes SSR/à la demande uniquement).
Avec prefixDefaultLocale: true, chaque locale reçoit un préfixe d'URL : uniforme, SEO-clean et facile à gérer avec des routes dynamiques [lang]/ + getStaticPaths. (Si vous préférez voir la locale par défaut servie à / sans préfixe, mettez-le à false et utilisez des pages basées sur les fichiers au lieu de [lang]/. L'exemple utilise la forme préfixée parce qu'elle passe mieux à l'échelle.)
Télécharger les traductions depuis Locize au build
Ajoutez à package.json :
{
"scripts": {
"downloadLocales": "locize download --project-id=<your-id> --ver=latest --cdn-type=standard --clean=true --path=./src/i18n/locales",
"syncLocales": "locize sync --project-id=<your-id> --ver=latest --cdn-type=standard --api-key=<your-write-key> --path=./src/i18n/locales --dry=true"
}
}Exécutez npm run downloadLocales avant npm run build (manuellement, en CI ou comme hook prebuild), pour que le JSON empaqueté soit toujours frais.
Standard vs Pro CDN. Locize propose deux infrastructures CDN (comparaison complète dans Types de CDN : Standard vs Pro) : Standard sur
api.lite.locize.app, basé sur BunnyCDN, gratuit pour des volumes mensuels de téléchargement généreux, public uniquement (par défaut pour les nouveaux projets) ; Pro surapi.locize.app, basé sur CloudFront, payant, prend en charge les téléchargements privés + un contrôle de cache personnalisé. Faites correspondre--cdn-typesur le flag de la cli avec ce sur quoi est votre projet.
i18next dans src/i18n/index.ts
Locize émet un JSON par namespace par langue, ce qui correspond exactement à la façon dont i18next organise ses ressources. Un seul module charge chaque fichier téléchargé et initialise i18next une fois :
import i18next, { type Namespace } from 'i18next'
// Every file locize-cli downloads: ./locales/{lng}/{ns}.json
const files = import.meta.glob<{ default: Record<string, string> }>('./locales/*/*.json', { eager: true })
const resources: Record<string, Record<string, Record<string, string>>> = {}
for (const [path, mod] of Object.entries(files)) {
const [, lng, ns] = path.match(/\.\/locales\/([^/]+)\/([^/]+)\.json$/)!
resources[lng] ??= {}
resources[lng][ns] = mod.default
}
export const languages = { en: 'English', de: 'Deutsch' } as const
export type Lang = keyof typeof languages
export const defaultLang: Lang = 'en'
// An instance of its own, apart from any island that uses i18next in the browser.
const i18n = i18next.createInstance()
i18n.init({
resources, // bundled, so init finishes right away
fallbackLng: defaultLang,
defaultNS: 'common',
interpolation: { escapeValue: false } // Astro escapes what {t(...)} renders
})
// A t() bound to one language (and optionally one namespace).
export const getT = <N extends Namespace>(lang: Lang, ns?: N) => i18n.getFixedT(lang, ns)
// The same page in another language: swap the /{lang}/ prefix.
// "/en/second/" → "/de/second/"
export function pathForLang (pathname: string, target: Lang): string {
const parts = pathname.split('/')
parts[1] = target
return parts.join('/')
}Ce que cela vous apporte :
- Aucune liste d'imports à maintenir.
import.meta.globrécupère chaque fichier quelocize-clitélécharge, donc un nouveau namespace ou une nouvelle langue venant de Locize ne demande aucun changement de code (seulement la langue danslocalesdeastro.config.mjset un libellé danslanguages). - Les namespaces comme fichiers.
getT(lang, 'index')renvoie unt()pour une langue et un namespace ; les clés d'un autre namespace prennent un préfixe :t('common:headTitle'). - Fallbacks. Une clé absente en allemand se rabat sur l'anglais (
fallbackLng). - Interpolation et pluriels dans le format que Locize stocke par défaut (i18next JSON v4) :
{{name}}pour les valeurs, les suffixes_one/_otherpluscountpour les pluriels, avec les règles de pluriel de chaque langue :
{
"title": "Hello, {{name}}!",
"loaves_one": "{{count}} loaf left",
"loaves_other": "{{count}} loaves left"
}Les clés typées fonctionnent aussi : le support TypeScript d'i18next lit les noms des clés dans votre JSON de la langue par défaut.
Utiliser t() dans les pages
Les routes dynamiques [lang]/ + getStaticPaths signifient qu'Astro pré-rend un fichier HTML par locale au moment du build :
---
// src/pages/[lang]/index.astro (excerpt)
import Layout from '../../layouts/Layout.astro'
import { getT, languages, type Lang } from '../../i18n'
import { getRelativeLocaleUrl } from 'astro:i18n'
export function getStaticPaths () {
return Object.keys(languages).map(lang => ({ params: { lang } }))
}
const { lang } = Astro.params as { lang: Lang }
const t = getT(lang, 'index')
---
<Layout lang={lang} title={t('common:headTitle')}>
<h1>{t('title', { name: 'Astro' })}</h1>
<p>{t('subtitle')}</p>
<p>{t('loaves', { count: 1 })} · {t('loaves', { count: 3 })}</p>
<p>
<a href={getRelativeLocaleUrl(lang, 'second/')}>
{t('goto.second')}
</a>
</p>
</Layout>La fonction getStaticPaths mappe chaque locale à un chemin statique ; lang arrive comme paramètre de route. Du pur travail au build : pas de runtime côté serveur, pas d'hydratation. Le build écrit /en/index.html avec « Hello, Astro! » et « 1 loaf left · 3 loaves left », et /de/index.html avec « Hallo, Astro! » et « 1 Brot übrig · 3 Brote übrig », sans aucun fichier JavaScript.
Le sélecteur de langue et les liens hreflang
La recette i18n des docs d'Astro montre un sélecteur simple qui échange le préfixe de locale sur l'URL courante ; pathForLang de src/i18n/index.ts se charge de cet échange :
---
// src/components/LanguagePicker.astro (excerpt)
import { languages, pathForLang, type Lang } from '../i18n'
interface Props {
currentLang: Lang
}
const { currentLang } = Astro.props
---
<nav>
<ul>
{Object.entries(languages).map(([lang, label]) => (
<li>
{lang === currentLang ? (
<strong>{label}</strong>
) : (
<a href={pathForLang(Astro.url.pathname, lang as Lang)}>{label}</a>
)}
</li>
))}
</ul>
</nav>Déposez-le dans src/layouts/Layout.astro et il est disponible sur chaque page. Le même layout écrit les liens hreflang, pour que les moteurs de recherche sachent quelle page est dans quelle langue ; le routage d'Astro ne les ajoute pas :
---
// src/layouts/Layout.astro (head excerpt)
import { languages, defaultLang, pathForLang, type Lang } from '../i18n'
const { lang, title } = Astro.props
---
<html lang={lang}>
<head>
<title>{title}</title>
{Object.keys(languages).map(l => (
<link rel="alternate" hreflang={l} href={new URL(pathForLang(Astro.url.pathname, l as Lang), Astro.site)} />
))}
<link rel="alternate" hreflang="x-default" href={new URL(pathForLang(Astro.url.pathname, defaultLang), Astro.site)} />
</head>Trois façons d'amener de nouvelles clés dans Locize
Astro est static-by-default : les pages sont pré-rendues, donc un push saveMissing à l'exécution depuis des utilisateurs en production n'est pas possible sans un adaptateur SSR, et Astro décourage de toute façon les écritures depuis la couche statique. Il existe trois chemins viables à la place :
npm run syncLocales(câblé danspackage.json, retirez le flag--dry=truepour réellement pousser).locize-clilit vossrc/i18n/locales/{lng}/{ns}.jsonlocaux et envoie toutes les clés pas encore présentes dans Locize. Manuel ou déclenché en CI, sans write-key dans le navigateur.- Extraction statique via
i18next-cli: il trouve d'emblée les appelst('…')dans les fichiers.js,.ts,.jsxet.tsxet écrit les nouvelles clés dans le JSON local ; synchronisez ensuite comme ci-dessus. Les fichiers.astronécessitent un plugin via ses hooks de plugin ; sans plugin, i18next-cli ne les lit pas. - L'app web Locize : ajoutez des clés directement dans l'éditeur et récupérez-les avec
downloadLocalesavant le prochain build.
Choisissez ce qui correspond à votre workflow. Aucun n'exige de livrer une write API key dans votre artefact de build.
Ce que cette forme n'inclut intentionnellement pas
Trois choses que vous pourriez attendre des walkthroughs Nuxt ou React Router v7 sont délibérément absentes ici :
- Pas de
saveMissingà l'exécution. Voir ci-dessus : les builds statiques Astro ne peuvent pas pousser, et une app Astro SSR ferait cela depuis l'intérieur d'une island, pas depuis la couche statique. - Pas d'éditeur in-context sur les pages statiques. L'éditeur
locizea besoin d'un DOM qui se re-rend quand l'éditeur met à jour une chaîne. La sortie statique d'Astro n'a pas ce hook. - Pas de fetch CDN live. Les traductions sont empaquetées au moment du build. Pour servir une traduction fraîche, lancez
npm run downloadLocaleset redéployez. Cela correspond au modèle static-first d'Astro et garde l'artefact de build autonome.
Tous ces trois points fonctionnent à l'intérieur de framework islands. Montez une island React, Vue, Svelte, Solid ou Preact via l'intégration @astrojs/<framework> correspondante, et à l'intérieur de cette island utilisez directement i18next-locize-backend + le package locize. La couche statique d'Astro gère le routage + l'habillage de la page ; les islands gèrent les parties qui ont besoin d'un runtime. Pages et islands utilisent la même bibliothèque et le même format JSON.
Quand ajouter une framework island
L'intégration static-only couvre la plupart des sites de contenu : blogs, pages marketing, docs, landing pages. Ajoutez une framework island quand vous avez besoin de :
- Mises à jour live des traductions sans redéploiement. Utilisez
i18next-locize-backendà l'intérieur de l'island pour fetcher les traductions depuis le CDN Locize à chaque visite (ou par route, si vous cachez). - Édition in-context pour les traducteurs. L'overlay
?incontext=truedu packagelocizea besoin d'un runtime qui se re-rend sur changement de chaîne : disponible uniquement à l'intérieur d'une island hydratée. saveMissingà l'exécution. Même contrainte : une island hydratée peut pousser de nouvelles clés ; le HTML statique ne le peut pas.
Le pattern ressemble à ceci (pour une island React) :
---
// src/pages/[lang]/interactive.astro
import Layout from '../../layouts/Layout.astro'
import I18nIsland from '../../components/I18nIsland.tsx'
import { languages, type Lang } from '../../i18n'
export function getStaticPaths () {
return Object.keys(languages).map(lang => ({ params: { lang } }))
}
const { lang } = Astro.params as { lang: Lang }
---
<Layout lang={lang} title="Interactive">
<I18nIsland client:load lang={lang} />
</Layout>// src/components/I18nIsland.tsx
import i18next from 'i18next'
import Backend from 'i18next-locize-backend'
import { initReactI18next, useTranslation } from 'react-i18next'
i18next
.use(Backend)
.use(initReactI18next)
.init({
fallbackLng: 'en',
saveMissing: import.meta.env.DEV,
backend: {
projectId: import.meta.env.PUBLIC_LOCIZE_PROJECT_ID,
apiKey: import.meta.env.DEV ? import.meta.env.PUBLIC_LOCIZE_API_KEY : undefined, // dev only; the browser sees only PUBLIC_ variables
version: 'latest'
}
})
export default function I18nIsland ({ lang }: { lang: string }) {
const { t, i18n } = useTranslation()
if (i18n.language !== lang) i18n.changeLanguage(lang)
return <h2>{t('island.heading')}</h2>
}client:load indique à Astro d'hydrater ce composant immédiatement au chargement de la page ; vous pouvez utiliser client:visible pour différer l'hydratation jusqu'à ce que l'island entre dans le viewport. La configuration exacte de i18next-locize-backend est documentée dans le walkthrough React Router v7 : le même câblage de backend fonctionne dans n'importe quel contexte React/Vue/Svelte/Solid, y compris à l'intérieur d'une island Astro.
🎉 Félicitations
Une configuration Astro 7 + i18next + Locize fonctionnelle vous offre :
- i18n static-first sans flash de contenu non traduit ni JavaScript de traduction dans le navigateur (tout est pré-rendu par locale)
- Préfixage d'URL SEO-clean via le routage i18n intégré d'Astro, avec des liens hreflang depuis le layout
- Un
t()complet fourni par i18next : pluriels, interpolation, fallbacks, namespaces - Synchronisation des traductions au build via
locize-cli, compatible serverless, sans saut CDN par requête - Une porte de sortie vers des islands dynamiques, avec la même bibliothèque et les mêmes fichiers, quand vous avez besoin de mises à jour à l'exécution ou d'édition in-context
🧑💻 Le code complet : github.com/locize/locize-astro-example.
Les fondateurs de Locize sont aussi les créateurs d'i18next. En utilisant Locize, vous soutenez directement l'avenir d'i18next.
Voir aussi
- Comment internationaliser une app Nuxt 4 avec @nuxtjs/i18n et Locize : pendant côté Vue avec une intégration plus riche (vue-i18n, éditeur in-context, saveMissing à l'exécution)
- Comment internationaliser une app React Router v7 avec remix-i18next : pendant côté React avec fetch CDN live via
i18next-locize-backend - Le routage i18n intégré d'Astro : la primitive de routage sur laquelle ce walkthrough s'appuie
- Recette i18n Astro : le pattern construisez-le-vous-même qu'i18next remplace ici
- Documentation i18next :
t(), pluriels, interpolation, TypeScript locize-cli: l'outil de synchronisation au build
Fatigué de gérer vos traductions à la main ?
Locize est le backend de gestion de traductions créé par l'équipe i18next : diffusion CDN, traduction IA, édition in-context, sans redéploiement.
Démarrez votre essai gratuit de 14 jours
