Cycle de vie du catalogue de localisation

ZeroClaw possède deux branches de localisation avec des formats et consommateurs différents. Les catalogues Mozilla Fluent fournissent les chaînes d’application pour le runtime et zerocode. Les catalogues gettext traduisent la documentation mdBook une fois que les sources anglaises et les références générées ont été assemblées.

Les branches partagent un registre de paramètres régionaux et une philosophie de remplissage adossée à un fournisseur, mais elles ne sont pas interchangeables. Le fait qu’un fichier traduit soit suivi dans le dépôt ne prouve pas non plus qu’un binaire particulier l’intègre ou le charge. Utilisez cette page pour suivre chaque catalogue, depuis la source anglaise jusqu’à la publication, en passant par la génération, la validation et la consommation à l’exécution ou par le site.

Deux branches de localisation

locales.toml est le registre partagé des codes de langue et des libellés d’affichage. Il pilote la génération des versions localisées de la documentation ainsi que le sélecteur de langue généré, et il est intégré par le runtime pour la découverte des langues. Il ne rend pas à lui seul chaque catalogue disponible pour chaque consommateur ; chaque chargeur définit toujours la manière dont ses fichiers sont intégrés ou localisés sur le disque.

Chaînes d’application Fluent

Les fichiers Fluent en anglais sont des sources rédigées. Les clés identifient les messages, tandis que les valeurs contiennent le texte anglais et les éventuelles variables Fluent. Les noms de produits, les littéraux de commande, les identifiants et les espaces réservés restent littéraux lorsque le contrat de message l’exige.

cargo fluent parcourt les racines du catalogue d’exécution et zerocode. fill compare chaque fichier anglais avec la locale sélectionnée, traduit les clés manquantes via le fournisseur de modèle configuré, écrit la progression après chaque lot, et modifie les fichiers .ftl suivis. check analyse la syntaxe du catalogue, scan compare les références source avec les catalogues, et stats rapporte la couverture sans modifier les catalogues. Les différences Fluent relèvent d’un changement de localisation délibéré plutôt que d’un travail applicatif accessoire.

Le stockage et le chargement sont des préoccupations distinctes :

• Les chaînes CLI d’exécution contiennent toujours de l’anglais intégré. Le chargeur peut également utiliser des catalogues CLI traduits intégrés par builtin_cli_ftl_source, puis applique un catalogue sur disque comme source locale de priorité la plus élevée.
• Les descriptions d’outils affichées à l’exécution dans les prompts intègrent toujours l’anglais et superposent les valeurs traduites de tools.ftl chargées depuis le disque ; les recherches facultatives manquantes ne renvoient aucune valeur.
• zeroclaw-tools intègre l’anglais de façon autonome et charge le fichier tools.ftl du disque pour les chaînes de schéma et de résultat appartenant aux outils, car sa crate ne peut pas dépendre du runtime ; les recherches manquantes requises affichent un marqueur {key} visible.
• zerocode intègre son catalogue anglais et superpose un fichier zerocode.ftl traduit depuis le disque. ZEROCODE_LOCALE_DIR est une surcharge de test explicite ; l’emplacement partagé habituel est <config-dir>/data/ftl/<locale>/zerocode.ftl.
• zeroclaw locales fetch télécharge les catalogues d’exécution et zerocode sélectionnés dans ce répertoire de locales partagé sur le disque en utilisant les chemins de catalogue déclarés par zeroclaw-config.

Pour le runtime, les outils et zerocode, l’anglais reste la table de base. Un catalogue traduit sur disque ou intégré remplace les clés qu’il contient ; les clés absentes du catalogue traduit conservent leur valeur anglaise. Les recherches obligatoires signalent l’absence d’une clé dans toutes les sources disponibles et affichent un marqueur visible {key} plutôt que d’inventer silencieusement du texte ; les recherches facultatives de descriptions d’outils du runtime ne renvoient aucune valeur.

