Referencia de configuración

`sourceLocale`

Código BCP-47 para el idioma de origen (por ejemplo, "en-GB", "en", "pt-BR"). No se genera ningún archivo de traducción para esta configuración regional — la propia cadena clave es el texto fuente.

Debe coincidir con SOURCE_LOCALE exportado desde su archivo de configuración de i18n en tiempo de ejecución (src/i18n.ts / src/i18n.js).

`targetLocales`

Matriz de códigos de configuración regional BCP-47 a los que traducir (por ejemplo, ["de", "fr", "es", "pt-BR"]).

targetLocales es la lista principal de configuraciones regionales para la traducción de la interfaz de usuario y la lista predeterminada para bloques de documentación. Usa generate-ui-languages para generar el manifiesto ui-languages.json a partir de sourceLocale + targetLocales.

`uiLanguage` (opcional)

Código BCP-47 para el idioma de la interfaz de usuario de la herramienta (ayuda de la CLI, registros/resúmenes y el Panel de traducción). Es independiente de sourceLocale / targetLocales y se anula mediante el indicador -L / --ui-lang y la variable de entorno AI_I18N_LANG. Los valores desconocidos se degradan correctamente a la configuración regional de origen (en-GB); no hay una validación estricta. Consulte Idioma de la interfaz de usuario de la herramienta.

`languagesManifestPath` (opcional)

Cadena opcional de nivel raíz (no anidada bajo ui). Ruta donde extract y generate-ui-languages escriben el manifiesto ui-languages.json, y donde la CLI lo lee para nombres de visualización y post-procesamiento de la lista de idiomas. Cuando se omite, el valor predeterminado es ui.flatOutputDir/ui-languages.json al cargar la configuración.

Utiliza esto cuando:

El manifiesto debe residir fuera de ui.flatOutputDir (por ejemplo, junto a los ayudantes de la aplicación en src/i18n/).
Desea que el post-procesamiento del selector de idioma (languageListBlock) cree etiquetas de configuración regional a partir del manifiesto del proyecto en lugar de solo el catálogo maestro incluido.

includeUiLanguageEnglishNames no lee este archivo, utiliza el catálogo maestro incluido (consulte ui.uiExtractor a continuación).

Heredado: uiLanguagesPath de nivel raíz todavía se acepta al cargar un archivo de configuración y se reescribe automáticamente a languagesManifestPath.

`concurrency` (opcional)

Número máximo de configuraciones regionales destino traducidas simultáneamente (translate-ui, translate-docs, translate-svg y los pasos correspondientes dentro de sync). Si se omite, la CLI usa 4 para traducción de interfaz de usuario y 3 para traducción de documentación (valores predeterminados integrados). Puedes anularlo por ejecución con -j / --concurrency.

`batchConcurrency` (opcional)

translate-docs, translate-svg y translate-json (y los pasos correspondientes dentro de sync): solicitudes por lotes máximas de LLM paralelas por archivo (cada lote puede contener muchos segmentos). El valor predeterminado es 4 cuando se omite. Ignorado por translate-ui. Anule con -b / --batch-concurrency.

`fileConcurrency` (opcional)

Número máximo de archivos procesados simultáneamente dentro de una sola configuración regional durante translate-docs y sync. Cuando se establece en un valor mayor que 1, los archivos dentro de la misma configuración regional se procesan en paralelo usando un semáforo para controlar el uso de memoria. Valor predeterminado 1 (procesamiento secuencial) si se omite. Valores más altos pueden mejorar significativamente el rendimiento en operaciones limitadas por E/S, especialmente cuando todos los segmentos ya están en caché (sin necesidad de llamadas a la API).

Ejemplo:

json

{
  "fileConcurrency": 4
}

Caso de uso: Establezca esto en 2-4 al ejecutar sync --force-update con aciertos del 100 % en la caché para reducir el tiempo total de procesamiento. La mejora es más notable con muchos archivos pequeños.

`batchSize` / `maxBatchChars` (opcional)

Agrupación de segmentos para translate-docs, translate-svg y translate-json: cuántos segmentos por solicitud de API y un límite de caracteres. Valores predeterminados: 20 segmentos, 4096 caracteres (cuando se omite).

`provider` y `providers`

provider (nivel superior, opcional) selecciona la clave del proveedor activo de providers. Es opcional cuando se configura exactamente un proveedor; es obligatorio cuando se configuran más de uno.

