Internationalisation (i18n)¶

Les produits et la documentation de l'écosystème sont servis en plusieurs langues. Cette page explique la politique linguistique et sa mise en œuvre technique.

Politique linguistique¶

Niveau	Langues
Obligatoire	Монгол (`mn`) · English (`en`)
Pour les produits principaux	+ 中文 (`zh`) · Русский (`ru`)
Pour la documentation d'écosystème	Mongol + les six langues officielles de l'ONU

Le mongol est la langue source : le texte d'origine est rédigé en mongol puis traduit vers les autres langues.

Les six langues officielles des Nations unies sont : العربية (ar) · 中文 (zh) · English (en) · Français (fr) · Русский (ru) · Español (es). Ce site (documentation au niveau de l'écosystème) est servi en mongol plus ces six langues — sept au total.

Pourquoi précisément ces langues ?

Les lecteurs de la documentation d'écosystème ne sont pas seulement des développeurs internes : on y trouve des partenaires internationaux, des bailleurs, des organismes de normalisation et des intégrateurs étrangers. Les six langues de l'ONU offrent la portée mondiale la plus large et constituent un choix neutre, qui ne privilégie aucun pays.

La documentation technique approfondie d'une plateforme donnée (schémas d'endpoints, référence des SDK) sort du champ de cette politique : elle reste en MN + EN dans son propre dépôt.

L'i18n dans les produits¶

Les applications déterminent la langue de l'utilisateur dans cet ordre :

Le réglage de l'utilisateur (enregistré dans son profil),
L'Accept-Language du navigateur,
La langue par défaut (mn).

L'assistant IA répond dans la langue de l'utilisateur — celle dans laquelle la question est arrivée.

Les deux couches de dictionnaire¶

Le dictionnaire réside à deux endroits, et il importe d'en comprendre la frontière :

Dictionnaire	Où	Taille
Partagé — connexion, menu, administration, eID	`@gerege/ui-core`	846 clés × 7 langues
De plateforme — la terminologie du domaine concerné	`lib/<platform>I18n.ts`	Propre à chaque plateforme, souvent 2–4 langues

La règle : le dictionnaire partagé ne connaît que la surface partagée. Le vocabulaire IBAN/relevés du portefeuille, le catalogue d'API du portail développeur, la terminologie des processus métier de Ring — tout cela réside dans le dictionnaire propre à l'application.

La raison en est le coût : placer les 1,104 termes de Ring dans le dictionnaire partagé, c'est les faire porter par kiosk, POS et le portefeuille — et chaque langue ajoutée multiplie ce coût par sept.

Un dictionnaire de plateforme se replie sur l'anglais pour les langues non traduites : l'interface peut donc exister en sept langues alors que le texte marketing et la terminologie métier n'existent que dans quelques-unes.

Langue d'interface ≠ langue de contenu

Passer le dictionnaire de quatre langues à sept a cassé chaque endroit où figurait Record<Lang, …> : le texte marketing de la landing, les descriptions du catalogue d'API — ceux-là sont écrits par des humains et ne s'étendent pas comme l'interface. À ces endroits, l'ensemble des langues se déclare explicitement, par exemple sous la forme LANDING_LANGS.

L'i18n dans la documentation¶

Le site de documentation de chaque dépôt utilise MkDocs Material + mkdocs-static-i18n.

La structure par suffixe¶

La traduction se fait en ajoutant un code de langue au nom du fichier :

docs/
├── index.md        ← Монгол (par défaut)
├── index.ar.md     ← العربية
├── index.zh.md     ← 中文
├── index.en.md     ← English
├── index.fr.md     ← Français
├── index.ru.md     ← Русский
└── index.es.md     ← Español

Configuration :

plugins:
  - i18n:
      docs_structure: suffix
      fallback_to_default: true
      reconfigure_material: true
      reconfigure_search: true
      languages:
        - locale: mn
          default: true
          name: Монгол
          build: true
        - locale: en
          name: English
          build: true
        - locale: ar
          name: العربية
          build: true
        # … zh · fr · ru · es de même

La langue par défaut est construite à la racine du site (/), les autres sous un sous-chemin (/en/, /ar/, /zh/, /fr/, /ru/, /es/).

