Internationalisation

Ce site est disponible en anglais, allemand, français et espagnol. Choisissez la langue dans l’en-tête ou le menu mobile. Ardo conserve la page, les paramètres de requête et le fragment lors du changement de langue.

Routes statiques par langue

Configurez les langues dans ardo.config.ts ou le plugin Vite ardo():

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Docs",
  i18n: {
    defaultLocale: "en",
    locales: [
      { id: "en", label: "English" },
      { id: "de", label: "Deutsch" },
      { id: "fr", label: "Français" },
      { id: "es", label: "Español" },
    ],
  },
})

Placez les routes correspondantes sous app/routes/en/, app/routes/de/, app/routes/fr/ et app/routes/es/. Gardez les mêmes slugs dans toutes les langues. Ardo exige une arborescence complète et signale les pages manquantes au build. Il ne remplace pas silencieusement le contenu par une autre langue.

Le déploiement V6 utilise /v6/en/, /v6/de/, /v6/fr/ et /v6/es/. Les anciennes versions de documentation conservent leur langue et leurs URL d’origine.

Interface, recherche et métadonnées

Utilisez useArdoLocale() depuis ardo/runtime pour la langue active, y compris pendant le rendu serveur. Passez des libellés traduits à <ArdoRoot labels={...}> pour la navigation, la recherche, les encadrés, les boutons de copie et les actions de page. Ardo formate les dates de mise à jour selon la langue de la route.

La recherche charge uniquement l’index de la langue active lorsque le lecteur sélectionne le champ ou saisit une requête. Le HTML généré contient le bon lang, l’URL canonique et les liens vers les autres langues. Les identifiants du code et chemins d’import restent inchangés. La référence API provient des commentaires sources en anglais et l’indique dans chaque interface traduite.

Une source MDX avec Palamedes

Cet exemple est compilé par Palamedes à partir d’un seul fichier MDX anglais. Ses paragraphes et ses espaces réservés de texte enrichi viennent des catalogues ; le composant React reste intact :

Bienvenue dans Ardo. Ce paragraphe est traduit avec Palamedes à partir d’une seule source MDX.

Le compilateur natif de Palamedes extrait les messages de chaque guide anglais dans docs/app/content/guide/. Pendant le build, le site applique les traductions PO et génère les quatre arborescences avant qu’Ardo ne prépare les métadonnées, la recherche et les exports Markdown.

Seuls la source MDX anglaise et les catalogues PO sont maintenus. Git ignore les routes générées dans docs/app/routes/<locale>/guide/. Code, imports, composants interactifs et identifiants anglais restent structurels ; les traductions portent sur le texte, les libellés et le frontmatter.

Contexte du rendu serveur

Un site peut exporter withRenderContext depuis app/server.ts pour définir un contexte autour du rendu complet d’une page. Ce module entre uniquement dans le bundle serveur. La résolution des métadonnées et les composants React suspendus s’exécutent dans le même contexte :

import type { ArdoServerRenderContext } from "ardo/runtime"
import { createServerI18nScope } from "@palamedes/runtime/server"

const scope = createServerI18nScope()

export async function withRenderContext({ path, render }: ArdoServerRenderContext) {
  const i18n = await loadI18n(path.split("/")[1] ?? "en")
  return scope.run(i18n, render)
}

Ici, loadI18n est le chargeur de catalogues du site. Utilisez une instance immuable par langue ou une nouvelle instance par requête. N’activez pas de langue mutable pour tout le processus : les rendus parallèles mélangeraient les langues. Dans le navigateur, Palamedes v2 initialise son runtime à partir des dépendances de catalogue générées. Le hook serveur du site utilise createViteCatalogDelivery() de @palamedes/vite-plugin/delivery pour insérer l’import map de la langue active et gérer les échecs de chargement des catalogues avant l’hydratation.

Maintenir les traductions

Depuis la racine du dépôt :

pnpm --filter ardo-docs i18n:extract
pnpm --filter ardo-docs i18n:check

L’extraction met à jour les messages sources et conserve les traductions. Modifiez les catalogues des guides dans docs/app/i18n/guides/ ; l’interface commune et l’exemple interactif utilisent docs/app/i18n/. L’audit vérifie traductions manquantes, syntaxe ICU et espaces réservés. Le plugin Vite régénère les routes après une modification de source ou de PO. Compilez le site et lancez les tests de changement de langue avant de soumettre vos modifications.