Skip to content

Referencia de configuración ​

sourceLocale ​

Código BCP-47 para el idioma de origen (por ejemplo "en-GB", "pt-BR" o "ja"). Cualquier idioma es válido. El inglés aparece en los ejemplos porque muchos proyectos comienzan ahí. No se genera ningún archivo de traducción para esta configuración regional: la propia cadena clave es el texto de origen.

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. El selector de idioma de la documentación lee esta ruta. Si se omite, toma por defecto el manifiesto del primer bloque de UI: el languagesManifestPath de ese bloque, o {flatOutputDir}/ui-languages.json. Cada bloque de UI puede establecer su propio languagesManifestPath; el bloque 0 utiliza esta ruta raíz cuando el bloque omite la suya.

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 de destino traducidas al mismo tiempo (translate-ui, translate-docs, translate-svg y los pasos correspondientes dentro de sync). Si se omite, la CLI usa 4 para la traducción de la interfaz de usuario y 3 para la traducción de la documentación (valores predeterminados integrados). Se puede anular por ejecución con -j / --concurrency.


batchConcurrency (opcional) ​

translate-docs, translate-svg y translate-json (y los pasos correspondientes dentro de sync): número máximo de solicitudes por lotes de LLM en paralelo por archivo (cada lote puede contener muchos segmentos). El valor predeterminado es 4 si se omite. No se aplica a translate-ui; en su lugar, utilice uiBatchConcurrency. Se anula con -b / --batch-concurrency.


uiBatchConcurrency (opcional) ​

translate-ui, sync-ui, y el paso de UI de sync: solicitudes por lotes LLM paralelas máximas dentro de una sola configuración regional (fragmentos de cadena simple de 50, luego grupos plurales). El valor predeterminado es 2 cuando se omite. Independiente de concurrency (configuraciones regionales de destino paralelas) y batchConcurrency (documentos/JSON/SVG). No hay un indicador de CLI; configúrelo en la configuración o pase uiBatchConcurrency a runTranslateUI programático.

Ejemplo:

json
{
  "uiBatchConcurrency": 2
}

Con la concurrencia de configuración regional predeterminada de 4, esto es hasta 8 llamadas a la API de IU en curso. Aumente este valor al traducir una configuración regional grande (-l de); manténgalo bajo si el proveedor aplica límites de velocidad.


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).


requestTimeout / requestTimeoutMs (opcional) ​

Tiempo máximo de espera para cada solicitud de LLM, para cada proveedor. requestTimeout son segundos enteros; requestTimeoutMs son milisegundos. Predeterminado: 120 segundos cuando ambos se omiten. Establezca solo uno de los dos. Un proveedor que establece cualquiera de los dos campos utiliza ese valor en su lugar, solo para ese proveedor.


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 ascendentes simples, 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 global predeterminada para cada pipeline 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 Pase 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 todos los pipelines 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 del pipeline (uiModels para la interfaz de usuario) y translationModels. Las claves de configuración regional normalizadas duplicadas se rechazan al cargar la configuración.
  • baseUrl URL base compatible con OpenAI. Anula la URL base preestablecida; es 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.
  • requestTimeout Tiempo máximo en segundos para esperar cada solicitud a este proveedor. Anula el requestTimeout / requestTimeoutMs de nivel superior. Cuando ni este proveedor ni la configuración de nivel superior establecen un tiempo de espera, el valor predeterminado es 120 segundos. Establezca solo uno de requestTimeout y requestTimeoutMs en el mismo objeto.
  • requestTimeoutMs Tiempo máximo en milisegundos para esperar cada solicitud a este proveedor. Anula el requestTimeout / requestTimeoutMs de nivel superior. Cuando ni este proveedor ni la configuración de nivel superior establecen un tiempo de espera, el valor predeterminado es 120000 (120 segundos). Establezca solo uno de requestTimeout y requestTimeoutMs en el mismo objeto.
  • pricing (opcional) USD por 1M de tokens para todo el proveedor: { "inputPerMTokens": 0.15, "outputPerMTokens": 0.6 }. Cuando una llamada facturada no tiene un usage.cost informado por el proveedor (la mayoría de los proveedores, excepto OpenRouter y Cheaper Inference), esta tarifa se aplica a los tokens de entrada y salida de esa llamada. El importe se incluye en el resumen de la traducción y se almacena en la fila api_calls.