Repli (fallback)¶

fallback_to_default: true — une page non traduite affiche son contenu dans la langue par défaut. Ainsi, même si des traductions manquent, le site reste complet et aucun 404 n'apparaît.

C'est le choix pragmatique : la documentation s'enrichit sans cesse et la traduction suit avec retard. Attendre que toutes les pages soient traduites d'un coup reviendrait à ne pas publier la documentation du tout.

Les libellés du menu se trouvent dans mkdocs.yml et non dans le contenu des pages ; ils sont donc traduits séparément pour chaque locale :

        - locale: en
          nav_translations:
            Архитектур: Architecture
            Платформууд: Platforms
        - locale: ar
          nav_translations:
            Архитектур: البنية المعمارية
            Платформууд: المنصّات

Si vous ajoutez une page en oubliant d'ajouter son entrée nav_translations pour les six locales, ce libellé restera en mongol : la construction n'échoue pas, l'oubli ne se voit donc qu'à l'œil.

Écriture de droite à gauche (RTL)¶

العربية se lit de droite à gauche. Material reconnaît la locale ar, pose <html dir="rtl"> et inverse de lui-même le menu, les titres et le sens des tableaux — inutile d'indiquer direction séparément.

En revanche, les blocs de code et les diagrammes ASCII restent de gauche à droite, même en RTL. C'est normal : une notation technique (URL, commandes, YAML) perd son sens si l'on en inverse le sens de lecture.

Ancres des titres en cyrillique¶

Le slugify standard supprime les lettres cyrilliques

Le slugify par défaut de l'extension toc de Python-Markdown supprime les caractères non ASCII. De ce fait, le titre ## Танилт reçoit un id vide et le lien interne à la page (#танилт) cesse de fonctionner.

La solution : un slugify qui préserve l'unicode.

markdown_extensions:
  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}

Ce site est configuré de la même façon.

L'ordre de traduction¶

Pour ajouter une nouvelle documentation :

Rédigez le texte source en mongol — la source est toujours le mongol.
Stabilisez la version mongole par une construction stricte (liens et ancres sont vérifiés).
Traduisez ensuite dans les six langues d'un seul tenant. Traduire une page à moitié désynchronise les langues entre elles.

Terminez une page dans toutes les langues

Mieux vaut travailler page par page que langue par langue : convertir un même document en six langues simultanément garde la terminologie, la structure et les lignes des tableaux identiques. À l'inverse, « d'abord l'anglais pour toutes les pages » condamne les langues traduites plus tard à courir après un texte source déjà modifié.

Ce qui se traduit et ce qui ne se traduit pas¶

Traduit	Laissé tel quel
Texte courant, titres, valeurs des tableaux	Noms de domaine (`sso.gerege.mn`)
Explications, avertissements, conseils	Noms de dépôts (`template-gerege-mn`)
Libellés explicatifs dans les diagrammes	Code, YAML, commandes, chemins d'endpoints
En-têtes de tableaux	Noms de produits (eID Mongolia, G-Sign)
Texte des badges d'état	Noms de standards (OIDC, PKCE, RFC 3161)

Les noms de fichiers et l'arborescence ne sont jamais traduits : c'est platforms/sso.ru.md, pas платформы/sso.md. Ainsi le chemin de l'URL reste identique d'une langue à l'autre et les liens profonds continuent de fonctionner.

L'état de ce site¶

Toutes les pages de la documentation d'écosystème sont prêtes en sept langues :

Locale	Langue	Chemin	État
`mn`	Монгол (par défaut)	`/`	✅ complet
`ar`	العربية	`/ar/`	✅ complet
`zh`	中文	`/zh/`	✅ complet
`en`	English	`/en/`	✅ complet
`fr`	Français	`/fr/`	✅ complet
`ru`	Русский	`/ru/`	✅ complet
`es`	Español	`/es/`	✅ complet

fallback_to_default reste activé : lorsqu'une page est ajoutée et que sa traduction tarde, cette page affiche l'original mongol et le site reste complet.

Si vous repérez une erreur ou une formulation maladroite, envoyez une PR au dépôt — voir Cette plateforme documentaire.