Traducción automática
Esta página fue traducida automáticamente por IA y puede contener errores. Si algo no está claro, consulte la fuente en inglés.
Internacionalización¶
La documentación trata el inglés y el chino simplificado como fuentes canónicas revisadas.
Cada otra configuración regional habilitada es un derivado generado. El registro de idiomas, el enrutamiento de fuentes, la configuración del modelo y los límites de la API residen en
i18n/config.toml.
1. Cobertura de idiomas y enrutamiento de fuentes¶
El registro habilita intencionalmente un conjunto enfocado de 12 configuraciones regionales del sitio. Cubre los seis idiomas oficiales de las Naciones Unidas: árabe, chino, inglés, francés, ruso y español. Además, cubre japonés, coreano y chino tradicional para Asia Oriental, más alemán, italiano y portugués para Europa. El inglés y el chino simplificado son canónicos, por lo que 10 configuraciones regionales se traducen automáticamente.
El japonés, el coreano y el chino tradicional utilizan el chino simplificado como fuente. Todas las demás configuraciones regionales generadas utilizan el inglés. La selección de la fuente es explícita por configuración regional; el traductor nunca adivina a partir de un nombre de configuración regional o de los caracteres del documento.
Agregar una configuración regional requiere entradas coincidentes en i18n/config.toml y la lista de idiomas de MkDocs
i18n. La auditoría de documentación rechaza registros inconsistentes.
2. Contrato de documento canónico¶
Cada página de MkDocs tiene un archivo en inglés y un archivo .zh-CN.md. Una solicitud de extracción,
un push a main, o una ejecución de calidad enviada manualmente que cambie una versión canónica
debe incluir su contraparte en el rango de confirmaciones verificado. El flujo de trabajo de calidad verifica:
- pares canónicos y acoplamiento de pares modificados;
- paridad de nivel de encabezado y bloque de código;
- enlaces locales y referencias de origen;
- inventarios de fixtures y pruebas;
- una compilación estricta de cada configuración regional configurada.
El texto canónico puede escribirse manualmente o con asistencia de IA, pero debe confirmarse y revisarse como fuente ordinaria. La API de traducción nunca se llama desde un flujo de trabajo de solicitud de extracción.
3. Numeración de encabezados y estabilidad de fragmentos¶
El código fuente Markdown almacena texto de encabezado descriptivo sin números de esquema.
Durante cada compilación de MkDocs, scripts/mkdocs_heading_numbers.py agrega números locales de página
a los encabezados H2–H6. Las páginas de la Guía del usuario usan letras minúsculas en H2
(a., b.) y descendientes de letra más decimal (a.1, a.1.1); otras páginas
conservan esquemas de página decimales. Por separado, la navegación izquierda de la Guía del usuario usa
números decimales jerárquicos como 1.1. Los títulos de página H1 y las secciones de navegación de nivel superior
permanecen sin numerar. Los números generados son metadatos de presentación:
mover una sección cambia su número visible sin cambiar su identificador de fragmento.
El hook de compilación hace que cada identificador de encabezado sea explícito antes de agregar el
número visible. i18n/legacy-heading-anchors.json conserva alias para fragmentos
que se publicaron antes de que se eliminaran los números de esquema almacenados. No edite
ese mapa de compatibilidad generado a la ligera y no agregue números de esquema manuales
de vuelta al Markdown canónico o generado; la auditoría de documentación
los rechaza.
4. Contrato de documento generado¶
Las páginas generadas usan el modo de sufijo de MkDocs, como index.fr.md o
guide/configuration.ja.md. Cada página contiene metadatos frontales deterministas que registran:
- la configuración regional y ruta de origen canónico;
- el resumen SHA-256 de origen;
- el modelo resuelto y la versión del prompt;
- que la página es una traducción automática.
i18n/manifest.json además registra resúmenes de salida y huellas digitales de entrada de traducción.
Una página se vuelve obsoleta cuando cambian su origen, glosario, prompt, modelo o
salida generada. El traductor solo solicita unidades obsoletas a menos que
se solicite explícitamente una reconstrucción completa.
Los encabezados traducidos mantienen sus slugs localizados naturales y reciben alias ocultos para los slugs de origen canónico. Debido a que los destinos de enlaces Markdown están protegidos de los cambios de modelo, estos alias mantienen los enlaces de fragmentos dentro de la página y entre páginas válidos en cada configuración regional. Los alias se pueden actualizar sin conexión sin otra llamada a la API de traducción.
Los archivos generados no deben editarse manualmente. El flujo de trabajo de traducción de la rama principal
los regenera y marca cada configuración regional completada como una confirmación
en una rama solo de generación derivada del SHA exacto validado por calidad. Una
ejecución posterior puede verificar y reutilizar esa rama, por lo que una interrupción solo descarta
la configuración regional que aún está en progreso. main permanece sin cambios hasta que el flujo de trabajo haya
ejecutado la auditoría de idioma generado requerida, el conjunto de pruebas completo y la compilación
estricta de todas las configuraciones regionales. Luego verifica que main no haya avanzado, promueve el
punto de control validado mediante un push de avance rápido e implementa ese mismo artefacto de sitio validado.
5. Markdown protegido y contrato de prompt¶
Antes de una solicitud de API, el traductor reemplaza los metadatos frontales, el código delimitado, el código en línea, los destinos de enlaces, las etiquetas HTML y las URL desnudas con marcadores de posición inmutables. Una respuesta se rechaza si falta algún marcador de posición, está duplicado, inventado o movido fuera del contrato de salida recuperable.
El prompt también requiere niveles de encabezado idénticos e idiomas de bloque de código. La implementación verifica de forma independiente esas propiedades después de restaurar el contenido protegido. La salida de traducción debe ser un objeto JSON; el texto alrededor del JSON, el contenido vacío, las razones de finalización anormales o los esquemas incompatibles son fallos.
Los prompts de Markdown y catálogo de navegación tienen versiones bajo
i18n/prompts/. i18n/glossary.json lleva terminología estable de producto y comando.
6. Configuración del modelo y credenciales¶
El modelo predeterminado está configurado como deepseek-v4-flash. La implementación no
se ramifica en ese nombre. Un cambio de modelo futuro solo requiere actualizar
i18n/config.toml, pasar --model o establecer la
variable de flujo de trabajo DEEPSEEK_TRANSLATION_MODEL. El modelo resuelto se registra
en cada página generada y entrada de manifiesto.
GitHub Actions lee la credencial de API solo del secreto del repositorio llamado
DEEKSEEK_API_KEY. Se inyecta solo en el paso de generación cuando el
plan sin conexión informa unidades pendientes respaldadas por API. Nunca está disponible para
código de solicitud de extracción no confiable o pasos de planificación, limpieza y validación sin API.
Los valores de autenticación nunca se escriben en registros, archivos generados, artefactos
o el manifiesto.
7. Aviso de página y preferencia de idioma¶
Las páginas generadas automáticamente reciben una advertencia localizada en el momento de la representación. La advertencia identifica la página como una traducción de IA, enlaza a la fuente autorizada en inglés o chino simplificado y enlaza a un problema de traducción prellenado. No forma parte del Markdown traducido y no crea una entrada en la tabla de contenido.
En la primera visita a la página raíz de un visitante, el sitio compara navigator.languages
con las alternativas de idioma configuradas. Se selecciona una configuración regional compatible
cuando está disponible. Una selección de idioma manual se guarda localmente y tiene
prioridad en visitas posteriores.
8. Comandos del mantenedor¶
Muestra el número de unidades de traducción pendientes sin realizar llamadas de red:
uv run python scripts/translate_docs.py --plan
Verifica que cada página generada y catálogo estén actualizados:
uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required
Actualiza los alias de encabezado de origen estables sin llamadas a la API:
uv run python scripts/translate_docs.py --refresh-heading-anchors
Fuerza una regeneración completa con un modelo explícito:
DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
--force --model deepseek-v4-flash