Internationalisation (i18n)

Cette page documente la façon dont le site de documentation d'Apothem gère plusieurs langues : la cohorte de locales qu'il déclare, le mécanisme hreflang qu'il émet, son rendu de droite à gauche, et la façon dont les pages de chaque langue sont raccordées au routage.

Résumé des décisionsCopy Anchor Link

• Plateforme : Next.js App Router + Fumadocs. Le site est construit à partir de site/. La cohorte de locales est déclarée dans site/lib/i18n.ts, et le mécanisme de liens vers les langues alternatives se trouve dans site/lib/hreflang.ts.
• Cohorte de locales : douze langues. La cohorte Modern Dev de douze locales est la source de vérité canonique ; l'anglais est la locale source et chacune des onze cibles est amorcée par traduction automatique à partir de l'ensemble des pages anglaises. La relecture humaine par locale est en cours, et fallbackLanguage: 'en' couvre toute page qu'une locale n'a pas encore rédigée.
• Routage par locale : activé sur toute la cohorte. Chaque locale est raccordée au routage et accessible sous son propre préfixe d'URL (/es/, /zh-cn/, …) ; l'anglais est servi à la racine du site.
• Mécanisme hreflang : actif. Chaque page émet un ensemble <link rel="alternate"> couvrant chaque locale, plus un repli x-default, de sorte que les moteurs de recherche voient le groupe complet des langues alternatives. Les liens sont résolus fichier par fichier à partir du système de fichiers ; une page n'est donc annoncée dans une locale que lorsque cette locale en dispose.
• Rendu de droite à gauche : actif. Les feuilles de style partagées utilisent partout des propriétés CSS logiques, de sorte que les pages arabes s'affichent correctement sous dir="rtl".
• Relecture des traductions : suivie page par page. Les pages de locale amorcées par traduction automatique sont servies et portent machineTranslated: true dans leur frontmatter jusqu'à ce qu'un humain les relise ; ce drapeau est une métadonnée de suivi de la relecture et la page ne l'affiche pas. L'anglais sert de repli pour toute page qu'une locale n'a pas. Faire relire 80 % des pages d'une locale est un objectif de relecture, et non une condition de publication.
• Fraîcheur des traductions : suivie page par page. Chaque page de locale enregistre le texte anglais à partir duquel elle a été traduite. Lorsque la page anglaise change par la suite, la page traduite affiche une note d'une ligne renvoyant à la page anglaise, qui continue de faire autorité.

La cohorte de localesCopy Anchor Link

La cohorte Modern Dev déclare douze locales. L'anglais est servi à la racine du site ; les onze cibles sont chacune amorcées par traduction automatique à partir de l'ensemble des pages anglaises, sous leur propre préfixe d'URL, et fallbackLanguage: 'en' couvre toute page pas encore rédigée.

La cohorte est l'unique source de vérité ; ses amendements passent par une décision délibérée, jamais par une modification silencieuse.

Comment fonctionne hreflangCopy Anchor Link

site/lib/hreflang.ts construit la table alternates.languages que Next.js rend dans le <head> de chaque page. Sa construction respecte une règle : le lien vers la langue alternative d'une locale n'est émis que lorsque cette locale a rédigé cette page, ce qui est résolu fichier par fichier à partir du système de fichiers (site/lib/translated-pages.ts). Une page entièrement traduite émet donc le groupe complet :

<link rel="alternate" hreflang="en" href="https://apothem.ahmedgad.com/..." />
<link rel="alternate" hreflang="es" href="https://apothem.ahmedgad.com/es/..." />
<link rel="alternate" hreflang="ar" href="https://apothem.ahmedgad.com/ar/..." dir="rtl" />
<!-- … one per cohort locale … -->
<link rel="alternate" hreflang="x-default" href="https://apothem.ahmedgad.com/..." />

Le lien canonical de la page est toujours sa propre URL — il ne pointe jamais vers une autre locale.

Rendu de droite à gaucheCopy Anchor Link

L'arabe est la locale de droite à gauche de la cohorte, et le site l'affiche correctement :

• Propriétés CSS logiques uniquement. Les feuilles de style et les composants partagés utilisent des propriétés logiques (margin-inline-start, padding-inline-end, text-align: start, inset-inline-start) plutôt que des propriétés physiques (margin-left, text-align: left). Les propriétés logiques s'inversent automatiquement sous dir="rtl", de sorte que la même feuille de style sert correctement les deux directions.
• Attribut de direction. Les pages arabes définissent dir="rtl" sur l'élément <html>, aux côtés de lang="ar".
• Contenu bidirectionnel. Les chaînes à direction mixte — par exemple une commande anglaise dans un paragraphe arabe — sont encapsulées dans <bdi> afin que la séquence de gauche à droite intégrée s'affiche correctement au sein du flux de droite à gauche.

Ajouter ou mettre à jour une localeCopy Anchor Link

La cohorte et le routage sont pilotés par site/lib/i18n.ts :

1. Rédigez la page sous content/docs/<locale>/ en reproduisant la source anglaise.
2. Enregistrez le texte anglais qu'elle traduit : depuis site/, exécutez node scripts/translation-sources.mjs --stamp <locale>/<path>.mdx, qui écrit le hash de la page anglaise dans le champ de frontmatter sourceHash de la page de locale.
3. Vérifiez que la locale figure dans ROUTED_LOCALES (les douze locales de la cohorte sont toutes routées aujourd'hui).
4. Son lien hreflang et ses routes se résolvent automatiquement à partir du système de fichiers.

Traductions obsolètesCopy Anchor Link

Le sourceHash d'une page de locale est le hash de la page anglaise à partir de laquelle elle a été traduite ; il couvre le frontmatter et la prose anglais, mais pas les tableaux générés que le générateur de référence réécrit dans toutes les langues à la fois. Lors de la compilation, le site calcule le hash de la page anglaise actuelle ; lorsque les deux diffèrent, la page traduite affiche une note indiquant que la page anglaise a changé depuis la traduction, avec un lien vers celle-ci. Exécutez node scripts/translation-sources.mjs depuis site/ pour lister les pages obsolètes par locale, puis actualisez chaque traduction et estampillez-la comme à l'étape 2 ci-dessus. Une page qu'une locale n'a pas traduite du tout est servie à partir de la source anglaise, signalée comme texte anglais.

L'anglais reste la source de vérité ; chaque page de locale reproduit à l'identique la structure, les liens et les exemples de code de son homologue anglaise.