providers (nivel superior) mapea una clave de proveedor a su bloque. Las claves integradas (ver la tabla de preajustes a continuación) solo necesitan translationModels; cualquier otra clave define un endpoint personalizado compatible con OpenAI y requiere baseUrl (más apiKeyEnv a menos que el endpoint no necesite clave).

Cada bloque de providers.<name> acepta:

translationModels Lista ordenada preferida de ID de modelo (ID de origen sin formato, sin prefijo provider/; los ID de OpenRouter mantienen su formato nativo vendor/model). El primero se intenta primero; las entradas posteriores son alternativas en caso de error. Esta es la cadena predeterminada global para cada canalización cuando no se aplica un nivel más específico.
uiModels (opcional) Lista de modelos ordenada solo para la interfaz de usuario para translate-ui, generación plural (Paso 0 y Paso B) y proofread-ui. Se intenta después de cualquier entrada localeModels coincidente para la configuración regional de destino, antes de translationModels.
localeModels (opcional) Anulaciones por configuración regional para todas las canalizaciones de traducción. Matriz de objetos { "locale": "<BCP-47>", "models": ["…"] }. Las etiquetas de configuración regional se comparan sin distinción entre mayúsculas y minúsculas (pt-br = pt-BR). La lista de cada configuración regional se intenta primero solo para esa configuración regional, luego los niveles específicos de la canalización (uiModels para la interfaz de usuario) y translationModels. Las claves de configuración regional normalizadas duplicadas se rechazan en la carga de configuración.
baseUrl URL base compatible con OpenAI. Anula la URL base preestablecida; necesaria para un proveedor no preestablecido.
apiKeyEnv Variable de entorno que contiene la clave API. Anula la variable de entorno preestablecida.
headers Encabezados HTTP adicionales enviados con cada solicitud a este proveedor.
maxTokens Máximo de tokens de finalización por solicitud. Predeterminado: 8192.
temperature Temperatura de muestreo. Predeterminado: 0.2.
requestTimeoutMs Tiempo máximo en milisegundos para esperar cada solicitud. Predeterminado: 30000 (30 segundos).

Presets de proveedores integrados (clave — URL base — variable de entorno de clave API):

Proveedor	URL base	Variable de entorno de clave API
`openrouter`	`https://openrouter.ai/api/v1`	`OPENROUTER_API_KEY`
`openai`	`https://api.openai.com/v1`	`OPENAI_API_KEY`
`anthropic`	`https://api.anthropic.com/v1`	`ANTHROPIC_API_KEY`
`gemini`	`https://generativelanguage.googleapis.com/v1beta/openai`	`GOOGLE_API_KEY`
`deepseek`	`https://api.deepseek.com`	`DEEPSEEK_API_KEY`
`cerebras`	`https://api.cerebras.ai/v1`	`CEREBRAS_API_KEY`
`groq`	`https://api.groq.com/openai/v1`	`GROQ_API_KEY`
`mistral`	`https://api.mistral.ai/v1`	`MISTRAL_API_KEY`
`xai`	`https://api.x.ai/v1`	`XAI_API_KEY`
`nvidia`	`https://integrate.api.nvidia.com/v1`	`NVIDIA_API_KEY`
`alibaba`	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`	`ALIBABA_API_KEY`
`apifun`	`https://api.apikey.fun/v1`	`APIFUN_API_KEY`
`ollama`	`http://localhost:11434/v1`	(ninguno)

Todavía se acepta un bloque openrouter de nivel superior heredado (con baseUrl, translationModels, defaultModel, fallbackModel, maxTokens, temperature, requestTimeoutMs) y se migra automáticamente a providers.openrouter (con provider: "openrouter") al cargarlo; defaultModel / fallbackModel se pliegan en translationModels.

Para ver un ejemplo ejecutable que configura varios proveedores en una configuración y cambia entre ellos con -P, consulte examples/multi-provider (openai, anthropic, nvidia y deepseek en el mismo documento).

Por qué usar múltiples modelos: Diferentes proveedores y modelos tienen costos variables y ofrecen diferentes niveles de calidad entre idiomas y locales. Configura translationModels como una cadena de respaldo ordenada (en lugar de un solo modelo) para que la CLI pueda intentar el siguiente modelo si una solicitud falla.

