Ciclo de vida del catálogo de localización

ZeroClaw tiene dos ramas de localización con formatos y consumidores diferentes. Los catálogos de Mozilla Fluent proporcionan las cadenas de la aplicación para el tiempo de ejecución y zerocode. Los catálogos de gettext traducen la documentación de mdBook una vez que se han ensamblado el código fuente en inglés y las referencias generadas.

Las ramas comparten un registro de configuración regional y una filosofía de relleno respaldada por el proveedor, pero no son intercambiables. El hecho de que un archivo traducido esté rastreado en el repositorio tampoco demuestra que un binario en particular lo incruste o lo cargue. Usa esta página para seguir cada catálogo desde el origen en inglés a través de la generación, la validación, el consumo en tiempo de ejecución o del sitio, y la publicación.

Dos ramas de localización

locales.toml es el registro compartido para códigos de idioma y etiquetas para mostrar. Impulsa las compilaciones de idiomas de la documentación y el selector de idiomas generado, y se incrusta en el runtime para el descubrimiento de idiomas. No hace por sí mismo que cada catálogo esté disponible para cada consumidor; cada cargador sigue definiendo cómo se incrustan o se encuentran sus archivos en el disco.

Cadenas de aplicación fluidas

Los archivos Fluent en inglés son fuentes de autoría. Las claves identifican los mensajes, mientras que los valores contienen el texto en inglés y cualquier variable de Fluent. Los nombres de productos, los literales de comandos, los identificadores y los marcadores de posición permanecen literales cuando el contrato del mensaje lo requiere.

cargo fluent recorre las raíces del catálogo de runtime y zerocode. fill compara cada archivo en inglés con la configuración regional seleccionada, traduce las claves faltantes a través del proveedor del modelo configurado, escribe el progreso después de cada lote y modifica los archivos .ftl rastreados. check analiza la sintaxis del catálogo, scan compara las referencias de origen con los catálogos y stats informa la cobertura sin modificar los catálogos. Las diferencias de Fluent corresponden a un cambio de localización deliberado en lugar de un trabajo de aplicación incidental.

El almacenamiento y la carga son aspectos independientes:

• Las cadenas del CLI en tiempo de ejecución siempre tienen inglés incrustado. El cargador también puede usar catálogos del CLI traducidos e incrustados por builtin_cli_ftl_source, y luego aplica un catálogo en disco como la fuente de configuración regional de mayor prioridad.
• Las descripciones de herramientas orientadas al prompt en tiempo de ejecución siempre incluyen texto en inglés y superponen los valores traducidos de tools.ftl del disco; las búsquedas opcionales ausentes no devuelven ningún valor.
• zeroclaw-tools incrusta inglés de forma independiente y carga desde disco tools.ftl para los strings de esquema y resultado propios de la herramienta, porque su crate no puede depender del runtime; las búsquedas faltantes requeridas renderizan un marcador visible {key}.
• zerocode incrusta su catálogo en inglés y superpone un zerocode.ftl traducido desde el disco. ZEROCODE_LOCALE_DIR es una anulación explícita para pruebas; la ubicación compartida habitual es <config-dir>/data/ftl/<locale>/zerocode.ftl.
• zeroclaw locales fetch descarga los catálogos de runtime y zerocode seleccionados en ese directorio de configuración regional compartido del disco, usando las rutas de catálogo declaradas por zeroclaw-config.

Para runtime, tools y zerocode, el inglés sigue siendo el mapa base. Un catálogo traducido en disco o integrado reemplaza las claves que contiene; las claves traducidas ausentes conservan su valor en inglés. Las búsquedas obligatorias informan de una clave ausente de todas las fuentes disponibles y muestran un marcador {key} visible en lugar de inventar texto de forma silenciosa; las búsquedas opcionales de descripción de herramientas en tiempo de ejecución no devuelven ningún valor.

cadenas de documentación de gettext