El origen del coste se resuelve en este orden:

  1. una entrada modelPricing coincidente (anula este valor predeterminado del proveedor);
  2. un coste informado por el proveedor (nunca se reemplaza);
  3. esta tarifa pricing;
  4. el precio de lista de models.dev para ese ID de modelo (USD de entrada y salida por 1M de tokens).

Las filas que se almacenaron sin un coste aún se pueden estimar más tarde mediante usage y Uso y costes. Si ninguna de esas fuentes se aplica, el coste permanece desconocido (—), nunca $0.00.

  • modelPricing (opcional) USD por 1M de tokens por modelo: { "<model-id>": { "inputPerMTokens": 2.5, "outputPerMTokens": 10 } }. Anula pricing para ese ID de modelo. Se aplica en el momento de la llamada cuando el proveedor omitió usage.cost, y se almacena con la llamada.
  • zeroDataRetention (opcional, solo providers.cheaperinference) Cuando true, las solicitudes de chat envían "zdr": true y list-models, check-models y suggest-models cargan GET /v1/models?zdr=true. Omitido significa desactivado. Consulte Retención de datos cero.

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

ProveedorURL baseVariable de entorno de clave de API
alibabahttps://dashscope-intl.aliyuncs.com/compatible-mode/v1ALIBABA_API_KEY
anthropichttps://api.anthropic.com/v1ANTHROPIC_API_KEY
apikeyfanhttps://api.apikey.fan/v1APIKEYFAN_API_KEY
cerebrashttps://api.cerebras.ai/v1CEREBRAS_API_KEY
cheaperinferencehttps://api.cheaperinference.com/v1CHEAPERINFERENCE_API_KEY
deepseekhttps://api.deepseek.comDEEPSEEK_API_KEY
geminihttps://generativelanguage.googleapis.com/v1beta/openaiGOOGLE_API_KEY
groqhttps://api.groq.com/openai/v1GROQ_API_KEY
mistralhttps://api.mistral.ai/v1MISTRAL_API_KEY
nvidiahttps://integrate.api.nvidia.com/v1NVIDIA_API_KEY
ollamahttp://localhost:11434/v1(ninguno)
openaihttps://api.openai.com/v1OPENAI_API_KEY
openrouterhttps://openrouter.ai/api/v1OPENROUTER_API_KEY
xaihttps://api.x.ai/v1XAI_API_KEY

El preajuste apifun se renombró a apikeyfan. Actualice las claves provider y providers en las configuraciones existentes; APIFUN_API_KEY sigue siendo un alias para APIKEYFAN_API_KEY.

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

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

Por qué usar varios modelos: los distintos proveedores y modelos tienen costes variables y ofrecen diferentes niveles de calidad según el idioma y la configuración regional. Configure translationModels como una cadena de respaldo ordenada para que la CLI pueda probar con el siguiente modelo si una solicitud falla. La guía para crear esa lista es Modelos de IA.

Considere la lista siguiente como un punto de partida. Reemplácela con la clasificación de la comparativa de Modelos de IA. Si la traducción para una configuración regional específica sigue siendo deficiente, añada una entrada localeModels para ese idioma o sistema de escritura, o añada más ID del catálogo del proveedor.

Estos IDs de modelo son los que ai-i18n-tools init -P openrouter escribe. Otros preajustes obtienen IDs de modelo nativos de init -P <provider> — consulta 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 (lista de OpenRouter de ai-i18n-tools init -P openrouter):

Lista de translationModels de OpenRouter
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 ​

CampoCanalizaciónDescripción
translateUIStrings1Extraer 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).
translateDocs2Traducir páginas .md / .mdx / .astro / .html / .htm; JSON del shell de Docusaurus cuando docs[].docusaurusCatalogDir está configurado; _meta / diccionario de Nextra cuando está configurado; tema de VitePress cuando docsOutput.vitepressThemeCatalog está configurado; meta.json / catálogo de UI de Fumadocs cuando docsOutput.style es "fumadocs".
translateJson3JSON anidado arbitrario bajo json[] (translate-json).
translateSVG—Traducir archivos .svg (requiere el bloque svg de nivel superior).