chaînes de documentation gettext

Le Markdown anglais est la source de documentation rédigée, mais l’extraction voit également les références générées, les fragments inclus et la sortie du préprocesseur matérialisée pour la compilation d’extraction. Avant d’exécuter mdBook avec la sortie xgettext, cargo mdbook sync appelle le chemin partagé prepare_generated_book_inputs() utilisé par les compilations par locale et le service mono-locale. Ce chemin régénère les références CLI et de configuration, le sélecteur de locale, le thème, le mappage de touches, le matériel, la matrice de fonctionnalités et les entrées de plugin à partir de leurs sources canoniques. L’extraction s’exécute également avec le préprocesseur peer-groups compilé, de sorte qu’un dépôt propre ne dépend pas des fichiers ignorés ni des binaires laissés par une compilation de documentation antérieure.

cargo mdbook sync extrait les messages anglais dans messages.pot, normalise le modèle, initialise ou fusionne chaque locale sans correspondance approximative, supprime les entrées obsolètes et signale le delta non traduit. Lorsqu’un fournisseur de modèle est spécifié, il complète les traductions manquantes via tools/fill-translations ; sinon, aucun appel au fournisseur n’est effectué. Le guide du mainteneur documente les options de la commande et la procédure opérationnelle.

L’outil de remplissage traite chaque entrée gettext comme une correspondance unique entre source et traduction. Il répare ou efface les réponses du modèle qui contiennent une fuite de prompt ou un nouveau chemin absolu local à la machine, préserve les sauts de ligne finaux requis, écrit de manière incrémentielle et supprime les indicateurs fuzzy des entrées acceptées. cargo mdbook check analyse séparément chaque fichier PO et rejette les réponses générées suspectes, les littéraux protégés corrompus et les chemins locaux introduits.

Traduction partielle et repli

Le préprocesseur gettext affiche le msgid anglais lorsqu’une locale ne dispose d’aucune valeur traduite utilisable pour cette entrée. Une locale peut donc afficher une navigation et des paragraphes traduits aux côtés de prose anglaise récemment ajoutée. Cet état mixte signifie que la source anglaise a évolué au-delà de la couverture acceptée par le catalogue ; cela ne signifie pas que mdBook a sélectionné deux langues pour une même page.

Les causes courantes sont :

• Veuillez fournir la chaîne msgid à traduire.
• la synchronisation du catalogue a fusionné la nouvelle source mais aucun remplissage de traduction n’a été exécuté ;
• une réparation de sécurité a effacé une réponse du modèle divulguée, contenant un chemin ou autrement inutilisable ;
• une modification de la source a remplacé un ancien message par un nouveau ;
• un catalogue de paramètres régionaux ou un épinglage de version retarde intentionnellement le master actuel.

Fuzzy est un état de maintenance du catalogue, et non une garantie que l’ancienne valeur peut être affichée en toute sécurité. La commande sync actuelle désactive la correspondance approximative pour les nouvelles fusions, tandis que l’outil fill peut accepter une valeur fuzzy non vide existante et en supprimer le marqueur. Vérifiez le msgstr résultant ; ne déduisez pas le comportement de publication à partir du seul marqueur.

Les builds de locales traduites désactivent la recherche plein texte. Seule la locale principale, le premier élément dans locales.toml, reçoit l’index de recherche. Il s’agit d’un choix de taille dans build_locales, et non d’un manque de couverture de traduction.

Stockage du catalogue et épinglages de version

Les catalogues Fluent se trouvent dans le dépôt principal. Une modification de traduction Fluent normale met à jour directement les fichiers .ftl concernés et est examinée avec le code de l’application qui consomme leurs clés ou dans le cadre d’une passe de traduction ciblée.

Les catalogues PO de documentation résident dans zeroclaw-labs/zeroclaw-docs-translations, monté à docs/book/po en tant que sous-module git. Le dépôt principal enregistre un seul commit gitlink, et non chaque fichier PO individuellement. messages.pot et les journaux d’échecs de traduction sont des artefacts générés et ne font pas partie de l’ensemble de catalogues épinglés.

