Documentación y traducciones

ZeroClaw tiene dos capas de traducción independientes:

Para conocer la fuente de verdad, el almacenamiento, la carga, los mecanismos de reserva y los límites de publicación que respaldan estos procedimientos, consulte Ciclo de vida del catálogo de localización. Las referencias en inglés generadas que alimentan la extracción de documentación están mapeadas en Canal de documentación generada.

Se rellenan por separado y se almacenan por separado. Ambos utilizan la ruta de tiempo de ejecución compartida independiente del proveedor: configure un proveedor de modelo en providers.models.<kind>.<alias> y pase --model-provider <alias> a los comandos de relleno. Cualquier alias configurado es seleccionable: un alias simple (--model-provider <alias>), o un calificador kind.alias (--model-provider anthropic.<alias>) cuando el mismo alias existe bajo más de un tipo. El resolutor requiere que la entrada coincidente nombre un modelo y luego delega los valores predeterminados de endpoint, autenticación, protocolo de comunicación y el manejo opcional de uri personalizado a la pila del proveedor en tiempo de ejecución.

Los modelos locales mediante Ollama son una opción de primera clase: no se requieren claves de API ni hay costo por llamada. Un proveedor alojado también es adecuado para calidad de nivel de lanzamiento. La traducción es una operación local. Ejecuta cargo mdbook sync para PRs dedicados a la caché de traducción, pasadas de traducción de lanzamiento y nuevas configuraciones regionales; los PRs rutinarios de documentación en inglés pueden aplazar los cambios masivos generados en archivos .po a un seguimiento específico posterior.

Configuración del proveedor

Ollama es la fuente canónica actual para la documentación. Asegúrate de tener Ollama instalado y de haber descargado qwen3:30b-a3b, luego configura una entrada de proveedor de Ollama. uri es la URL completa del endpoint y es opcional: déjala sin definir para usar el endpoint predeterminado de la familia del proveedor (resuelto por la pila de proveedores en tiempo de ejecución). Defínela solo para apuntar a una puerta de enlace o proxy autoalojado. Cualquier familia configurada funciona (Anthropic, OpenAI, OpenRouter, Ollama, …); las herramientas de traducción construyen el proveedor real en tiempo de ejecución, de modo que el endpoint, el encabezado de autenticación y el protocolo de comunicación de cada familia se gestionan automáticamente: no hay requisito de compatibilidad con OpenAI.

Compilar la documentación localmente

Catálogos de traducción (submódulo de git)

Los catálogos .po traducidos viven en el submódulo zeroclaw-labs/zeroclaw-docs-translations montado en docs/book/po. El ciclo de desarrollo en Rust (cargo build, cargo test, cargo clippy) no lo necesita, pero construir o sincronizar la documentación sí. Inicialízalo una vez:

git clone --recurse-submodules https://github.com/zeroclaw-labs/zeroclaw   # clonación nueva
git submodule update --init docs/book/po                                   # clon existente

Sin el submódulo extraído, inglés sigue compilando (el código fuente en inglés vive en docs/book/src/), pero las versiones localizadas se renderizan vacías.

Inicio rápido con un solo comando

cargo mdbook serve                       # servir todas las localizaciones en http://localhost:3000/en/
cargo mdbook serve --locale ja           # recarga en vivo contra fuentes en japonés
cargo mdbook build                       # compilación estática de cada localización en docs/book/book/
cargo mdbook refs                        # regenerar las páginas de referencia generadas automáticamente
cargo mdbook sync                        # pase de translation-cache: volver a extraer + fusionar archivos .po
cargo mdbook sync --locale ja            # sincronizar solo una configuración regional
cargo mdbook sync --force                # Forzar la retraducción de todo (paso de calidad)
cargo mdbook sync --locale ja --force    # forzar la retraducción de una configuración regional
cargo mdbook stats                       # mostrar traducidos/ambiguos/no traducidos por localización
cargo mdbook check                       # validar el formato .po (ejecutar antes de un PR de traducción)

Utiliza siempre el contenedor cargo mdbook …. Ejecutar mdbook build directamente desde docs/book/ omite el paso de xtask que renderiza theme/lang-switcher.js a partir de locales.toml, lo que provoca un fallo en la compilación con el error failed to open theme/lang-switcher.js for hashing.