Cada indicador tiene un valor predeterminado de true cuando se omite la clave. El comportamiento es:

  • Un true omitido sin nada que traducir se omite: ningún bloque de interfaz de usuario tiene sourceRoots, ningún bloque de documentos tiene contentPaths o docusaurusCatalogDir, json[] no tiene contentPaths o svg no está configurado.
  • Escribir el indicador como true cuando ese pipeline no tiene trabajo es un error de configuración.
  • Escribir false desactiva ese pipeline para sync incluso cuando existen fuentes.
  • --no-ui, --no-docs, --no-json y --no-svg omiten el paso para una ejecución.

Traducir archivos SVG con translate-svg cuando features.translateSVG es verdadero y hay un bloque svg de nivel superior configurado. El comando sync ejecuta ese paso cuando el indicador está activado y svg está definido (a menos que --no-svg).


ui ​

Un objeto de catálogo, o un array de bloques de catálogo (la misma idea que docs[]). Se acepta un único objeto al cargar y se envuelve en un array de un solo elemento; el archivo en el disco no se reescribe. Después del análisis, config.ui es siempre un array.

extract, translate-ui, sync-ui, la fase de UI de sync, proofread-ui, export-ui-xliff, generate-ui-languages y purge-locale recorren cada bloque que tiene sourceRoots. Pase --ui-block con un índice basado en cero, el description del bloque, o su ruta stringsJson para ejecutar un solo bloque. status y statistics listan cada bloque que tiene fuentes o un catálogo existente. El Panel de Traducción lista cada uno de estos catálogos y muestra un selector cuando hay más de uno.

Las rutas resueltas de stringsJson, flatOutputDir y de manifiesto deben ser únicas en todos los bloques. Los valores de description deben ser únicos cuando se definen, porque --ui-block los coincide exactamente.

  • description Nota opcional para las personas que leen la configuración (no se envía al modelo). Se muestra como ui[i] — description en los encabezados de comandos, status, statistics y el panel.
  • sourceRoots Directorios o patrones glob (relativos a cwd) escaneados en busca de llamadas a t("…"). Admite patrones como src/ o ["src/**/*.ts"]. Se omite un bloque con una lista vacía a menos que --ui-block lo nombre, lo cual es un error.
  • stringsJson Ruta al archivo de catálogo maestro de este bloque. Actualizado por extract.
  • flatOutputDir Directorio donde se escriben los archivos JSON por configuración regional de este bloque (de.json, etc.).
  • flatOutput Cuando true (el valor predeterminado), translate-ui escribe un archivo JSON plano por cada configuración regional. Establezca false para emitir solo gettext o resx. Un bloque con flatOutput: false debe establecer gettext o resx.
  • resx Salida opcional de .resx de .NET. outputDir (valor predeterminado Resources) y baseName (valor predeterminado SharedResource) escriben {baseName}.resx más {baseName}.{culture}.resx. writeNeutral (valor predeterminado true) coloca el texto fuente en el archivo neutro para que ResourceManager pueda recurrir. localeFormat es bcp47 (valor predeterminado, pt-BR) o posix (pt_BR). ingestExistingResx (valor predeterminado true) lee satélites durante extract. neutralFile asigna claves con nombre heredadas como LoginButton a través del valor neutro. Las claves de contexto usan U+2404. Las formas plurales son entradas separadas llamadas {singular}[{form}]. Un bloque con flatOutput: false debe establecer gettext o resx.
  • gettext Salida opcional de GNU gettext para este bloque. outputDir (valor predeterminado ./locales) recibe <locale>/LC_MESSAGES/<domain>.po y, cuando compileMo es true (el valor predeterminado), el .mo coincidente. domain toma por defecto messages. potPath es el catálogo de plantillas. ingestExistingPo (valor predeterminado true) rellena las ranuras strings.json vacías con valores msgstr no difusos durante extract y no reemplaza una traducción no vacía o editada por el usuario. localeFormat es posix (valor predeterminado, pt_BR) o bcp47 (pt-BR). Las filas contextuales usan el separador \u0004 de gettext. La misma cadena de idioma de origen en dos contextos no comparte un ID de catálogo.
  • targetLocales Lista opcional de configuraciones regionales para este bloque. Cuando se omite o está vacía, el bloque usa la raíz targetLocales.
  • languagesManifestPath Ruta opcional donde extract y generate-ui-languages escriben el ui-languages.json de este bloque. Cuando se omite, el bloque 0 usa la raíz languagesManifestPath (que a su vez toma por defecto el {flatOutputDir}/ui-languages.json de este bloque). Los bloques posteriores usan por defecto {flatOutputDir}/ui-languages.json.
  • uiGlossary Cuando true (el valor predeterminado), el strings.json de este bloque es una fuente de sugerencias de glosario para translate-docs, translate-json y translate-svg. translate-ui, proofread-ui y el linting de código fuente usan solo glossary.userGlossary. Establezca false para mantener un catálogo fuera de esas sugerencias (por ejemplo, un catálogo de cadenas de CLI que no debería guiar la documentación).
  • uiExtractor.funcNames (o el heredado reactExtractor.funcNames) Nombres de funciones adicionales para escanear (valor predeterminado: ["t", "i18n.t"]).
  • uiExtractor.extensions (o el heredado reactExtractor.extensions) Extensiones de archivo a incluir (valor predeterminado: [".js", ".jsx", ".ts", ".tsx"]). Agregue .astro para el frontmatter de Astro y las expresiones de plantilla.
  • uiExtractor.includePackageDescription (o el heredado reactExtractor.includePackageDescription) Cuando true (valor predeterminado), extract también incluye package.json description como una cadena de interfaz de usuario cuando está presente. Establezca false en bloques adicionales para que la misma descripción no se extraiga en cada catálogo.
  • uiExtractor.packageJsonPath (o el heredado reactExtractor.packageJsonPath) Ruta personalizada al archivo package.json utilizado para esa extracción opcional de descripción.
  • uiExtractor.includeUiLanguageEnglishNames (o el heredado reactExtractor.includeUiLanguageEnglishNames)

