Internacionalización¶

CodexSpec soporta múltiples idiomas mediante traducción dinámica con LLM y ofrece documentación multilingüe para GitHub Pages.

Traducción de plantillas de comandos¶

Cómo funciona¶

Plantillas únicas en inglés: todas las plantillas de comandos se mantienen en inglés
Configuración de idioma: el proyecto especifica el idioma de salida preferido
Traducción dinámica: Claude traduce el contenido en tiempo de ejecución

Dimensiones de idioma¶

CodexSpec divide el idioma en cuatro dimensiones configurables de forma independiente. output es la base; las demás la sobrescriben y, si no están establecidas, caen a ella (y luego a en).

Dimensión	Clave en `config.yml`	En init	Después	Controla	Cae a
Output (base)	`output`	`--lang`	`config --set-lang`	base de las otras tres	`en`
Interaction	`interaction`	`--interaction-lang`	`config --set-interaction-lang`	diálogo LLM + salida del CLI	output → `en`
Document	`document`	`--document-lang`	`config --set-document-lang`	spec/plan/tasks generados	output → `en`
Commit	`commit`	`--commit-lang`	`config --set-commit-lang`	mensajes de commit de git	output → `en`
Templates	`templates`	—	—	origen de las plantillas de comandos (siempre `en`)	—

Establecer el idioma¶

Durante la inicialización¶

# Salida en chino (establece la base de output)
codexspec init my-project --lang zh-CN

# Totalmente no interactivo: base zh-CN, mensajes de commit en inglés
codexspec init my-project --lang zh-CN --commit-lang en

# Establecer cada dimensión explícitamente (scriptable, sin prompts)
codexspec init my-project \
  --interaction-lang zh-CN --document-lang en --commit-lang en

La primera inicialización en una TTY sin --lang (y sin las tres flags de dimensión) solicita un idioma base; en un entorno sin TTY (CI/scripts) el valor predeterminado es en. Volver a ejecutar init preserva cualquier clave de idioma que no hayas especificado.

Después de la inicialización¶

# Ver la configuración actual
codexspec config

# Cambiar una única dimensión
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

# Conmutar workflow.auto_next (la flag a secas conmuta; o pasa on/off explícitamente)
codexspec config --auto-next

# Listar los idiomas soportados
codexspec config --list-langs

Archivo de configuración¶

.codexspec/config.yml:

version: "1.0"

language:
  output: "zh-CN"        # Idioma base; las tres siguientes caen a él, luego a "en"
  interaction: "zh-CN"   # Diálogo LLM + salida del CLI codexspec (opcional → por defecto output)
  document: "en"         # requirements/spec/plan/tasks generados (opcional → por defecto output)
  commit: "en"           # Mensajes de commit de git (opcional → por defecto output)
  templates: "en"        # Mantener como "en"

project:
  ai: "claude"          # claude | codex | both — para qué asistente de IA se destina este proyecto
  created: "2025-02-15"

i18n de la documentación en GitHub Pages¶

Idiomas del sitio de documentación frente a idiomas de la CLI/tu tiempo de ejecución: no los confundas.

Sitio de documentación (esta sección): 8 idiomas. El sitio de GitHub Pages construido por MkDocs publica exactamente los ocho locales enumerados a continuación (en, zh, ja, ko, es, fr, de, pt-BR). Es un conjunto fijo, regido por la disposición de directorios docs/{lang}/ y por el plugin mkdocs-i18n.

CLI / tiempo de ejecución (la sección anterior): 13 idiomas. Las dimensiones language.* que configuras en .codexspec/config.yml aceptan 13 códigos soportados (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, ru, it, ar, hi), traducidos al vuelo por el LLM. Consulta la tabla "Idiomas soportados" en el README del proyecto para la lista canónica.

Ambos conjuntos se solapan, pero no son idénticos: el sitio de documentación no tiene los locales zh-TW/ru/it/ar/hi, y la CLI no usa los códigos zh/de/... sin prefijo que MkDocs emplea como nombres de carpeta.

El sitio de documentación de CodexSpec soporta 8 idiomas mediante MkDocs con el plugin mkdocs-i18n.

Idiomas soportados¶

Código	Idioma
`en`	Inglés (predeterminado)
`zh`	中文简体
`ja`	日本語
`ko`	한국어
`es`	Español
`fr`	Français
`de`	Deutsch
`pt-BR`	Português (Brasil)

Estructura de directorios¶