Le script d’aide à la publication scripts/release/refresh-translations.sh gère le tag de traduction et la mise à jour du gitlink du dépôt principal. Par défaut, il exécute la synchronisation et la vérification du catalogue, valide et pousse les modifications du catalogue dans le sous-module, crée et bascule sur le tag v<version> correspondant, et indexe le gitlink. Son mode --no-translate ignore à la fois la synchronisation et la vérification du catalogue, il ne convient donc qu’après avoir validé séparément les catalogues actuels. Le workflow de verrouillage des traductions initialise le commit épinglé exact, vérifie la syntaxe PO et confirme que les catalogues de langue exposent le même ensemble de msgid.

Le déploiement de la documentation initialise le sous-module épinglé et génère chaque locale déjà présente. Il n’appelle pas de fournisseur de modèle, ne comble pas les traductions manquantes, n’avance pas le sous-module et ne crée pas de balise de version.

Limites de validation et de révision

• Les PR de documentation ordinaires en anglais peuvent différer une large mise à jour des fichiers PO vers une passe ciblée du cache de traduction. Examinez la source anglaise et la limite générée dans la PR d’origine.
• Inclure les modifications PO lorsque la traduction ou la maintenance du catalogue est l’objectif, qu’une locale est ajoutée, que le delta généré est petit et révisable, ou qu’une passe de release avance le pin.
• Incluez les modifications Fluent lorsque les clés ou les chaînes traduites de l’application changent. N’affirmez pas qu’un chemin d’exécution traduit fonctionne simplement parce que son fichier .ftl existe ; vérifiez le chargeur concerné ou le chemin de récupération/installation.
• Conservez intactes la syntaxe protégée des commandes, les clés de configuration, les noms de produits, les littéraux JSON/TOML et les espaces réservés. Traduisez la prose environnante plutôt que d’affaiblir les exemples destinés aux machines.
• Considérez un repli en anglais comme une preuve visible d’une couverture de catalogue acceptée manquante. Corrigez ou complétez la source du catalogue, et non le HTML généré.
• Examinez les modifications des sous-modules comme des opérations de publication/catalogue : inspectez à la fois le gitlink du dépôt principal et le commit du catalogue qu’il sélectionne.

Pour les commandes détaillées, la configuration des fournisseurs, le traitement par lots, l’ajout d’une locale et la procédure de publication, voir Docs & Translations. Pour la source anglaise et les étapes de référence générée qui alimentent l’extraction gettext, voir Generated documentation pipeline.

Pointeurs source

• Registre des paramètres régionaux : locales.toml
• Chargeur Fluent d’exécution : crates/zeroclaw-runtime/src/i18n.rs
• Chargeur Fluent géré par l’outil : crates/zeroclaw-tools/src/i18n.rs
• Catalogues Fluent d’exécution : crates/zeroclaw-runtime/locales/
• zerocode Chargeur Fluent : apps/zerocode/src/i18n.rs
• zerocode Catalogues Fluent : apps/zerocode/locales/
• Outillage Fluent : xtask/src/cmd/fluent/
• Table de correspondance des téléchargements de catalogues : zeroclaw_config::schema::FTL_CATALOGS
• extraction et fusion gettext : xtask/src/cmd/mdbook/sync.rs
• Vérifications de sécurité gettext : xtask/src/cmd/mdbook/check.rs
• gettext remplissage et réparation : tools/fill-translations/
• Comportement de génération et de recherche des locales : xtask/src/cmd/mdbook/build.rs
• Validation du pin de traduction : .github/workflows/validate-translations-pin.yml
• Actualisation du catalogue de versions : scripts/release/refresh-translations.sh
• Déploiement de la documentation : .github/workflows/docs-deploy.yml