Internationalisation¶

CodexSpec prend en charge plusieurs langues via la traduction dynamique par LLM et fournit une documentation multilingue pour GitHub Pages.

Traduction des modèles de commandes¶

Comment ça marche¶

Des modèles uniques en anglais : tous les modèles de commandes restent en anglais
Configuration de la langue : le projet spécifie la langue de sortie préférée
Traduction dynamique : Claude traduit le contenu à l'exécution

Dimensions de langue¶

CodexSpec décompose la langue en quatre dimensions configurables indépendamment. output est la base ; les autres la surchargent et se rabattent sur elle (puis sur en) si elles ne sont pas définies.

Dimension	Clé `config.yml`	À l'init	Plus tard	Contrôle	Se rabat sur
Output (base)	`output`	`--lang`	`config --set-lang`	base pour les trois autres	`en`
Interaction	`interaction`	`--interaction-lang`	`config --set-interaction-lang`	dialogue LLM + sortie CLI	output → `en`
Document	`document`	`--document-lang`	`config --set-document-lang`	spec/plan/tasks générés	output → `en`
Commit	`commit`	`--commit-lang`	`config --set-commit-lang`	messages de commit git	output → `en`
Templates	`templates`	—	—	source des modèles de commandes (toujours `en`)	—

Définir la langue¶

Pendant l'initialisation¶

# Sortie en chinois (définit la base output)
codexspec init my-project --lang zh-CN

# Entièrement non interactif : base zh-CN, messages de commit en anglais
codexspec init my-project --lang zh-CN --commit-lang en

# Définir chaque dimension explicitement (scriptable, sans invite)
codexspec init my-project \
  --interaction-lang zh-CN --document-lang en --commit-lang en

La première initialisation dans un TTY sans --lang (et sans les trois indicateurs de dimension) demande une langue de base ; dans un environnement non-TTY (CI/scripts) elle utilise en par défaut. Relancer init préserve toute clé de langue que vous n'avez pas explicitement fournie.

Après l'initialisation¶

# Voir la configuration courante
codexspec config

# Changer une seule dimension
codexspec config --set-lang zh-CN
codexspec config --set-interaction-lang zh-CN
codexspec config --set-document-lang en
codexspec config --set-commit-lang en

# Basculer workflow.auto_next (l'indicateur seul bascule ; ou passer explicitement on/off)
codexspec config --auto-next

# Lister les langues prises en charge
codexspec config --list-langs

Fichier de configuration¶

.codexspec/config.yml :

version: "1.0"

language:
  output: "zh-CN"        # Langue de base ; les trois ci-dessous se rabattent sur elle, puis "en"
  interaction: "zh-CN"   # Dialogue LLM + sortie CLI codexspec (optionnel → par défaut output)
  document: "en"         # Exigences/spec/plan/tasks générés (optionnel → par défaut output)
  commit: "en"           # Messages de commit git (optionnel → par défaut output)
  templates: "en"        # Conserver "en"

project:
  ai: "claude"          # claude | codex | both — assistant AI cible de ce projet
  created: "2025-02-15"

i18n de la documentation GitHub Pages¶

Langues du site docs vs. langues CLI/runtime — ne pas les confondre.

Site de documentation (cette section) : 8 langues. Le site GitHub Pages construit par MkDocs fournit exactement les huit locales listées ci-dessous (en, zh, ja, ko, es, fr, de, pt-BR). C'est un ensemble fixe, piloté par l'agencement docs/{lang}/ et le plugin mkdocs-i18n.

CLI / runtime (section précédente) : 13 langues. Les dimensions language.* que vous configurez dans .codexspec/config.yml acceptent 13 codes pris en charge (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, ru, it, ar, hi), traduits à la volée par le LLM. Voir le tableau « Supported Languages » dans le README du projet pour la liste canonique.

Les deux ensembles se recoupent mais ne sont pas identiques : le site docs n'a pas de locales zh-TW/ru/it/ar/hi, et le CLI n'utilise pas les codes nus zh/de/... que MkDocs utilise comme noms de dossiers.

Le site de documentation de CodexSpec prend en charge 8 langues grâce à MkDocs et au plugin mkdocs-i18n.

Langues prises en charge¶

Code	Langue
`en`	English (par défaut)
`zh`	中文简体
`ja`	日本語
`ko`	한국어
`es`	Español
`fr`	Français
`de`	Deutsch
`pt-BR`	Português (Brasil)

Structure des répertoires¶

