Documentos

Diseñado principalmente para documentación de markdown, MDX y .astro gestionada a través de bloques de configuración de docs[]. El campo contentPaths de cada bloque enumera los archivos o carpetas a traducir.

En los sitios de Docusaurus, también configure docusaurusCatalogDir en su carpeta de catálogo write-translations (por ejemplo, docs-site/i18n/en). Entonces translate-docs también incluye JSON de shell: barra de navegación, pie de página y cadenas de tema.

En los sitios de VitePress, los cuerpos de las páginas utilizan la misma canalización docs[]. Las etiquetas de navegación, barra lateral y pie de página se encuentran en docsOutput.vitepressThemeCatalog: translate-docs arranca el catálogo en inglés y lo traduce junto con las páginas, sin una canalización separada.

En los sitios de Nextra, los cuerpos de las páginas utilizan la misma canalización docs[] con docsOutput.style: "nextra". Las etiquetas de la barra lateral de _meta.ts son recopiladas y traducidas automáticamente por translate-docs; las cadenas del diccionario del tema se traducen a través de docs[].nextraDictionaryPath en la misma canalización.

En los sitios de Fumadocs, los cuerpos de las páginas utilizan docsOutput.style: "fumadocs" con fumadocsParser "dot" (predeterminado) o "dir". Las etiquetas de la barra lateral de meta.json se recopilan automáticamente; las anulaciones de la interfaz de usuario se traducen a través de docsOutput.fumadocsUiCatalog.

En los sitios de Astro Starlight, los cuerpos de las páginas usan docsOutput.style: "astro-starlight" con docsRoot en la raíz de su contenido de Starlight (normalmente src/content/docs/). translate-docs escribe markdown/MDX localizado bajo src/content/docs/<locale>/ junto al árbol en inglés. Starlight incluye cadenas de interfaz de usuario integradas para muchas configuraciones regionales; no hay una canalización de catálogo de temas separada; las anulaciones opcionales de la interfaz de usuario pueden usar jsonPathTemplate en un bloque docs[] para src/content/i18n/en.json.

Para imágenes PNG y otras imágenes rasterizadas incrustadas en markdown, consulte Imágenes y capturas de pantalla. translate-docs solo traduce el texto alternativo; no copia archivos rasterizados.

Para un bloque opcional de selector de idioma en README o documentos, configure docsOutput.style en "flat"; consulte Selector de idioma.

Los archivos SVG se traducen a través de translate-svg cuando features.translateSVG está habilitado, no a través de docs[] / contentPaths.

Los paquetes JSON de interfaz de usuario anidados arbitrarios no relacionados con las cadenas de shell/tema de un framework de documentación pertenecen a la canalización JSON, no a docs[].

Para la coherencia terminológica entre la interfaz de usuario y la documentación, configure glossary.uiGlossary en su ruta strings.json; translate-docs reutiliza las traducciones de interfaz de usuario existentes como sugerencias en las indicaciones de LLM cuando aparecen términos coincidentes en un segmento. El glossary.userGlossary opcional agrega anulaciones de CSV para términos de productos (compartidos con translate-ui y proofread-ui). Genere un CSV inicial con glossary-generate, edite filas en la pestaña Glosario del Panel de traducción, o consulte Configuración — glossary y Glosario.

Anulaciones de modelo por configuración regional

translate-docs y el paso de documentos de sync resuelven modelos por configuración regional de destino: primero localeModels(locale) cuando está configurado, luego la cadena global translationModels del proveedor. Use esto cuando un idioma específico necesite un modelo diferente a su lista de reserva predeterminada; por ejemplo, prefiriendo Gemini para la documentación de pt-BR cuando la cadena global tiene dificultades con el portugués. Consulte Proveedores y modelos y Configuración - localeModels.

Qué guía leer

Su configuración	Empiece aquí
Sitio de Docusaurus	init -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus
Sitio de VitePress	init -t ui-vitepress + vitepressThemeCatalog para el tema - VitePress
Sitio de Nextra	init -t ui-nextra + nextraDictionaryPath para el diccionario (la barra lateral _meta.ts es automática) - Nextra
Sitio de Fumadocs	init -t ui-fumadocs + fumadocsUiCatalog para la interfaz de usuario (la barra lateral meta.json es automática) - Fumadocs
Astro Starlight	init -t ui-starlight - Astro Starlight
Documentos planos (README, registros de cambios, etc.)	docsOutput.style = "flat" - Diseños de salida, selector de idioma opcional
Dónde aterrizan los archivos traducidos	Diseños de salida
Enlaces #anchor entre páginas	Enlaces de anclaje
Reescritura de URL de enlaces y activos (regexAdjustments)	Reescritura de enlaces
Capturas de pantalla en documentos	Imágenes y capturas de pantalla
Terminología de productos y coherencia de UI/documentos	Configuración — glossary, Glosario
Banderas y caché de translate-docs	Opciones de CLI

Paso 1: Inicializar para la documentación

ai-i18n-tools init -t ui-docusaurus [-P <provider>]

Para sitios de documentación Astro Starlight:

ai-i18n-tools init -t ui-starlight [-P <provider>]

Para sitios de documentación de VitePress:

ai-i18n-tools init -t ui-vitepress [-P <provider>]

Configure docsOutput.vitepressThemeCatalog para las cadenas de navegación/barra lateral/pie de página; consulte Integración de VitePress.

Para sitios de documentación de Nextra:

ai-i18n-tools init -t ui-nextra [-P <provider>]