Considere la siguiente lista como una línea base que puede ampliar: si la traducción para una configuración regional específica es deficiente o no tiene éxito, investigue qué modelos admiten ese idioma o script de manera efectiva (consulte los recursos en línea o la documentación de su proveedor) y agregue esos ID de modelo como alternativas adicionales.

Estos ID de modelo coinciden con ai-i18n-tools init [-P <provider>] cuando -P openrouter (el valor predeterminado). Otros preajustes obtienen ID de modelo nativos de init -P <provider>; consulte Proveedores integrados.

Esta lista fue probada para una amplia cobertura de localidades en un gran proyecto de documentación con 36 localidades objetivo; sirve como valor predeterminado práctico, pero no se garantiza que funcione bien en todas las localidades.

Ejemplo translationModels (mismos valores predeterminados que ai-i18n-tools init [-P <provider>]):

Lista predeterminada de alternativas para translationModels

json

"translationModels": [
  "google/gemini-2.5-flash",
  "meta-llama/llama-3.3-70b-instruct",
  "openai/gpt-4o-mini",
  "google/gemma-4-26b-a4b-it",
  "~anthropic/claude-haiku-latest",
  "z-ai/glm-5.2",
  "google/gemini-3.5-flash",
  "~anthropic/claude-sonnet-latest"
  // … add more fallback models as needed
]

uiModels recomendado: Las cadenas de la interfaz de usuario son cortas pero muy visibles; un modelo premium a menudo mejora el tono, los plurales y la coherencia. El uiModels opcional se prueba después de cualquier entrada localeModels coincidente y antes de translationModels (consulte la lista de campos anterior). Ejemplo:

Modelos de interfaz de usuario recomendados para la traducción de la interfaz de usuario

json

"uiModels": [
  "~anthropic/claude-sonnet-latest",
  "z-ai/glm-5.2"
]

localeModels recomendado para idiomas asiáticos: Las configuraciones regionales de japonés, coreano y chino a menudo se benefician de modelos ajustados para esos scripts. Agregue anulaciones por configuración regional que se prueben primero (antes de uiModels / translationModels) cuando la configuración regional de destino coincida:

localeModels recomendados para ja, ko, zh-Hans, zh-Hant

json

"localeModels": [
  { "locale": "ja",      "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "ko",      "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "zh-Hans", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "zh-Hant", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] }
]

Establezca la variable de entorno de la clave API del proveedor activo (consulte la tabla de preajustes) en su entorno o archivo .env.

Antes de cambiar las listas de modelos, ejecute ai-i18n-tools check-models. Para cualquier proveedor, verifica cada ID de modelo configurado (translationModels, uiModels y todas las entradas localeModels) con la lista de modelos en vivo de ese proveedor (GET /models), informa los ID que faltan o que superan expiration_date, enumera los modelos válidos y sale con un valor distinto de cero cuando cualquier ID configurado no es válido. Cuando el proveedor devuelve precios (por ejemplo, OpenRouter), también muestra los precios estimados de entrada/salida (USD por 1M de tokens).

Para comparar los modelos configurados en un trabajo de traducción real, ejecute ai-i18n-tools bench-models. Compara cada ID de modelo único de translationModels, uiModels y localeModels traduciendo una muestra a través de cada uno de forma aislada (en paralelo, limitado por concurrency) e imprime los tokens de entrada/salida por modelo, el tiempo real y el costo en USD, para que pueda sopesar la velocidad frente al precio antes de decidirse por las listas de modelos.

`features`

Campo	Canalización	Descripción
`translateUIStrings`	1	Extraer `t("…")` / `i18n.t("…")` en `strings.json`, luego traducir las entradas y escribir JSON plano por configuración regional (la extracción se ejecuta automáticamente; usar `extract` independiente para actualizar solo el catálogo).
`translateDocs`	2	Traducir `.md` / `.mdx` / `.astro` páginas; shell JSON de Docusaurus cuando `docs[].docusaurusCatalogDir` esté configurado; Nextra `_meta` / diccionario cuando esté configurado; tema VitePress cuando `docsOutput.vitepressThemeCatalog` esté configurado; Fumadocs `meta.json` / catálogo de interfaz de usuario cuando `docsOutput.style` esté `"fumadocs"`.
`translateJson`	3	JSON anidado arbitrario bajo `json[]` (`translate-json`).
`translateSVG`	—	Traducir archivos `.svg` (requiere el bloque `svg` de nivel superior).