docs/
├── en/                 # Inglés (fuente)
│   ├── index.md
│   ├── user-guide/
│   └── ...
├── zh/                 # Traducción al chino
├── ja/                 # Traducción al japonés
├── ko/                 # Traducción al coreano
├── es/                 # Traducción al español
├── fr/                 # Traducción al francés
├── de/                 # Traducción al alemán
└── pt-BR/              # Traducción al portugués (Brasil)

Traducir la documentación (solo para mantenedores)¶

Nota: Los comandos /codexspec:translate-docs y /codexspec:check-i18n-semantics son herramientas exclusivas para mantenedores de CodexSpec. Están fuertemente acoplados al layout i18n de MkDocs de este repositorio (docs/{lang}/) y al glosario interno en docs/i18n/glossary.yml. No se distribuyen a proyectos de usuario mediante codexspec init y no están disponibles como slash commands para el usuario final.

Si trabajas en el propio CodexSpec, estos comandos viven en .claude/commands/codexspec/ y se invocan igual que cualquier otro slash command. Los usuarios finales que traduzcan la documentación de su propio proyecto deben usar Claude directamente, con el flujo de trabajo que prefieran.

Para los mantenedores de CodexSpec, usa el comando /codexspec:translate-docs para traducir la documentación:

# Traducir al chino
/codexspec:translate-docs --lang zh

# Traducir un archivo específico al japonés
/codexspec:translate-docs user-guide/installation.md --lang ja

# Traducción incremental (solo archivos modificados)
/codexspec:translate-docs --lang ko --incremental

# Modo vista previa (sin cambios en archivos)
/codexspec:translate-docs --lang es --dry-run

Glosario de traducción¶

El glosario en docs/i18n/glossary.yml (solo del repo) garantiza terminología consistente al traducir la documentación del propio CodexSpec:

version: "1.0"

# Términos a mantener en inglés
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# Traducciones de términos comunes
translations:
  zh:
    specification: "规格说明"
    constitution: "宪法"
    task: "任务"

# Reglas inteligentes para casos especiales
rules:
  - pattern: '\b(CLI|API)\b'
    action: keep

Metodología de traducción¶

Las traducciones pretenden leerse de forma natural en tu idioma, no como reflejos palabra a palabra del inglés:

El sentido, primero. Cada pasaje se traduce a partir de lo que comunica y luego se reexpresa con la redacción y la estructura oracional propias del idioma destino.
Los términos en inglés se mantienen cuando son más claros. Los términos técnicos sin un equivalente nativo adecuado —o más reconocibles en inglés— se conservan en inglés en lugar de traducirse de forma forzada. Por ejemplo, "AI coding agent" se convierte en una frase nativa natural como "AI 编程助手", no en una traducción literal y rígida.
Fluidez nativa. El objetivo es una prosa que se lea como si hubiera sido escrita originalmente en tu idioma.

Verificaciones de calidad¶

Verificación de estructura¶

Comprueba que todos los directorios de idioma tengan la misma estructura de archivos:

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

Verificación de completitud¶

Detecta contenido en inglés no traducido dentro de las traducciones:

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

Verificación semántica (solo para mantenedores)¶

Análisis de consistencia semántica potenciado por IA, disponible para los mantenedores de CodexSpec mediante el comando interno (véase la nota de "solo para mantenedores" más arriba):

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

Integración CI/CD¶

El flujo de trabajo .github/workflows/docs-i18n.yml es únicamente una puerta de compilación (build gate): en cada cambio de docs/** / mkdocs.yml (push a main y pull requests) ejecuta mkdocs build --strict en todas las versiones de idioma para detectar errores de compilación, enlaces rotos y contenido mal formado. No traduce nada.

Las traducciones se producen y se confirman manualmente mediante /codexspec:translate-docs (véase más arriba), con la fuente en inglés y todas las traducciones en un único commit revisado y atómico. La traducción automática en CI se eliminó de forma intencional: el job anterior nunca llegaba a ejecutarse realmente (un if mal formado lo saltaba), requería una clave API permanente y habría confirmado traducciones sin revisar directamente a main.

Beneficios¶

Cero mantenimiento de traducción: no es necesario mantener múltiples versiones de plantillas
Siempre actualizado: las actualizaciones de plantillas benefician a todos los idiomas
Consciente del contexto: los términos técnicos permanecen en inglés cuando procede
Calidad automatizada: la CI garantiza la consistencia de la traducción
Asistido por IA: Claude aporta traducciones conscientes del contexto