Aller au contenu
Tutorials21 mai 2026· Mis à jour 17 novembre 2026· 10 min de lecture

Internationaliser un site Astro avec i18next et Locize

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: true pour des URLs uniformes.
  • Utilisez des routes de pages dynamiques [lang]/ avec getStaticPaths, pour que chaque locale soit pré-rendue statiquement.
  • Synchronisez les traductions dans l'app au moment du build via la commande download de locize-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 un t() pour sa langue avec getFixedT. 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 syncLocales ou l'app web Locize, selon ce qui correspond à votre workflow. Aucun saveMissing à 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 utilisez i18next-locize-backend + le package locize à 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-cli télécharge le dernier JSON publié depuis le CDN Locize dans src/i18n/locales/{lng}/{ns}.json. src/i18n/index.ts charge 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 downloadLocales et 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-app

La 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.json

Installer les dépendances

npm install astro i18next
npm install --save-dev locize-cli

Aucun 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.currentLocale disponible dans chaque page/composant gratuitement.
  • La détection de la langue du navigateur via Astro.preferredLocale et Astro.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 sur api.locize.app, basé sur CloudFront, payant, prend en charge les téléchargements privés + un contrôle de cache personnalisé. Faites correspondre --cdn-type sur 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.glob récupère chaque fichier que locize-cli télécharge, donc un nouveau namespace ou une nouvelle langue venant de Locize ne demande aucun changement de code (seulement la langue dans locales de astro.config.mjs et un libellé dans languages).
  • Les namespaces comme fichiers. getT(lang, 'index') renvoie un t() 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 / _other plus count pour 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 :

  1. npm run syncLocales (câblé dans package.json, retirez le flag --dry=true pour réellement pousser). locize-cli lit vos src/i18n/locales/{lng}/{ns}.json locaux et envoie toutes les clés pas encore présentes dans Locize. Manuel ou déclenché en CI, sans write-key dans le navigateur.
  2. Extraction statique via i18next-cli : il trouve d'emblée les appels t('…') dans les fichiers .js, .ts, .jsx et .tsx et écrit les nouvelles clés dans le JSON local ; synchronisez ensuite comme ci-dessus. Les fichiers .astro nécessitent un plugin via ses hooks de plugin ; sans plugin, i18next-cli ne les lit pas.
  3. L'app web Locize : ajoutez des clés directement dans l'éditeur et récupérez-les avec downloadLocales avant 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 locize a 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 downloadLocales et 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=true du package locize a 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

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

Articles similaires