docs/
├── en/                 # Anglais (source)
│   ├── index.md
│   ├── user-guide/
│   └── ...
├── zh/                 # Traduction chinoise
├── ja/                 # Traduction japonaise
├── ko/                 # Traduction coréenne
├── es/                 # Traduction espagnole
├── fr/                 # Traduction française
├── de/                 # Traduction allemande
└── pt-BR/              # Traduction portugaise (Brésil)

Traduire la documentation (réservé aux mainteneurs)¶

Note : les commandes /codexspec:translate-docs et /codexspec:check-i18n-semantics sont des outils réservés aux mainteneurs de CodexSpec. Elles sont étroitement couplées à la structure i18n MkDocs de ce dépôt (docs/{lang}/) et au glossaire interne docs/i18n/glossary.yml. Elles ne sont pas distribuées aux projets utilisateurs via codexspec init et ne sont pas disponibles comme slash commands pour les utilisateurs finaux.

Si vous travaillez sur CodexSpec lui-même, ces commandes se trouvent dans .claude/commands/codexspec/ et s'invoquent comme n'importe quelle autre slash command. Les utilisateurs finaux qui souhaitent traduire la documentation de leur propre projet doivent utiliser Claude directement, avec le flux de travail de leur choix.

Pour les mainteneurs de CodexSpec, utilisez la commande /codexspec:translate-docs pour traduire la documentation :

# Traduire en chinois
/codexspec:translate-docs --lang zh

# Traduire un fichier spécifique en japonais
/codexspec:translate-docs user-guide/installation.md --lang ja

# Traduction incrémentale (uniquement les fichiers modifiés)
/codexspec:translate-docs --lang ko --incremental

# Mode aperçu (aucune modification de fichier)
/codexspec:translate-docs --lang es --dry-run

Glossaire de traduction¶

Le glossaire docs/i18n/glossary.yml (interne au dépôt) garantit une terminologie cohérente lors de la traduction de la documentation de CodexSpec elle-même :

version: "1.0"

# Termes à conserver en anglais
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# Traductions pour les termes courants
translations:
  zh:
    specification: "规格说明"
    constitution: "宪法"
    task: "任务"

# Règles intelligentes pour les cas particuliers
rules:
  - pattern: '\b(CLI|API)\b'
    action: keep

Méthodologie de traduction¶

Les traductions visent à se lire naturellement dans votre langue, pas comme des transpositions mot à mot de l'anglais :

Le sens d'abord. Chaque passage est traduit pour ce qu'il communique, puis reformulé avec le vocabulaire et la syntaxe propres à la langue cible.
Les termes anglais sont conservés lorsqu'ils sont plus clairs. Les termes techniques sans bon équivalent natif — ou plus reconnaissables en anglais — restent en anglais plutôt que d'être traduits de manière maladroite. Par exemple, « AI coding agent » devient une expression native naturelle comme « AI 编程助手 », et non une traduction littérale rigide.
Fluidité native. L'objectif est une prose qui se lit comme si elle avait été écrite à l'origine dans votre langue.

Contrôles qualité¶

Contrôle de structure¶

Vérifie que tous les répertoires de langue ont la même structure de fichiers :

./scripts/bash/check-i18n-structure.sh

Contrôle de complétude¶

Détecte le contenu anglais non traduit dans les traductions :

./scripts/bash/check-i18n-completeness.sh

Contrôle sémantique (réservé aux mainteneurs)¶

Analyse de cohérence sémantique assistée par IA, disponible pour les mainteneurs de CodexSpec via la commande interne (voir la note « réservé aux mainteneurs » ci-dessus) :

/codexspec:check-i18n-semantics --lang zh

Intégration CI/CD¶

Le workflow .github/workflows/docs-i18n.yml est uniquement une porte de build : à chaque modification de docs/** / mkdocs.yml (push sur main et pull requests) il exécute mkdocs build --strict sur toutes les versions linguistiques afin de détecter les erreurs de build, les liens cassés et le contenu mal formé. Il ne traduit rien.

Les traductions sont produites et commitées manuellement via /codexspec:translate-docs (voir ci-dessus), avec la source anglaise et toutes les traductions dans un seul commit atomique revu. La traduction automatique en CI a été retirée volontairement — l'ancien job ne s'exécutait en réalité jamais (un if mal formé le sautait), il exigeait une clé API permanente et aurait commité des traductions non revues directement sur main.

Avantages¶

Zéro maintenance de traduction : pas besoin de maintenir plusieurs versions de modèles
Toujours à jour : les mises à jour de modèles profitent à toutes les langues
Sensible au contexte : les termes techniques restent en anglais quand c'est pertinent
Qualité automatisée : la CI garantit la cohérence des traductions
Assistée par IA : Claude fournit des traductions contextuelles