Herramientas requeridas

cargo mdbook fallará rápidamente y te indicará qué falta, pero como referencia:

La versión de mdbook-mermaid está fijada, pero su archivo de bloqueo publicado sigue seleccionando el preprocesador de mdBook 0.5.0. No incluyas --locked para esa herramienta, de modo que Cargo resuelva el preprocesador 0.5.x compatible que usa mdBook 0.5.4.

Qué se construye en cada lugar

Los dos archivos reference/*.md se generan a partir de las derivaciones clap reales y del esquema JSON en el código; nunca los edites a mano. En su lugar, edita los comentarios de documentación /// en los tipos de Rust relevantes.

cargo mdbook es un alias de cargo run -p xtask --bin mdbook -- (definido en la configuración de cargo). Para una versión más concisa de esta sección orientada a colaboradores, consulte Building the docs locally.

[!NOTE] La búsqueda de texto completo se genera únicamente para la configuración regional principal (inglés, la primera en locales.toml). Las configuraciones regionales traducidas se generan sin índice de búsqueda ni cuadro de búsqueda. Los índices de búsqueda por configuración regional son grandes (~6-7 MB cada uno) y dominan el tamaño del clon de gh-pages; restringir la búsqueda al inglés mantiene los clones ligeros. Volver a agregar un cuadro de búsqueda a una configuración regional traducida implica volver a habilitar output.html.search.enable para esa generación en build_locales (xtask/src/cmd/mdbook/build.rs).

Cómo se mantienen actualizadas las traducciones

Cuando cambia la fuente en inglés, cargo mdbook sync ejecuta dos etapas:

1. Extraer: mdbook-xgettext regenera po/messages.pot a partir de la fuente actual en inglés.
2. Merge: msgmerge --no-fuzzy-matching actualiza el archivo .po de cada configuración regional, asigna a las cadenas de origen nuevas o modificadas un msgstr "" vacío y elimina las entradas obsoletas. Solo las entradas fuzzy que ya estaban presentes antes de la fusión pueden seguir disponibles para una revisión posterior o para aceptar el rellenado.

Luego el comando cuenta las entradas difusas + sin traducir y, cuando se proporciona --model-provider, completa solo esas. Las cadenas sin cambios no cuestan nada: la caché de .po significa que volver a ejecutar contra un código fuente sin cambios es una operación nula. Sin --model-provider, sync aún ejecuta extract + merge e informa el delta; las cadenas sin msgstr recurren al inglés en el momento del renderizado.

La sincronización normaliza los catálogos con reglas de salida estables (msgcat --sort-output --no-wrap --add-location=file), de modo que los diffs se mantienen enfocados en los cambios reales del código fuente. Cambios inevitables: metadatos del encabezado (POT-Creation-Date, etc.), actualizaciones de ubicaciones de referencia cuando una cadena cambia de archivo, y ediciones reales de cadenas de origen.

Los PRs rutinarios de documentación en inglés pueden aplazar cambios extensos en archivos .po a un seguimiento específico. Incluya actualizaciones de .po solo cuando el PR sea una pasada de caché de traducciones, una pasada de traducciones de versión, agregue una configuración regional o produzca un diff pequeño y fácil de revisar.

Rellenar cadenas de la aplicación (Fluent)

Las cadenas de la aplicación se encuentran en crates/zeroclaw-runtime/locales/. El inglés es la fuente de verdad y se incrusta en tiempo de compilación.

Límite de carga en tiempo de ejecución.

• Fuentes incrustadas: cli.ftl y tools.ftl en inglés están incrustados. builtin_cli_ftl_source() enumera los catálogos de CLI en idiomas distintos del inglés incrustados por el entorno de ejecución; zeroclaw-tools incrusta por separado las cadenas de texto de las herramientas en inglés para preservar la dirección de las dependencias entre crates.
• Superposición de disco: Un catálogo en <config-dir>/data/ftl/<locale>/ anula un valor incrustado en la CLI y proporciona valores de tiempo de ejecución/herramienta traducidos. zeroclaw locales fetch completa este directorio compartido.
• Advertencia de consumo: Completar y confirmar un archivo .ftl actualiza la fuente del catálogo con seguimiento, pero un consumidor lo usa solo cuando su cargador incrusta ese catálogo o el archivo está instalado donde ese cargador lo lee.

La TUI de apps/zerocode mantiene un catálogo Fluent independiente (apps/zerocode/locales/), consulta cadenas de zerocode más abajo. cargo fluent recorre ambas raíces de catálogos (runtime + zerocode), por lo que cada subcomando a continuación cubre ambas de forma predeterminada.

cargo fluent stats                                                   # cobertura por configuración regional, por catálogo
cargo fluent check                                                   # validar la sintaxis de `.ftl` en ambos catálogos
cargo fluent fill --locale ja --model-provider anthropic.<alias>             # fill missing keys (default batch 50)
cargo fluent fill --locale ja --model-provider anthropic.<alias> --batch 10  # lotes más pequeños: menos entradas por solicitud (reduce los límites de tasa / truncamiento)
cargo fluent fill --locale ja --model-provider anthropic.<alias> --force     # volver a traducir todo
cargo fluent scan                                                    # Buscar claves obsoletas o faltantes frente al código fuente de Rust

Limitar a un solo catálogo: cada subcomando acepta --catalog <runtime|zerocode> (predeterminado: ambos). Para traducir solo la TUI:

cargo fluent fill --locale ja --model-provider anthropic.<alias> --catalog zerocode
cargo fluent check --catalog zerocode                                # solo verificación de sintaxis zerocode

Un valor --catalog desconocido genera un error con las opciones válidas.

fill genera <locale>/<domain>.ftl para cada raíz de catálogo seleccionada que tenga un directorio en/: los archivos cli.ftl/tools.ftl del runtime y zerocode.ftl de zerocode.

La resolución de proveedores se comparte con el runtime. --model-provider acepta cualquier alias configurado bajo [providers.models.<kind>.<alias>]: un alias simple (<alias>) o un calificador kind.alias (anthropic.<alias>) cuando hay ambigüedad. La herramienta construye el proveedor real del runtime, por lo que el endpoint, el encabezado de autenticación y el protocolo de transmisión se resuelven por familia (Anthropic /v1/messages + x-api-key, compatible con OpenAI /v1/chat/completions + Bearer, etc.): nada se da por supuesto. Los valores de api_key cifrados se descifran mediante el SecretStore canónico. Use --config-dir <dir> (equivalente a zeroclaw --config-dir) para leer la configuración + .secret-key desde una ubicación no predeterminada; por defecto usa ~/.zeroclaw y luego ~/.config/zeroclaw.

Procesamiento por lotes: fill envía una solicitud por lote (las N entradas como un único objeto JSON); --batch reduce N para aliviar los límites de tasa del proveedor o el truncamiento de respuestas en entradas largas. Cada lote se escribe en disco antes de la siguiente solicitud, por lo que un fallo a mitad de ejecución solo pierde el lote en curso. Al volver a ejecutar se omiten las claves que ya existen en el .ftl de destino, de modo que la reanudación es automática: no se necesita --force.

zerocode strings (Fluent, independiente)

apps/zerocode incluye su propia configuración de Fluent autocontenida, separada de los catálogos del runtime mencionados arriba. La TUI está intencionalmente desacoplada del resto del workspace: no tiene ninguna dependencia de crates zeroclaw-*, y sus cadenas residen junto a su código fuente en lugar de bajo zeroclaw-runtime/locales/.

Espacio de nombres de claves

Todas las claves zerocode llevan el prefijo zc- y nunca colisionan con los espacios de nombres cli-, channel- ni tool- del runtime. La convención dentro de zc- es zc-<pane>-<purpose>:

• zc-pane-<name>: etiquetas de la barra de modos de nivel superior
• zc-app-<purpose>: cadenas pertenecientes a app.rs (diálogos, ayuda, estado)
• zc-<pane>-<purpose>: cadenas locales de un panel específico (zc-dashboard-*, zc-chat-*, …)

Los acordes literales no se traducen

Los glifos de combinación de teclas como Ctrl+C, Esc, Shift+Up son protocolo, no idioma. Los constructores HelpEntry y HelpNode reciben el vector de combinaciones como &'static str y la descripción como String, de modo que los literales de combinación permanecen codificados de forma fija mientras que las descripciones pasan por t(). Cuando la prosa incrusta una combinación de teclas en línea, usa un espacio reservado de Fluent { $keys } y pasa la combinación en el momento del renderizado en lugar de concatenar texto traducido alrededor de un literal.

Resolución de configuración regional

La configuración regional proviene de un campo locale de nivel superior en la configuración de zerocode. Cuando no está establecido, i18n::detect_locale() lee el directorio de configuración resuelto como --config-dir, luego ZEROCLAW_CONFIG_DIR, luego ~/.zeroclaw, y en caso contrario recurre a en como valor predeterminado. zerocode resuelve su configuración regional de forma independiente a partir de su propia configuración; no comparte la búsqueda del daemon.

Agregando cadenas

1. Añade la clave + el valor en inglés a apps/zerocode/locales/en/zerocode.ftl. Agrupa las claves por archivo de origen con un comentario de sección para que el catálogo siga siendo fácil de revisar.
2. Reemplaza el literal en el código fuente con crate::i18n::t("zc-…"). Para los brazos de match de enum→etiqueta, devuelve la constante de clave (&'static str) desde un método fluent_key() y llama a t() en el punto de renderizado, nunca hagas match sobre una cadena.
3. cargo check -p zerocode y las pruebas unitarias de i18n (cargo test -p zerocode i18n) detectan las claves faltantes en tiempo de compilación/prueba. Las claves faltantes en tiempo de ejecución se muestran como {zc-key-name} y emiten una advertencia única por stderr.

Rellenando traducciones

cargo fluent recorre el catálogo de zerocode junto al catálogo de tiempo de ejecución, por lo que no se necesita un comando de relleno separado. Al ejecutar cargo fluent fill --locale <code> --model-provider <alias> se genera apps/zerocode/locales/<code>/zerocode.ftl en el mismo pase que rellena el catálogo de tiempo de ejecución. cargo fluent check y cargo fluent stats también informan sobre zerocode; scan indexa apps/ para que las referencias a claves zc- se resuelvan contra la fuente de zerocode. Para ejercitar la traducción en zerocode, instálala a través de zeroclaw locales fetch o colócala bajo una de las dos raíces de búsqueda en disco mencionadas anteriormente.

Rellenando traducciones de documentación (gettext)

Las traducciones de documentación se encuentran en docs/book/po/. cargo mdbook sync ejecuta extract → merge → strip obsolete → AI-fill en un solo paso. Sin --model-provider, sync igualmente ejecuta extract + merge e informa cuántas cadenas necesitan traducción: las traducciones parciales recurren al inglés en el momento del renderizado.

cargo mdbook sync --model-provider anthropic.<alias>              # delta fill
cargo mdbook sync --model-provider anthropic.<alias> --force      # pase de calidad: volver a traducir todas las entradas
cargo mdbook sync --model-provider anthropic.<alias> --batch 1    # escribir después de cada entrada (reanudación más segura)
cargo mdbook sync --locale ja --model-provider anthropic.<alias>  # single locale
cargo mdbook sync --model-provider anthropic.<alias> --config-dir ~/.zeroclaw  # alias calificado + directorio de configuración explícito

--model-provider se resuelve a través de la misma ruta compartida de proveedor en tiempo de ejecución que cargo fluent (cualquier familia/alias configurado, endpoint por familia + autenticación + protocolo de transmisión, descifrado de SecretStore, compatibilidad con --config-dir). A diferencia de cargo fluent, que envía un lote completo como un único objeto JSON, el rellenador de gettext emite una solicitud por cada cadena de origen para mantener inequívoca la correspondencia msgid → msgstr, por lo que --batch controla con qué frecuencia se vuelca el .po a disco (el intervalo de punto de control), no el tamaño de la solicitud. Una configuración regional con el catálogo completo supone miles de solicitudes secuenciales; para rellenos incrementales rutinarios, un alias local económico de Ollama es la opción más rentable.

El pipeline tiene resiliencia integrada:

• Detección de fugas: si un modelo devuelve sus propias instrucciones en lugar de una traducción, la herramienta detecta el patrón (mediante la proporción de longitud de la respuesta y la estructura de listas con viñetas), intenta recuperar la traducción real del final de la respuesta y deja la entrada en blanco para volver a traducirla si la recuperación falla.
• Verificaciones de literales protegidos: cargo mdbook check también rechaza corrupción de literales de alta confianza en los archivos .po generados. Los nombres de producto como ZeroClaw Maturity Framework, los literales de comandos como zeroclaw daemon y los literales de secciones/claves TOML en bloques delimitados deben permanecer intactos byte por byte dentro de las traducciones. Traduce la prosa circundante, no el texto destinado a las máquinas.
• Comprobaciones de fugas de rutas: las traducciones generadas no deben introducir rutas absolutas locales de la máquina que no estuvieran presentes en el original en inglés; esas entradas se vacían para volver a traducirse y se rechazan mediante cargo mdbook check.
• Escrituras incrementales: después de cada lote, el archivo .po se reescribe. Un Ctrl-C a mitad de la ejecución no pierde el progreso logrado hasta ese momento.
• Eliminación de obsoletos: msgmerge + msgattrib --no-obsolete evitan que las cadenas eliminadas del código fuente se acumulen como entradas #~.

Los mantenedores deben aceptar la excepción habitual de documentación en inglés documentada en Building the docs locally. Solicita actualizaciones de .po solo cuando el PR sea en sí mismo una pasada de caché de traducción, una pasada de traducción de versión, un cambio de nuevo idioma, o el diff generado sea lo suficientemente pequeño como para revisarlo.

Añadiendo una nueva configuración regional

1. Edita locales.toml en la raíz del repositorio, el único archivo que necesitas modificar:

2. Traduce las cadenas de la aplicación:

   sh

   cargo fluent fill --locale <code> --model-provider ollama
   

3. Inicia y completa el archivo de documentación .po:

   sh

   cargo mdbook sync --locale <code> --model-provider ollama
   

4. La ejecución de cargo fluent fill en el paso 2 ya genera apps/zerocode/locales/<code>/zerocode.ftl en la misma pasada, dado que cargo fluent recorre tanto los catálogos de runtime como los de zerocode. No se necesita ningún paso manual de zerocode; verifique la cobertura con cargo fluent stats.

Todo lo demás, lang-switcher.js, la lista de destinos de despliegue de CI, la salida de cargo mdbook locales, se lee automáticamente desde locales.toml.

Submódulo del catálogo de traducciones

Los catálogos .po traducidos no están en el árbol principal de este repositorio. Viven en el repositorio dedicado zeroclaw-labs/zeroclaw-docs-translations, montado como un submódulo de git en docs/book/po (rama predeterminada main). El punto de montaje es transparente para la ruta: el preprocesador gettext de book.toml, cargo mdbook sync y cargo mdbook build leen po/ exactamente como antes.

El bucle de desarrollo del crate de Rust nunca necesita el submódulo. Solo las compilaciones de documentación y los trabajos de docs-deploy / release lo requieren; esos checkouts pasan submodules: recursive. Todo lo demás permanece sin submódulos.

En cada versión, scripts/release/refresh-translations.sh publica los catálogos modificados en la rama main del submódulo, etiqueta ese commit como v{version}, extrae la etiqueta y prepara el gitlink del repositorio principal. bump-version.sh deja deliberadamente la fijación de traducciones a ese asistente. messages.pot y *.failures.log son artefactos regenerados y están en gitignore en ambos repositorios, no se rastrean.

Flujo de trabajo de traducción de la versión

El procedimiento de actualización, validación, etiquetado, envío y anclaje de gitlink en el momento del lanzamiento forma parte del Paso 2 del Manual de Lanzamiento. Esta página documenta el sistema de traducción; utilice el manual como fuente de verdad operativa al preparar un lanzamiento.

Notas sobre la calidad del modelo

La calidad de la traducción varía significativamente según el idioma y el modelo.

Para versiones finales, se recomienda usar un modelo de frontera alojado mediante --force. Durante el desarrollo, para llenados incrementales continuos, un modelo local de Ollama es adecuado y gratuito.