Mantener la documentación bilingüe alineada
Las guías de usuario públicas se emparejan por ruta relativa:
docs/es/<ruta-relativa>
docs/ja/<ruta-relativa>
El inglés se publica en /; el japonés en /ja/. El japonés sigue siendo la fuente práctica de autoría para nuevas explicaciones de productos, pero una edición en cualquiera de los idiomas no debe dejar silenciosamente a su contraparte con comportamiento, comandos, límites de propiedad, advertencias o navegación diferentes.
Alcance
Aplica este flujo de trabajo a index.md y guide/**/*.md debajo de ambas raíces de idioma. docs/en/reference/ es intencionalmente solo en inglés. Los documentos de arquitectura interna, Decisiones, repositorio, colaboradores y pruebas prospectivas fuera de las dos raíces de idioma no son pares de traducción.
Flujo de trabajo
- Inspecciona el cambio solicitado y el diff actual de Git. Identifica cada página afectada y su contraparte con la misma ruta relativa.
- Lee ambas páginas completas. Cuando se crea, edita o revisa contenido en japonés para legibilidad, también lee la referencia de estilo japonés. Cuando la edición cambie el comportamiento del producto, comandos, rutas o propiedad, verifica la fuente actual o la Decisión aceptada en lugar de traducir una suposición.
- Conserva el significado, la arquitectura de la información, los ejemplos, las advertencias y los destinos de los enlaces, pero escribe documentación natural para cada audiencia en lugar de traducir oración por oración. Edita ambas contrapartes cuando el significado o la estructura de la información cambien. Para una mejora de redacción solo en japonés, inspecciona la contraparte en inglés pero no inventes una edición en inglés si su significado y estructura ya coinciden.
- Si una contraparte no existe, créeala. Si una página es intencionalmente específica de un idioma, confirma que está fuera del alcance emparejado u obtén una decisión explícita para posponerla; reporta el aplazamiento y su ubicación de seguimiento. No des por completo el cambio bilingüe mientras la deriva no esté simplemente mencionada.
- Para un movimiento o eliminación, aplica el mismo cambio de ruta relativa a ambos árboles y actualiza
mkdocs.yml, los enlaces entrantes, la guía para colaboradores y cualquier URL pública incrustada en código o pruebas.
Verificación
Ejecuta desde la raíz del repositorio:
python -m mkdocs build --strict
git diff --check
Confirma que las páginas generadas en inglés y japonés existan en rutas correspondientes y que sus enlaces de selección de idioma se apunten entre sí. Cuando una URL pública es un contrato de CLI, también actualiza su fuente, pruebas enfocadas y la Decisión aceptada, luego ejecuta la prueba enfocada y python scripts/check_decisions.py.
Reporta los pares de páginas inspeccionados y cambiados, cualquier contraparte intencionalmente dejada sin cambios después de la comparación semántica, cualquier otra excepción y los resultados de la verificación.