Internacionalizacion¶

CodexSpec soporta multiples idiomas a traves de traduccion dinamica LLM y proporciona documentacion multi-idioma para GitHub Pages.

Traduccion de Plantillas de Comandos¶

Como Funciona¶

Plantillas en Ingles Unicas: Todas las plantillas de comandos permanecen en ingles
Configuracion de Idioma: El proyecto especifica el idioma de salida preferido
Traduccion Dinamica: Claude traduce contenido en tiempo de ejecucion

Establecer Idioma¶

Durante la Inicializacion¶

# Salida en espanol
codexspec init my-project --lang es

# Salida en japones
codexspec init my-project --lang ja

Despues de la Inicializacion¶

# Ver configuracion actual
codexspec config

# Cambiar idioma
codexspec config --set-lang es

# Listar idiomas soportados
codexspec config --list-langs

Archivo de Configuracion¶

.codexspec/config.yml:

version: "1.0"

language:
  output: "es"  # Idioma de salida
  templates: "en"  # Mantener como "en"

project:
  ai: "claude"
  created: "2025-02-15"

i18n de Documentacion en GitHub Pages¶

El sitio de documentacion de CodexSpec soporta 8 idiomas usando MkDocs con el plugin mkdocs-i18n.

Idiomas Soportados¶

Codigo	Idioma
`en`	Ingles (predeterminado)
`zh`	中文简体
`ja`	日本語
`ko`	한국어
`es`	Espanol
`fr`	Francais
`de`	Deutsch
`pt-BR`	Portugues (Brasil)

Estructura de Directorios¶

docs/
+-- en/                 # Ingles (fuente)
|   +-- index.md
|   +-- user-guide/
|   +-- ...
+-- zh/                 # Traduccion al chino
+-- ja/                 # Traduccion al japones
+-- ko/                 # Traduccion al coreano
+-- es/                 # Traduccion al espanol
+-- fr/                 # Traduccion al frances
+-- de/                 # Traduccion al aleman
+-- pt-BR/              # Traduccion al portugues (Brasil)

Traducir Documentacion (Solo para Mantenedores)¶

Nota: Los comandos /codexspec:translate-docs y /codexspec:check-i18n-semantics son herramientas exclusivas para mantenedores de CodexSpec. Estan 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 estan disponibles como comandos slash para usuarios finales.

Si estas trabajando en CodexSpec, estos comandos viven en .claude/commands/codexspec/ y se invocan igual que cualquier otro comando slash. Los usuarios finales que necesiten traducir la documentacion de su propio proyecto deben usar Claude directamente con el flujo de trabajo que prefieran.

Los mantenedores de CodexSpec pueden usar el comando /codexspec:translate-docs para traducir la documentacion:

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

# Traducir archivo especifico al japones
/codexspec:translate-docs user-guide/installation.md --lang ja

# Traduccion incremental (solo archivos cambiados)
/codexspec:translate-docs --lang ko --incremental

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

Glosario de Traduccion¶

El glosario en docs/i18n/glossary.yml asegura terminologia consistente:

version: "1.0"

# Terminos a mantener en ingles
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# Traducciones para terminos comunes
translations:
  es:
    specification: "especificacion"
    constitution: "constitucion"
    task: "tarea"

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

Verificaciones de Calidad¶

Verificacion de Estructura¶

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

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

Verificacion de Completitud¶

Detecta contenido en ingles no traducido en las traducciones:

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

Verificacion Semantica (Solo para Mantenedores)¶

El analisis de consistencia semantica impulsado por AI esta disponible solo para los mantenedores de CodexSpec a traves del comando interno (ver la nota "Solo para Mantenedores" anterior):

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

Integracion CI/CD¶

El flujo de trabajo .github/workflows/docs-i18n.yml automatiza:

Deteccion de Cambios: Se activa cuando docs/en/ cambia
Traduccion Paralela: Estrategia matricial para los 7 idiomas objetivo
Verificaciones de Calidad: Validacion de estructura y completitud
Bloqueo de Despliegue: Previene despliegue si las verificaciones fallan

Disparador Manual del Flujo de Trabajo¶

# Via UI o CLI de GitHub
gh workflow run docs-i18n.yml -f languages="es,ja" -f dry_run="false"

Beneficios¶

Cero Mantenimiento de Traduccion: No es necesario mantener multiples versiones de plantillas
Siempre Actualizado: Las actualizaciones de plantillas benefician a todos los idiomas
Consciente del Contexto: Los terminos tecnicos permanecen en ingles cuando es apropiado
Calidad Automatizada: CI asegura consistencia de traduccion
Asistido por AI: Claude proporciona traducciones conscientes del contexto