Maintenir alignée la documentation bilingue
Les guides utilisateur publics sont appariés par chemin relatif :
docs/en/<chemin-relatif>
docs/ja/<chemin-relatif>
L'anglais est publié à / ; le japonais est publié à /ja/. Le japonais reste
la source pratique de rédaction pour les nouvelles explications produit, mais une
modification dans l'une ou l'autre langue ne doit pas laisser silencieusement sa
contrepartie avec un comportement, des commandes, des limites de propriété, des
avertissements ou une navigation différents.
Périmètre
Appliquez ce workflow à index.md et guide/**/*.md sous les deux racines linguistiques.
docs/en/reference/ est volontairement uniquement en anglais. Les documents
internes d'architecture, de décision, de dépôt, de contributeur et de test
anticipé en dehors des deux racines linguistiques ne sont pas des paires de
traduction.
Workflow
- Inspectez le changement demandé et le diff Git actuel. Identifiez chaque page publique concernée et sa contrepartie de même chemin relatif.
- Lisez les deux pages complètes. Lorsque du contenu japonais est créé, modifié ou révisé pour sa lisibilité, lisez également la référence de style japonais. Lorsque la modification change le comportement produit, les commandes, les chemins ou la propriété, vérifiez la source actuelle ou la Décision acceptée au lieu de traduire une hypothèse.
- Préservez le sens, l'architecture de l'information, les exemples, les avertissements et les destinations des liens, mais rédigez une documentation naturelle pour chaque public plutôt que de traduire phrase par phrase. Modifiez les deux contreparties lorsque le sens ou la structure de l'information change. Pour une simple amélioration rédactionnelle en japonais, inspectez la contrepartie anglaise mais ne fabriquez pas de modification anglaise si son sens et sa structure sont déjà en accord.
- Si une contrepartie n'existe pas, créez-la. Si une page est intentionnellement spécifique à une langue, confirmez qu'elle est en dehors du périmètre apparié ou obtenez une décision explicite de la différer ; signalez le report et son emplacement de suivi. Ne considérez pas le changement bilingue comme complet tant que la dérive n'est pas simplement mentionnée.
- Pour un déplacement ou une suppression, appliquez le même changement de chemin
relatif aux deux arborescences et mettez à jour
mkdocs.yml, les liens entrants, les conseils aux contributeurs, et toute URL publique intégrée dans le code ou les tests.
Vérification
Exécutez depuis la racine du dépôt :
python -m mkdocs build --strict
git diff --check
Confirmez que les pages générées en anglais et en japonais existent aux chemins
correspondants et que leurs sélecteurs de langue pointent l'un vers l'autre.
Lorsqu'une URL publique est un contrat CLI, mettez également à jour sa source,
ses tests ciblés et la Décision acceptée, puis exécutez le test ciblé et
python scripts/check_decisions.py.
Signalez les paires de pages inspectées et modifiées, toute contrepartie intentionnellement laissée inchangée après comparaison sémantique, toute autre exception et les résultats de vérification.