El Markdown en inglés es la fuente de documentación redactada, pero la extracción también ve referencias generadas, fragmentos incluidos y salida del preprocesador materializada para la compilación de extracción. Antes de ejecutar mdBook con salida xgettext, cargo mdbook sync llama a la ruta compartida de prepare_generated_book_inputs() usada por las compilaciones de locales y el servicio de un solo locale. Esa ruta regenera las referencias de CLI y configuración, el selector de locale, el tema, el mapa de teclas, el hardware, la matriz de características y las entradas de plugins a partir de sus fuentes canónicas. La extracción también se ejecuta con el preprocesador peer-groups compilado, por lo que un checkout limpio no depende de archivos ignorados ni de binarios dejados por una compilación anterior de la documentación.

cargo mdbook sync extrae los mensajes en inglés hacia messages.pot, normaliza la plantilla, inicializa o fusiona cada configuración regional sin coincidencia difusa, elimina las entradas obsoletas e informa el delta de traducciones pendientes. Cuando se proporciona un proveedor de modelos, completa las traducciones faltantes a través de tools/fill-translations; de lo contrario, no realiza llamadas al proveedor. La guía de mantenimiento contiene las opciones del comando y el procedimiento operativo.

La herramienta fill trata cada entrada gettext como una asignación de origen a traducción. Repara o descarta respuestas del modelo que contienen filtración de prompts o una nueva ruta absoluta local de la máquina, preserva los saltos de línea finales requeridos, escribe de forma incremental y elimina las marcas fuzzy de las entradas aceptadas. cargo mdbook check analiza por separado cada archivo PO y rechaza respuestas generadas sospechosas, literales protegidos corruptos y rutas locales introducidas.

Traducción parcial y reserva

El preprocesador gettext muestra el msgid en inglés cuando una configuración regional no tiene un valor traducido utilizable para esa entrada. Por lo tanto, una configuración regional puede mostrar navegación y párrafos traducidos junto con prosa en inglés recién añadida. Este estado de idioma mixto significa que la fuente en inglés ha avanzado más allá de la cobertura aceptada del catálogo; no significa que mdBook haya seleccionado dos idiomas para una misma página.

Las causas comunes son:

• una modificación en la documentación en inglés o en la referencia generada añadió un nuevo msgid;
• El sync del catálogo fusionó la nueva fuente pero no se ha ejecutado ningún relleno de traducción;
• una reparación de seguridad borró una respuesta del modelo filtrada, con rutas o de algún otro modo inutilizable;
• una edición de origen reemplazó un mensaje antiguo por uno nuevo;
• un catálogo de configuración regional o un pin de versión intencionalmente queda detrás del master actual.

Fuzzy es un estado de mantenimiento del catálogo, no una garantía de que el valor anterior sea seguro para renderizar. El comando sync actual desactiva la coincidencia difusa para las nuevas fusiones, mientras que la herramienta fill puede aceptar un valor fuzzy no vacío existente y quitar su marca. Revisa el msgstr resultante; no infieras el comportamiento de publicación solo a partir de la marca.

Las compilaciones de configuraciones regionales traducidas deshabilitan la búsqueda de texto completo. Solo la configuración regional primaria, la primera entrada en locales.toml, recibe el índice de búsqueda. Esta es una decisión de tamaño en build_locales, no una cobertura de traducción faltante.

Almacenamiento del catálogo y versiones fijadas

Los catálogos de Fluent se encuentran en el repositorio principal. Un cambio normal de traducción de Fluent actualiza directamente los archivos .ftl correspondientes y se revisa junto con el código de la aplicación que utiliza sus claves o como una revisión de traducción específica.

Los catálogos PO de la documentación residen en zeroclaw-labs/zeroclaw-docs-translations, montado en docs/book/po como un submódulo de git. El repositorio principal registra un único commit gitlink, no cada archivo PO. messages.pot y los registros de errores de traducción son artefactos generados y no forman parte del conjunto de catálogos anclado.