Cuando true (valor predeterminado false), extract también añade cada englishName del catálogo maestro de idiomas de IU incluido (creado a partir de sourceLocale + el targetLocales efectivo del bloque) a strings.json si no está ya presente en el escaneo de origen (mismas claves hash). No lee languagesManifestPath.

  • uiExtractor.placeholderStyledefault (mustache, campos de formato de Python y printf) o dotnet (solo {0}, {0,-10}, {0:format}). En el estilo dotnet, un signo de porcentaje es texto literal y las llaves dobles son llaves literales. La plantilla ui-dotnet establece dotnet.
  • uiExtractor.exclude Patrones Minimatch, relativos a la raíz del proyecto, descartados después del escaneo. bin, obj, .vs, TestResults y packages ya se omiten por nombre de directorio. Las plantillas ui-dotnet y ui-dotnet-resx excluyen **/Tests/**, **/*.Tests/** y **/TrExtension.cs.

glossary.uiGlossary y glossary.uiGlossaryFromStringsJson ya no se aceptan. La carga de la configuración falla y el error explica el reemplazo: elimine la clave. Las sugerencias ahora provienen del indicador uiGlossary de cada bloque (predeterminado true).


cacheDir ​

  • cacheDir Directorio de caché de SQLite (compartido por todos los bloques docs). Predeterminado .translation-cache. Reutilizar entre ejecuciones. Si está migrando desde una caché de traducción de documentación personalizada, archívela o elimínela; cacheDir crea su propia base de datos SQLite y no es compatible con otros esquemas. suggest-models también almacena agregados de referencia en <cacheDir>/benchmark-scores.json. Ese archivo es una caché, como el resto del directorio, y no forma parte del paquete publicado.

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 la confirmación de artefactos de caché temporales.
  • Conserve cache.db (no lo elimine rutinariamente), ya que preservar la caché de SQLite evita volver a traducir segmentos sin cambios. Esto ahorra costos tanto de tiempo de ejecución como de API al actualizar o modificar software que utiliza ai-i18n-tools.
  • Excluya los archivos de entorno y los archivos temporales para que los secretos y las copias de seguridad no se confirmen.