Traduce archivos SVG con translate-svg cuando features.translateSVG es verdadero y se configura un bloque superior svg. El comando sync ejecuta ese paso cuando ambos están establecidos (a menos que --no-svg).

`ui`

sourceRoots
Directorios o patrones globales (relativos al directorio de trabajo actual) escaneados en busca de llamadas a t("…"). Admite patrones como src/ o ["src/**/*.ts"].
stringsJson
Ruta al archivo del catálogo maestro. Actualizado por extract.
flatOutputDir
Directorio donde se escriben los archivos JSON por configuración regional (de.json, etc.).
uiExtractor.funcNames (o el obsoleto reactExtractor.funcNames)
Nombres de funciones adicionales para escanear (predeterminado: ["t", "i18n.t"]).
uiExtractor.extensions (o el obsoleto reactExtractor.extensions)
Extensiones de archivo a incluir (predeterminado: [".js", ".jsx", ".ts", ".tsx"]). Agregue .astro para el frontmatter y las expresiones de plantilla de Astro.
uiExtractor.includePackageDescription (o el obsoleto reactExtractor.includePackageDescription)
Cuando true (predeterminado), extract también incluye package.json description como una cadena de interfaz de usuario cuando está presente.
uiExtractor.packageJsonPath (o el obsoleto reactExtractor.packageJsonPath)
Ruta personalizada al archivo package.json utilizado para esa extracción de descripción opcional.
uiExtractor.includeUiLanguageEnglishNames (o el obsoleto reactExtractor.includeUiLanguageEnglishNames)

Cuando true (predeterminado false), extract también agrega cada englishName del catálogo maestro de ui-languages incluido (construido a partir de sourceLocale + targetLocales) a strings.json cuando aún no está presente en el escaneo de origen (mismas claves hash). No lee languagesManifestPath.

`cacheDir`

cacheDir Directorio de caché de SQLite (compartido por todos los bloques docs). Predeterminado .translation-cache. Reutilizar en varias ejecuciones. Si está migrando desde una caché de traducción de documentos personalizada, archívela o elimínela; cacheDir crea su propia base de datos SQLite y no es compatible con otros esquemas.

Mejor práctica para exclusiones en git:

Excluya el contenido de la carpeta de caché de traducción (por ejemplo, usando .gitignore o .git/info/exclude) para evitar confirmar artefactos temporales de caché.
Mantenga cache.db (no eliminarlo habitualmente), ya que conservar la caché SQLite evita volver a traducir segmentos sin cambios. Esto ahorra tiempo de ejecución y costos de API al actualizar o modificar software que usa ai-i18n-tools.
Excluya archivos temporales y de registro para evitar confirmar archivos de respaldo y depuración.

Ejemplo:

gitignore