Configure docs[].nextraDictionaryPath para las cadenas del diccionario de temas; consulte Integración de Nextra. Las etiquetas de la barra lateral _meta.ts se recopilan automáticamente.

Para sitios de documentación de Fumadocs:

ai-i18n-tools init -t ui-fumadocs [-P <provider>]

Configure docsOutput.fumadocsUiCatalog para las anulaciones de la interfaz de usuario; consulte Integración de Fumadocs. Las etiquetas de la barra lateral meta.json se recopilan automáticamente.

Para la interfaz de un sitio web Astro plano (sin Starlight):

ai-i18n-tools init -t ui-astro-website [-P <provider>]

Esa plantilla solo permite la extracción de la interfaz de usuario. Para la traducción de HTML de páginas, también configure features.translateDocs y agregue un bloque docs[] (consulte Páginas del sitio web de Astro (analizar y reemplazar)). La configuración de examples/astro-website muestra ambas canalizaciones juntas.

Edite el ai-i18n-tools.config.json generado:

• provider y providers — init genera un bloque de proveedor predeterminado (openrouter a menos que pase -P <provider>); configure al menos un proveedor y establezca su clave API antes de translate-docs o sync (Ollama no necesita clave). Consulte Proveedor y clave API y Proveedores y modelos de LLM.
• sourceLocale - idioma de origen (debe coincidir con defaultLocale en docusaurus.config.js).
• targetLocales - matriz de códigos de configuración regional BCP-47 (por ejemplo, ["de", "fr", "es"]).
• cacheDir - directorio de caché SQLite compartido para todas las canalizaciones (y directorio de registro predeterminado para --write-logs).
• docs - array de bloques de documentación. Cada bloque tiene description opcional, contentPaths (cadena o array; archivo, directorio o patrón), outputDir, docusaurusCatalogDir opcional, docsOutput, segmentSplitting opcional, translateFrontmatterFields, protectAttributes, protectKeys, targetLocales, addFrontmatter, etc.
• docs[].description - nota breve opcional para los mantenedores. Cuando se establece, aparece en el titular de translate-docs y en los encabezados de sección de status.
• docs[].contentPaths - fuentes de markdown/MDX/.astro (y docusaurusCatalogDir opcional para JSON de shell de Docusaurus).
• docs[].outputDir - raíz de salida traducida para ese bloque.
• docs[].docsOutput.style - "nested" (predeterminado), "flat", "doc-system", o alias "docusaurus" / "astro-starlight" / "vitepress" / "nextra" / "fumadocs" (consulte Diseños de salida).
• glossary.uiGlossary - ruta a strings.json para que los segmentos de documentos obtengan sugerencias de terminología de su catálogo de UI (consulte Configuración — glossary).
• glossary.userGlossary - CSV opcional para traducciones de términos de productos fijos; también utilizado por las canalizaciones de UI y editable en la pestaña del panel Glosario.

Principal frente a suplementario: Enfóquese en contentPaths para páginas localizadas. Establezca docusaurusCatalogDir cuando también necesite JSON del shell de Docusaurus desde write-translations. Omita docusaurusCatalogDir si solo traduce páginas.

Paso 2: Traducir documentos

ai-i18n-tools translate-docs

Esto traduce todos los archivos en el contentPaths de cada bloque docs[] (y el JSON del catálogo de Docusaurus cuando se establece docusaurusCatalogDir) a todas las configuraciones regionales de documentación efectivas. Los segmentos ya traducidos se sirven desde la caché de SQLite; solo los segmentos nuevos o modificados se envían al LLM.

Para traducir un solo idioma:

ai-i18n-tools translate-docs --locale de

Para comprobar qué necesita traducción:

ai-i18n-tools status

Para conocer las banderas, el comportamiento de la caché y el formato de solicitud por lotes, consulte Opciones de la CLI.

Markdown complejo y comprobaciones de calidad fallidas

translate-docs verifica que cada segmento traducido preserve la estructura de markdown (incluido el énfasis analizado desde el documento). Párrafos que acumulan muchos elementos bold alrededor de `inline code`, anidan comillas invertidas dentro de negritas (por ejemplo, literales de plantilla como `fetch(\`/locales/${code}.json\`)`), o entrelazan negritas y código en una oración larga son frágiles: algunas configuraciones regionales necesitan un orden de palabras diferente, lo cual puede alterar cómo coinciden ** y ` tras la traducción y provocar errores en la CLI como AST mismatch.

Si encuentra ese tipo de error de validación, prefiera simplificar el texto en el idioma de origen (divida el párrafo, mueva un ejemplo a un bloque de código delimitado o describa la misma idea con menos pares de negrita/código en capas) en lugar de esperar que cada modelo y configuración regional reproduzcan perfectamente el marcado en línea denso.

Cuando todos los modelos configurados fallan con un AST mismatch en el mismo segmento, translate-docs puede dividir automáticamente ese segmento en partes más pequeñas (primero el punto medio de la lista, luego elementos individuales de la lista o fragmentos más cortos de párrafo), volver a intentar cada parte desde el primer modelo y volver a unir el resultado bajo la clave original de caché del segmento. Esta función está activada por defecto (segmentSplitting.qualityRetrySplit); establézcala en false para detenerse tras agotar todos los modelos. El resumen de ejecución informa Quality split retries cuando se ejecuta este mecanismo de respaldo.

Para ver qué segmentos fallaron, con qué frecuencia y los mensajes de calidad/error almacenados, use la pestaña Fallos del Panel de traducción (Panel de traducción → Fallos).