Ejemplo:

init escribe este bloque para el cacheDir predeterminado. Cuando cacheDir es diferente, las dos líneas de caché usan ese directorio, por ejemplo, .i18n-cache/* y !.i18n-cache/cache.db.

gitignore
# Cache
.translation-cache/*
!.translation-cache/cache.db
benchmark-scores.json

# Environment
.env
.env.local
.env.*.local

# Temporary files
*.tmp
*.backup.*

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 heredadaClave/comportamiento actual
documentationsdocs
markdownOutputdocs[].docsOutput
jsonSourcedocs[].docusaurusCatalogDir
openrouter de nivel superiorproviders.openrouter + provider: "openrouter"
features.translateMarkdownfeatures.translateDocs
features.translateJSONeliminado (use docs[].docusaurusCatalogDir o json[])
features.extractUIStringseliminado (extract se ejecuta antes de la traducción de la interfaz de usuario)
glossary.uiGlossary y glossary.uiGlossaryFromStringsJsoneliminados; la carga de la configuración falla. Use ui[].uiGlossary (booleano, valor predeterminado true)
ui.reactExtractorui.uiExtractor (el alias aún se acepta)
svg.svgExtractor.forceLowercasesvg.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).

docsOutput ​

Diseño de salida para este bloque.

  • 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 Reescribir enlaces relativos después de la traducción (habilitado automáticamente cuando docsOutput.style = "flat" y sin 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. Se habilita por defecto cuando docsOutput.style es "vitepress". Úselo con cualquier diseño doc-system donde las carpetas de idioma se encuentren junto a los archivos del idioma de origen bajo docsRoot. El idioma de origen es sourceLocale y puede ser cualquier idioma. Reescribe las rutas docs/guide/… de estilo README a rutas del sitio (/guide/…) y enlaces ../guide/… relativos al idioma. Para enlaces a archivos del repositorio fuera del árbol de VitePress (LICENSE, examples/), use URL completas en los archivos del idioma de origen — consulte Integración de VitePress — README como 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. Se habilita por defecto cuando docsOutput.style es "nextra". Reescribe las rutas content/en/… y .mdx relativas a rutas del sitio neutrales al idioma (/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 los archivos del idioma de origen; dir escribe carpetas de idioma como Nextra. El idioma de origen es sourceLocale y puede ser cualquier idioma. 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. Se habilita por defecto cuando docsOutput.style es "fumadocs". Reescribe las rutas de contenido y los enlaces .mdx relativos a rutas /docs/….
  • docsOutput.fumadocsUiCatalog Opcional. Arranque del catálogo de anulación de la interfaz de usuario de Fumadocs + traducción dentro de translate-docs. Campos: sourcePath (p. ej., 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 meta.json de Fumadocs (predeterminado: title, description).
  • docsOutput.localizedAssets Renombrado opcional de URL de imágenes e iconos en el HTML traducido cuando existe un archivo de configuración regional. Campos: include (predeterminado img/**), pattern (predeterminado {stem}-{locale}{ext}), onlyIfExists (predeterminado true), assetRoot (directorio utilizado para probar URL relativas a la raíz; el valor predeterminado es el directorio del archivo HTML). Marcadores de posición: {stem}, {ext}, {basename}, {locale}, {llocale}, {LOCALE}. La url() CSS no se reescribe. Consulte Páginas HTML.
  • docsOutput.html Lista de idiomas y hreflang opcionales para documentos HTML. Los comentarios predeterminados son <!-- ai-i18n:lang-list --> … <!-- /ai-i18n:lang-list --> y <!-- ai-i18n:hreflang --> … <!-- /ai-i18n:hreflang -->. languageList.format es links o select. languageList.label es local, english o both. hreflang.siteUrl añade prefijos a los enlaces alternativos; cuando se omite, los enlaces son relativos y se registra una advertencia. hreflang.xDefault tiene como valor predeterminado sourceLocale. hreflang.stripIndexHtml convierte index.html en una URL de directorio. Para HTML, docsRoot se elimina antes de añadir la carpeta de configuración regional (site/index.html → site/{locale}/index.html cuando docsRoot es site). Consulte Páginas HTML.
  • docsOutput.vitepressThemeCatalog Opcional. Inicialización del catálogo 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 generado en inglés), 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[]). Valor predeterminado true: traducir el texto YAML orientado 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 front matter 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 la lista de modelos se detiene se dividen progresivamente y se reintentan desde el primer modelo. La lista se detiene antes cuando el mismo error de calidad ha ocurrido tres veces. maxQualityRetrySplitDepth (predeterminado 3) 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 de riesgo / 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.

CampoDescripción
descriptionNota opcional para CLI / status (no se traduce).
contentPathsArchivos, directorios o globs de .json de origen bajo la raíz del proyecto. Se admiten los archivos de espacio de nombres i18next típicos (public/locales/en/*.json): objetos anidados, matrices, interpolación {{var}} en valores de cadena y claves de sufijo plural independientes (key_one, key_other).
outputPathTemplateRuta de salida requerida por configuración regional de destino. Marcadores de posición: {locale}, {LOCALE}, {llocale}, {stem}, {basename}, {extension}, {relativeToSourceRoot}.
targetLocalesSubconjunto opcional para este bloque; en caso contrario, raíz targetLocales.
keyPolicy.modeallowlist, denylist o both.
keyPolicy.translateKeysRutas con notación de puntos o patrones glob a incluir cuando el modo es allowlist o both.
keyPolicy.skipKeysRutas 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).

CampoDescripción
sourcePathUno 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.
outputDirDirectorio raíz para la salida SVG traducida.
style"flat" o "nested" cuando pathTemplate no está definido.
pathTemplateRuta de salida personalizada para SVG. Marcadores de posición: "{outputDir}", "{locale}", "{LOCALE}", "{llocale}", "{relPath}", "{stem}", "{basename}", "{extension}", "{relativeToSourceRoot}".
localePathLowercaseCuando 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.
forceLowercaseTexto traducido en minúsculas durante la reensamblaje SVG. Útil para diseños que dependen de etiquetas completamente en minúsculas.

modelSuggestion (opcional) ​

Pesos de ChrF y Arena, más un umbral de calidad opcional, para suggest-models y la pestaña Modelos del panel de control. El índice es solo de calidad. Omita el bloque, u omita un perfil, y ese perfil conservará los pesos integrados. El bloque no es reescrito por --apply ni por Actualizar configuración; estos solo escriben los ID de modelo. Un peso price heredado en un perfil se elimina cuando se carga la configuración.

  • quality — ChrF predeterminado 0.55, Arena 0.45, umbral de calidad 0.7
  • price — ChrF predeterminado 0.55, Arena 0.45, umbral de calidad 0.6

Cada objeto de perfil requiere chrf y arena. Cada valor es finito y al menos 0, y al menos uno es mayor que 0. Se normalizan para que su suma sea 1, por lo que 55 y 45 coinciden con los valores predeterminados. qualityFloor es opcional, en el rango (0, 1], y es la fracción del mejor ChrF en el conjunto de candidatos. Los modelos por debajo del umbral, incluidos los modelos sin medición de ChrF, se ordenan después de los que lo superan. Los dos perfiles comparten la misma mezcla predeterminada; difieren en el orden de clasificación (--quality por índice, --price por frontera de Pareto) y en el umbral.

json
"modelSuggestion": {
  "quality": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.7 },
  "price": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.6 }
}

glossary ​

CampoDescripción
userGlossaryRuta a un archivo CSV con las columnas Original language string (o en), locale, Translation, Force opcional y Context opcional - una fila por término de origen y configuración regional de destino (locale puede ser * para todos los destinos).
autoAddUserEditedToGlossaryCuando 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.
contextFilesArchivos Markdown o de texto sin formato (.md, .markdown, .txt) opcionales relativos al directorio de trabajo actual con explicaciones de productos o características. Se cargan al inicio del comando y se inyectan en la interfaz de usuario, documentos, JSON, SVG y avisos de revisión. No coloque estos archivos en docs[].contentPaths a menos que también desee que se traduzcan. Las URL son rechazadas. El texto completo se envía al proveedor de LLM configurado y puede aparecer en los registros de --debug-failed; no incluya secretos ni PII.
contextMaxCharsCaracteres máximos de texto de archivo de contexto concatenado enviado al modelo (predeterminado 12000, límite estricto 100000). El texto en exceso se trunca con una advertencia.
labelCheckSkipsLista opcional de comprobaciones de etiquetas de interfaz de usuario bloqueadas para omitir. Cada entrada tiene term (término del glosario en inglés), locales (códigos de destino, o * para cada configuración regional; predeterminado *), files opcional (globs relativos al directorio de trabajo actual) y note opcional. El término permanece como una sugerencia de aviso. Una omisión se aplica en la siguiente ejecución de translate-docs.

translate-docs, translate-json y translate-svg también obtienen sugerencias de cada bloque de interfaz de usuario cuyo uiGlossary es true (el valor predeterminado). Esto reutiliza las traducciones ya almacenadas en el strings.json de ese bloque. Establezca uiGlossary en false en un bloque para excluirlo. translate-ui y proofread-ui no utilizan esos catálogos como sugerencias. Las abreviaturas compactas de las etiquetas de la interfaz de usuario (formas con punto final como Alm., o compresiones cortas de un solo token como Size → Tam) se omiten para que los prompts del documento no se orienten hacia tokens {{…}} inventados. Los términos completos del producto y las traducciones de la interfaz de usuario no abreviadas se siguen utilizando como sugerencias.

La columna CSV opcional Context es una guía de uso en el idioma de origen para ese término (definición, uso gramatical, significado del producto). Se incluye solo cuando el término coincide con el lote actual. Cambiar la nota Context de un término o cualquier contenido de contextFiles invalida los segmentos en caché de la configuración regional coincidente y las filas de seguimiento de archivos en la siguiente ejecución, por lo que las traducciones se actualizan automáticamente. Cambiar solo un Translation preferido en una fila no forzada sigue utilizando la caché existente a menos que pase --force / --force-update. Una fila Force omite solo los segmentos cuyo origen contiene ese término, cuando el texto almacenado aún no incluye la traducción forzada. Se mantienen las filas de caché editadas por el usuario del panel. Los catálogos de interfaz de usuario también siembran un prefijo compartido de varias palabras como su propio término cuando ese prefijo es una etiqueta capitalizada (al menos dos palabras de contenido) y la traducción compartida es una frase corta sin un marcador de posición. La traducción de Markdown requiere una etiqueta de interfaz de usuario de dos a cinco palabras para mantener su traducción de catálogo cuando la fuente la cita como el tramo completo en negrita o código en línea, en un encabezado o en una línea que es solo esa etiqueta. Una frase en negrita más larga que simplemente contiene el término es una sugerencia. El uso de mayúsculas y minúsculas en el título dentro de una oración es una sugerencia, por lo que la traducción puede flexionarse (el hindi Cursor account puede convertirse en कर्सर खाते en lugar de la forma de diccionario कर्सर खाता). Una etiqueta con una sola palabra de contenido, como Sign in, permanece como una sugerencia. La comprobación ignora las mayúsculas. Todavía requiere la redacción del catálogo como una subcadena, por lo que una forma gramaticalmente flexionada puede fallar. Ese fallo es una advertencia: el segmento se escribe, se almacena en caché con una bandera de etiqueta de glosario y se lista al final de la ejecución en glossary-review-*.md bajo cacheDir. Agregue una entrada labelCheckSkips, o pase --recheck-glossary-warnings, después de revisarlo. --force vuelve a traducir las filas marcadas junto con todos los demás segmentos.

Ejemplo:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md", "i18n/billing-feature.md"],
    "contextMaxChars": 12000,
    "labelCheckSkips": [
      {
        "term": "Target language",
        "locales": ["uk"],
        "files": ["website/src/content/docs/docs/transform.md"],
        "note": "Inflected inside a bold phrase"
      }
    ]
  }
}

Genere un archivo CSV de glosario vacío:

bash
ai-i18n-tools glossary-generate

Para redactar contextFiles desde el repositorio, utilice el prompt de copiar y pegar del agente en Generar un archivo de contexto con un agente de IA. Consulte el Glosario para saber cómo se aplican las filas de términos y los archivos de contexto.

Publicado bajo la licencia MIT.