# Translation cache directory
.translation-cache/*

# Keep SQLite cache for reuse
!.translation-cache/cache.db

# Temporary and log files
*.tmp
*.log

`docs`

Matriz de bloques de la canalización de documentación. translate-docs y la fase de documentos de sync procesan cada bloque en orden. Las claves heredadas aún se aceptan en el momento de la carga y se reescriben cuando el archivo de configuración es editable; prefiera los nombres actuales en las nuevas configuraciones.

Clave heredada	Clave/comportamiento actual
`documentations`	`docs`
`markdownOutput`	`docs[].docsOutput`
`jsonSource`	`docs[].docusaurusCatalogDir`
`openrouter` de nivel superior	`providers.openrouter` + `provider: "openrouter"`
`features.translateMarkdown`	`features.translateDocs`
`features.translateJSON`	eliminado (use `docs[].docusaurusCatalogDir` o `json[]`)
`features.extractUIStrings`	eliminado (`extract` se ejecuta antes de la traducción de la interfaz de usuario)
`glossary.uiGlossaryFromStringsJson`	`glossary.uiGlossary`
`ui.reactExtractor`	`ui.uiExtractor` (el alias aún se acepta)
`svg.svgExtractor.forceLowercase`	`svg.forceLowercase`

Fuentes de contenido

description Nota opcional legible para humanos sobre este bloque (no se usa para traducción). Se antepone en el encabezado translate-docs 🌐 cuando se establece; también se muestra en los encabezados de sección de status.
contentPaths Cuerpos de páginas en Markdown/MDX y plantillas .astro a traducir (translate-docs analiza estos en busca de .md, .mdx y .astro). Admite rutas de directorio o patrones globales (por ejemplo, "docs/**/*.md", "guides/*.mdx", "src/pages/index.astro"). De ahí proviene la documentación localizada.
sourceFiles Alias opcional que se fusiona en contentPaths en tiempo de carga.
targetLocales Subconjunto opcional de configuraciones regionales solo para este bloque (en caso contrario, se usa la raíz targetLocales). Las configuraciones regionales efectivas de la documentación son la unión entre todos los bloques.
docusaurusCatalogDir Opcional. Directorio de origen para los catálogos de etiquetas JSON de Docusaurus para este bloque (por ejemplo, "i18n/en" de docusaurus write-translations). Los cuerpos de las páginas siempre provienen de contentPaths; docusaurusCatalogDir solo proporciona JSON de shell/UI, no MDX.
nextraMetaGlob Glob(s) opcional(es) para _meta.ts / _meta.tsx / _meta.js de Nextra bajo docsRoot. Cuando docsOutput.style es "nextra" y esto se omite, todos los archivos _meta bajo docsRoot se recopilan automáticamente.
nextraMetaTranslatableKeys Nombres de propiedades opcionales cuyos valores de cadena se traducen en objetos _meta de Nextra (predeterminado: title, display, breadcrumb).
nextraDictionaryPath Módulo de diccionario de tema de Nextra en inglés opcional (por ejemplo, "app/_dictionaries/en.ts"). Traducido a {dir}/{locale}.ts durante translate-docs.
nextraDictionaryOutputTemplate Plantilla de salida opcional para módulos de diccionario de configuración regional (predeterminado: {dir}/{locale}.ts en relación con el directorio del diccionario).

Estructura de salida

outputDir Directorio raíz para la salida traducida de este bloque.
docsOutput.style"nested" (predeterminado), "flat", "doc-system", o alias "docusaurus" / "astro-starlight" / "vitepress" / "nextra".
docsOutput.localeSubpath Segmento de ruta entre {locale}/ y {relativeToDocsRoot} para doc-system (obligatorio cuando se usa style: "doc-system" directamente; preestablecido cuando se usa un alias). Use "" para carpetas de configuración regional estilo Starlight.
docsOutput.docsRoot Raíz de documentos de origen para el diseño de Docusaurus (por ejemplo, "docs"). Predeterminado "docs" cuando se omite.
docsOutput.pathTemplate Ruta de salida de markdown personalizada. Marcadores de posición: "{outputDir}", "{locale}", "{LOCALE}", "{llocale}", "{relPath}", "{stem}", "{basename}", "{extension}", "{docsRoot}", "{relativeToDocsRoot}".
docsOutput.jsonPathTemplate Ruta de salida JSON personalizada para archivos de etiquetas. Admite los mismos marcadores de posición que pathTemplate.
docsOutput.localePathLowercase Cuando true, los diseños de salida integrados (nested, flat, doc-system sin pathTemplate) usan segmentos de configuración regional en minúsculas en las rutas. Predeterminado false; astro-starlight y doc-system con localeSubpath vacío se establecen de forma predeterminada en true en la carga de configuración.
docsOutput.flatPreserveRelativeDir Cuando docsOutput.style = "flat", mantenga los subdirectorios de origen para que los archivos con el mismo nombre base no colisionen. Predeterminado false.
docsOutput.rewriteRelativeLinks Reescribe los enlaces relativos después de la traducción (habilitado automáticamente cuando docsOutput.style = "flat" y no hay pathTemplate personalizado).
docsOutput.linkRewriteDocsRoot Raíz del repositorio utilizada al calcular los prefijos de reescritura de enlaces planos. Normalmente, déjelo como "." a menos que su documentación traducida se encuentre bajo una raíz de proyecto diferente.
docsOutput.rewriteVitepressLinks Cuando true, ejecute el normalizador de enlaces de VitePress después de la traducción. Por defecto, está habilitado cuando docsOutput.style es "vitepress". Úselo con cualquier diseño doc-system donde las carpetas de localización se encuentren junto al inglés bajo docsRoot. Reescribe las rutas docs/guide/… de estilo README a rutas del sitio (/guide/…) y enlaces ../guide/… relativos a la localización. Para enlaces a archivos del repositorio fuera del árbol de VitePress (LICENSE, examples/), use URL completas en la fuente en inglés — consulte Integración de VitePress — README como la página de inicio de la documentación.
docsOutput.rewriteNextraLinks Cuando true, ejecute el normalizador de enlaces de Nextra después de la traducción. Por defecto, está habilitado cuando docsOutput.style es "nextra". Reescribe las rutas content/en/… y .mdx relativas a rutas de sitio neutrales a la localización (/guide/…) para Next.js i18n. Consulte Integración de Nextra — Convenciones de enlaces.
docsOutput.fumadocsParser"dot" (predeterminado) o "dir". Dot escribe stem.{locale}.mdx junto a las fuentes en inglés; dir escribe carpetas de localización como Nextra. Consulte Integración de Fumadocs — Diseño de página.
docsOutput.rewriteFumadocsLinks Cuando true, ejecute el normalizador de enlaces de Fumadocs después de la traducción. Por defecto, está habilitado cuando docsOutput.style es "fumadocs". Reescribe las rutas de contenido y los enlaces .mdx relativos a las rutas /docs/….
docsOutput.fumadocsUiCatalog Opcional. Catálogo de anulación de la interfaz de usuario de Fumadocs y traducción dentro de translate-docs. Campos: sourcePath (por ejemplo, lib/layout.shared.ts), catalogPath (JSON en inglés generado), outputPathTemplate opcional (predeterminado: ui.{locale}.json junto a catalogPath).
docs[].fumadocsMetaGlob Glob(s) opcional(es) para la colección meta.json cuando docsOutput.style es "fumadocs". Predeterminado: meta.json recursivo bajo docsOutput.docsRoot.
docs[].fumadocsMetaTranslatableKeys Nombres de propiedades cuyos valores de cadena se traducen en Fumadocs meta.json (predeterminado: title, description).
docsOutput.vitepressThemeCatalog Opcional. Catálogo de inicio de tema/navegación/barra lateral de VitePress + traducción dentro de translate-docs. Campos: configPath (configuración de VitePress con cadenas de tema), catalogPath (JSON anidado en inglés generado), outputPathTemplate opcional (predeterminado: theme.{locale}.json junto a catalogPath).

Posprocesado

docsOutput.postProcessing Transformaciones opcionales en el cuerpo de markdown traducido (las claves YAML y los valores de metadatos no textuales se conservan). Se ejecuta después del reensamblaje de segmentos y la reescritura de enlaces (plano o VitePress), y antes de addFrontmatter.
docsOutput.postProcessing.regexAdjustments Lista ordenada de { "description"?, "search", "replace" }. search es un patrón de expresión regular (la cadena simple usa la bandera g, o /pattern/flags). replace admite marcadores de posición como ${translatedLocale}, ${sourceLocale}, ${sourceFullPath}, ${translatedFullPath}, ${sourceFilename}, ${translatedFilename}, ${sourceBasedir}, ${translatedBasedir}.
docsOutput.postProcessing.languageListBlock{ "start", "end", "separator", "label"? } — regenera una fila de enlaces delimitada "leer en otros idiomas" en markdown de origen y traducido. Requiere languagesManifestPath (o un manifiesto en ui.flatOutputDir/ui-languages.json) para etiquetas endónimas cuando label: "local".

Comportamiento y metadatos

translateFrontmatterFields Al mismo nivel que docsOutput (por bloque docs[]). true predeterminado: traducir el texto YAML de cara al usuario para Starlight/Docusaurus (etiquetas title, description, sidebar.label, sidebar_label, keywords, hero.title, hero.tagline, hero.image.alt, hero.actions[].text, pagination_label, prev/next). Establezca false para mantener todo el bloque de metadatos sin cambios; pase una matriz de cadenas para restringir a rutas de puntos específicas.
segmentSplitting Al mismo nivel que docsOutput (por bloque docs[]). Segmentos opcionales más granulares para la extracción de translate-docs: { "enabled", "maxCharsPerSegment"?, "splitPipeTables"?, "splitDenseParagraphs"?, "maxLinesPerParagraphChunk"?, "splitLongLists"?, "maxListItemsPerChunk"?, "qualityRetrySplit"?, "maxQualityRetrySplitDepth"? }. Cuando enabled es true (predeterminado cuando se omite segmentSplitting), los párrafos densos, las tablas de tuberías GFM (el primer fragmento incluye el encabezado, el separador y la primera fila de datos) y las listas largas se dividen; las subpartes se unen con saltos de línea únicos (tightJoinPrevious). Establezca "enabled": false para usar un segmento por bloque de cuerpo delimitado por línea en blanco solamente. Cuando qualityRetrySplit es true (predeterminado), los segmentos de markdown que fallan la validación AST después de que todos los modelos se agotan se dividen progresivamente y se reintentan desde el primer modelo; maxQualityRetrySplitDepth (3 predeterminado) limita las divisiones recursivas.
warnMarkdownSourceIssues Cuando true (predeterminado cuando se omite), cada ejecución de translate-docs vuelve a escanear los segmentos de markdown en busca de delimitadores riesgosos / código en línea sin cerrar, imprime advertencias en la terminal y reemplaza las filas markdown_source_issues para la ruta de archivo de caché de ese archivo. Establezca false para omitir advertencias y actualizaciones de SQLite para este bloque.
addFrontmatter Cuando true (predeterminado cuando se omite), los archivos markdown traducidos incluyen las claves YAML: translation_last_updated, source_file_mtime, source_file_hash, translation_language, source_file_path, y cuando al menos un segmento tiene metadatos del modelo, translation_models (lista ordenada de IDs de modelo del proveedor activo). Establezca en false para omitir.
emphasisPlaceholders Por bloque docs[]. Cuando true, enmascara los delimitadores de énfasis de markdown como marcadores de posición antes de la traducción. Por defecto, true para configuraciones regionales CJK (zh, ja, ko) y para las configuraciones regionales enumeradas en rtlLocales; de lo contrario, por defecto, false. Se puede anular mediante CLI --emphasis-placeholders / --no-emphasis-placeholders.
rtlLocales Matriz opcional de códigos BCP-47 tratados como RTL para los valores predeterminados de marcador de posición de énfasis (fusionados con la detección de RTL incorporada).

protectAttributes Opcional. Nombres adicionales de atributos JSX/HTML cuyos valores de cadena entre comillas no deben enviarse al traductor. Se fusionan con los valores predeterminados integrados (class, id, style, src, href, type, data-*, la mayoría de aria-*, etc.). No distingue entre mayúsculas y minúsculas. Se aplica a:
.astro extracción de parseo y reemplazo (etiquetas HTML estáticas y literales de cadena después de attr= dentro de bloques {expression}).
- Extracción de marcadores de posición MDX durante la traducción de segmentos markdown/Astro (label, tooltip, y aria-label en etiquetas JSX en mayúsculas, además de TabItem value cuando sea aplicable).

Ejemplo: "protectAttributes": ["variant", "size"] mantiene variant="primary" dentro de {items.map(...)} sin cambios en todos los idiomas.

También puedes incluir atributos normalmente traducibles (por ejemplo "title" o "aria-label") cuando desees que esos valores se copien textualmente del inglés.

protectKeys Opcional. Nombres adicionales de propiedades de objeto cuyos valores entre comillas no deben traducirse dentro de bloques de plantilla {expression} y literales de objeto MDX (por ejemplo label: dentro de <Tabs values={[ … ]}>). Se combina con los valores predeterminados integrados (class, key, id, href, src, etc.). No distingue entre mayúsculas y minúsculas.

Ejemplo: "protectKeys": ["slug", "code"] omite { slug: 'getting-started', title: 'Getting started' } → solo se traduce title cuando slug está protegido.

Ejemplo (docsOutput.style = "flat" — rutas de capturas de pantalla + contenedor opcional con lista de idiomas):

Ejemplo de postprocesamiento con diseño plano (capturas de pantalla + bloque de lista de idiomas)

json

"docsOutput": {
  "style": "flat",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders",
        "search": "images/screenshots/[^/]+/",
        "replace": "images/screenshots/${translatedLocale}/"
      }
    ],
    "languageListBlock": {
      "start": "<small id=\"lang-list\">",
      "end": "</small>",
      "separator": " · ",
      "label": "local"
    }
  }
}

`json`

Matriz de nivel superior de canalizaciones de traducción JSON anidadas. Se usa solo cuando features.translateJson es verdadero (translate-json o la etapa JSON de sync). Consulta JSON.

Campo	Descripción
`description`	Nota opcional para CLI / `status` (no se traduce).
`contentPaths`	Archivos, directorios o patrones `.json` de origen bajo la raíz del proyecto.
`outputPathTemplate`	Ruta de salida requerida por configuración regional de destino. Marcadores de posición: `{locale}`, `{LOCALE}`, `{llocale}`, `{stem}`, `{basename}`, `{extension}`, `{relativeToSourceRoot}`.
`targetLocales`	Subconjunto opcional para este bloque; en caso contrario, raíz `targetLocales`.
`keyPolicy.mode`	`allowlist`, `denylist` o `both`.
`keyPolicy.translateKeys`	Rutas con notación de puntos o patrones glob a incluir cuando el modo es `allowlist` o `both`.
`keyPolicy.skipKeys`	Rutas con notación de puntos o patrones glob a excluir (la lista de denegación predeterminada incluye `id`, `slug`, `href`, `url`, `key`, `code`).

`svg`

Rutas y estructura de nivel superior para archivos SVG. La traducción solo se ejecuta cuando features.translateSVG es verdadero (mediante translate-svg o la etapa SVG de sync).

Campo	Descripción
`sourcePath`	Uno o más directorios o patrones globales (por ejemplo, `"images/.svg"`, `"/icons/.svg"`). Los patrones se resuelven respecto a la raíz del proyecto y se escanean recursivamente en busca de archivos `.svg`.
`outputDir`	Directorio raíz para la salida SVG traducida.
`style`	`"flat"` o `"nested"` cuando `pathTemplate` no está definido.
`pathTemplate`	Ruta de salida personalizada para SVG. Marcadores de posición: `"{outputDir}"`, `"{locale}"`, `"{LOCALE}"`, `"{llocale}"`, `"{relPath}"`, `"{stem}"`, `"{basename}"`, `"{extension}"`, `"{relativeToSourceRoot}"`.
`localePathLowercase`	Cuando es `true`, los diseños integrados de SVG `flat` / `nested` usan segmentos de idioma en minúsculas. Los valores personalizados de `pathTemplate` no cambian; use `{llocale}` para segmentos en minúsculas.
`forceLowercase`	Texto traducido en minúsculas durante la reensamblaje SVG. Útil para diseños que dependen de etiquetas completamente en minúsculas.

`glossary`

Campo	Descripción
`uiGlossary`	Ruta a `strings.json` - crea automáticamente un glosario a partir de traducciones existentes.
`userGlossary`	Ruta a un archivo CSV con columnas `Original language string` (o `en`), `locale`, `Translation` - una fila por término fuente y configuración regional objetivo (`locale` puede ser `*` para todos los destinos).
`autoAddUserEditedToGlossary`	Cuando `true`, las ediciones del panel de control a las cadenas de la interfaz de usuario se pueden añadir automáticamente al glosario del usuario.

Genere un archivo CSV de glosario vacío:

bash

ai-i18n-tools glossary-generate

Cadenas de interfaz de usuario

Documentos

Integraciones

Imágenes y capturas de pantalla

Traducción de SVG

Panel de traducción

Referencia de configuración

`sourceLocale`

`targetLocales`

`uiLanguage` (opcional)

`languagesManifestPath` (opcional)

`concurrency` (opcional)

`batchConcurrency` (opcional)

`fileConcurrency` (opcional)

`batchSize` / `maxBatchChars` (opcional)

`provider` y `providers`

`features`

`ui`

`cacheDir`

Mejor práctica para exclusiones en git:

`docs`

`json`

`svg`

`glossary`

Cadenas de interfaz de usuario

Documentos

Referencia de configuración ​

sourceLocale ​

targetLocales ​

uiLanguage (opcional) ​

languagesManifestPath (opcional) ​

concurrency (opcional) ​

batchConcurrency (opcional) ​

fileConcurrency (opcional) ​

batchSize / maxBatchChars (opcional) ​

provider y providers ​

features ​

ui ​

cacheDir ​

Mejor práctica para exclusiones en git: ​

docs ​

json ​

svg ​

glossary ​

Referencia de configuración

`sourceLocale`

`targetLocales`

`uiLanguage` (opcional)

`languagesManifestPath` (opcional)

`concurrency` (opcional)

`batchConcurrency` (opcional)

`fileConcurrency` (opcional)

`batchSize` / `maxBatchChars` (opcional)

`provider` y `providers`

`features`

`ui`

`cacheDir`

Mejor práctica para exclusiones en git:

`docs`

`json`

`svg`

`glossary`