El asistente de publicación scripts/release/refresh-translations.sh gestiona la etiqueta de traducción y la actualización del gitlink del repositorio principal. De forma predeterminada, ejecuta la sincronización y la comprobación del catálogo, confirma y envía los cambios del catálogo en el submódulo, crea y activa la etiqueta v<version> correspondiente y prepara el gitlink. Su modo --no-translate omite tanto la sincronización como la comprobación del catálogo, por lo que solo es apropiado después de validar los catálogos actuales por separado. El flujo de trabajo de fijación de traducciones inicializa el commit fijado exacto, comprueba la sintaxis de PO y verifica que los catálogos de idioma expongan el mismo conjunto de msgid.

El despliegue de la documentación inicializa el submódulo anclado y compila todas las configuraciones regionales ya presentes. No llama a un proveedor de modelos, no completa las traducciones faltantes, no avanza el submódulo ni crea una etiqueta de lanzamiento.

Límites de validación y revisión

• Las PR ordinarias de documentación en inglés pueden posponer los cambios masivos en PO para una pasada específica de la caché de traducción. Revisa la fuente en inglés y el límite generado en la PR original.
• Incluye los cambios de PO cuando el propósito sea la traducción o el mantenimiento del catálogo, se esté añadiendo una configuración regional, el delta generado sea pequeño y revisable, o una pasada de lanzamiento esté actualizando el pin.
• Incluye los cambios de Fluent cuando cambien las claves o las cadenas traducidas de la aplicación. No afirmes que una ruta de ejecución traducida funciona simplemente porque existe su archivo .ftl; verifica la ruta de carga o de obtención/instalación pertinente.
• Mantén intacta la sintaxis de comandos protegidos, las claves de configuración, los nombres de productos, los literales JSON/TOML y los marcadores de posición. Traduce el texto circundante en lugar de debilitar los ejemplos orientados a máquinas.
• Trata un texto de reserva en inglés como evidencia visible de una cobertura de catálogo aceptada que falta. Corrige o completa la fuente del catálogo, no el HTML renderizado.
• Revisa los cambios de submódulos como operaciones de release/catálogo: inspecciona tanto el gitlink del repositorio principal como el commit del catálogo que selecciona.

Para ver comandos detallados, la configuración de proveedores, el procesamiento por lotes, cómo agregar una configuración regional y el procedimiento de publicación, consulta Documentos y traducciones. Para ver la fuente en inglés y las etapas de referencia generada que alimentan la extracción de gettext, consulta Canalización de documentación generada.

Punteros de origen

• Registro de configuraciones regionales: locales.toml
• Cargador de Fluent en tiempo de ejecución: crates/zeroclaw-runtime/src/i18n.rs
• Cargador Fluent propiedad de la herramienta: crates/zeroclaw-tools/src/i18n.rs
• Catálogos Fluent de tiempo de ejecución: crates/zeroclaw-runtime/locales/
• zerocode Cargador fluido: apps/zerocode/src/i18n.rs
• zerocode Catálogos Fluent: apps/zerocode/locales/
• Herramientas de Fluent: xtask/src/cmd/fluent/
• Mapa de descarga de catálogos: zeroclaw_config::schema::FTL_CATALOGS
• Extracción y fusión de gettext: xtask/src/cmd/mdbook/sync.rs
• Comprobaciones de seguridad de gettext: xtask/src/cmd/mdbook/check.rs
• gettext relleno y reparación: tools/fill-translations/
• Comportamiento de compilación y búsqueda de idiomas: xtask/src/cmd/mdbook/build.rs
• Validación de anclaje de traducción: .github/workflows/validate-translations-pin.yml
• Actualización del catálogo de versiones: scripts/release/refresh-translations.sh
• Despliegue de documentación: .github/workflows/docs-deploy.yml