Traduction automatique
Cette page a été traduite automatiquement par IA et peut contenir des erreurs. En cas de doute, référez-vous à la source anglaise.
Internationalisation¶
La documentation traite l'anglais et le chinois simplifié comme des sources canoniques révisées. Toute autre langue activée est un dérivé généré. Le registre des langues, le routage des sources, la configuration du modèle et les limites de l'API se trouvent dans i18n/config.toml.
1. Couverture linguistique et routage des sources¶
Le registre active intentionnellement un ensemble ciblé de 12 langues du site. Il couvre les six langues officielles des Nations Unies : arabe, chinois, anglais, français, russe et espagnol. Il couvre en outre le japonais, le coréen et le chinois traditionnel pour l'Asie de l'Est, ainsi que l'allemand, l'italien et le portugais pour l'Europe. L'anglais et le chinois simplifié sont canoniques, donc 10 langues sont traduites automatiquement.
Le japonais, le coréen et le chinois traditionnel utilisent le chinois simplifié comme source. Toutes les autres langues générées utilisent l'anglais. La sélection de la source est explicite par langue ; le traducteur ne devine jamais à partir d'un nom de langue ou des caractères du document.
L'ajout d'une langue nécessite des entrées correspondantes dans i18n/config.toml et la liste des langues MkDocs i18n. L'audit de la documentation rejette les registres incohérents.
2. Contrat de document canonique¶
Chaque page MkDocs a un fichier anglais et un fichier .zh-CN.md. Une pull request, une poussée vers main, ou une exécution de qualité déclenchée manuellement qui modifie une version canonique doit inclure sa contrepartie dans la plage de commits vérifiée. Le workflow de qualité vérifie :
- les paires canoniques et le couplage des paires modifiées ;
- la parité des niveaux de titres et des blocs de code ;
- les liens locaux et les références sources ;
- les inventaires de fixtures et de tests ;
- une construction stricte de chaque langue configurée.
Le texte canonique peut être rédigé manuellement ou avec l'aide de l'IA, mais il doit être validé et révisé comme une source ordinaire. L'API de traduction n'est jamais appelée depuis un workflow de pull request.
3. Numérotation des titres et stabilité des fragments¶
Le Markdown source stocke le texte descriptif des titres sans numéros de plan. Lors de chaque construction MkDocs, scripts/mkdocs_heading_numbers.py ajoute des numéros locaux à la page pour les titres H2–H6. Les pages du Guide d'utilisation utilisent des lettres minuscules pour les H2 (a., b.) et des descendants lettre-plus-décimale (a.1, a.1.1) ; les autres pages conservent les plans de page décimaux. Par ailleurs, la navigation gauche du Guide d'utilisation utilise des numéros décimaux hiérarchiques tels que 1.1. Les titres de page H1 et les sections de navigation de niveau supérieur restent non numérotés. Les numéros générés sont des métadonnées de présentation : déplacer une section modifie son numéro visible sans changer son identifiant de fragment.
Le hook de construction rend chaque identifiant de titre explicite avant d'ajouter le numéro visible. i18n/legacy-heading-anchors.json conserve les alias pour les fragments qui ont été publiés avant que les numéros de plan stockés ne soient supprimés. Ne modifiez pas cette carte de compatibilité générée à la légère et n'ajoutez pas de numéros de plan manuels dans le Markdown canonique ou généré ; l'audit de la documentation les rejette.
4. Contrat de document généré¶
Les pages générées utilisent le mode suffixe MkDocs, comme index.fr.md ou guide/configuration.ja.md. Chaque page contient des métadonnées frontales déterministes enregistrant :
- la langue source canonique et le chemin ;
- le condensé SHA-256 de la source ;
- le modèle résolu et la version de l'invite ;
- que la page est une traduction automatique.
i18n/manifest.json enregistre en outre les condensés de sortie et les empreintes d'entrée de traduction. Une page devient obsolète lorsque sa source, son glossaire, son invite, son modèle ou sa sortie générée changent. Le traducteur ne demande que les unités obsolètes, sauf si une reconstruction complète est explicitement demandée.
Les titres traduits conservent leurs slugs localisés naturels et reçoivent des alias cachés pour les slugs sources canoniques. Étant donné que les destinations des liens Markdown sont autrement protégées des modifications du modèle, ces alias maintiennent la validité des liens de fragments intra-page et inter-pages dans chaque langue. Les alias peuvent être actualisés hors ligne sans autre appel API de traduction.
Les fichiers générés ne doivent pas être modifiés manuellement. Le workflow de traduction de la branche principale les régénère et valide chaque langue terminée comme un commit sur une branche dédiée aux fichiers générés, dérivée du SHA exact validé par la qualité. Une exécution ultérieure peut vérifier et réutiliser cette branche, donc une interruption ne perd que la langue encore en cours. main reste inchangé jusqu'à ce que le workflow ait exécuté l'audit de langue générée requis, la suite de tests complète et la construction stricte de toutes les langues. Il vérifie ensuite que main n'a pas avancé, promeut le point de contrôle validé par une poussée fast-forward, et déploie ce même artefact de site validé.
5. Markdown protégé et contrat d'invite¶
Avant une requête API, le traducteur remplace les métadonnées frontales, le code dans les blocs, le code en ligne, les destinations de liens, les balises HTML et les URL nues par des espaces réservés immuables. Une réponse est rejetée si un espace réservé est manquant, dupliqué, inventé ou déplacé en dehors du contrat de sortie récupérable.
L'invite exige également des niveaux de titres et des langages de blocs de code identiques. L'implémentation vérifie indépendamment ces propriétés après avoir restauré le contenu protégé. La sortie de traduction doit être un objet JSON ; le texte autour du JSON, le contenu vide, les raisons d'achèvement anormales ou les schémas incompatibles sont des échecs.
Les invites Markdown et de catalogue de navigation sont versionnées sous i18n/prompts/. i18n/glossary.json contient une terminologie stable des produits et des commandes.
6. Configuration du modèle et identifiants¶
Le modèle par défaut est configuré comme deepseek-v4-flash. L'implémentation ne bifurque pas sur ce nom. Un changement futur de modèle nécessite uniquement la mise à jour de i18n/config.toml, le passage de --model, ou la définition de la variable de workflow DEEPSEEK_TRANSLATION_MODEL. Le modèle résolu est enregistré dans chaque page générée et entrée de manifeste.
GitHub Actions lit l'identifiant API uniquement à partir du secret de dépôt nommé DEEKSEEK_API_KEY. Il est injecté uniquement dans l'étape de génération lorsque le plan hors ligne signale des unités en attente basées sur l'API. Il n'est jamais disponible pour le code de pull request non fiable ou les étapes de planification, nettoyage et validation sans API. Les valeurs d'authentification ne sont jamais écrites dans les journaux, les fichiers générés, les artefacts ou le manifeste.
7. Avis de page et préférence linguistique¶
Les pages générées automatiquement reçoivent un avertissement localisé au moment du rendu. L'avertissement identifie la page comme une traduction IA, lie vers la source faisant autorité en anglais ou chinois simplifié, et lie vers un problème de traduction pré-rempli. Il ne fait pas partie du Markdown traduit et ne crée pas d'entrée de table des matières.
Lors de la première visite d'une page racine par un visiteur, le site compare navigator.languages avec les alternatives linguistiques configurées. Une langue compatible est sélectionnée lorsqu'elle est disponible. Une sélection manuelle de langue est enregistrée localement et prévaut lors des visites ultérieures.
8. Commandes du mainteneur¶
Afficher le nombre d'unités de traduction en attente sans effectuer d'appels réseau :
uv run python scripts/translate_docs.py --plan
Vérifier que chaque page générée et catalogue est à jour :
uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required
Actualiser les alias de titres sources stables sans appels API :
uv run python scripts/translate_docs.py --refresh-heading-anchors
Forcer une régénération complète avec un modèle explicite :
DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
--force --model deepseek-v4-flash
Le workflow automatisé utilise le secret du dépôt au lieu de placer une clé sur la ligne de commande.