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 ensrc/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:
{
"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:
{
"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:
translationModelsLista ordenada preferida de ID de modelo (ID ascendentes simples, sin prefijoprovider/; los ID de OpenRouter mantienen su formato nativovendor/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 paratranslate-ui, generación plural (Paso 0 y Pase B) yproofread-ui. Se intenta después de cualquier entradalocaleModelscoincidente para la configuración regional de destino, antes detranslationModels.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 (uiModelspara la interfaz de usuario) ytranslationModels. Las claves de configuración regional normalizadas duplicadas se rechazan al cargar la configuración.baseUrlURL base compatible con OpenAI. Anula la URL base preestablecida; es necesaria para un proveedor no preestablecido.apiKeyEnvVariable de entorno que contiene la clave API. Anula la variable de entorno preestablecida.headersEncabezados HTTP adicionales enviados con cada solicitud a este proveedor.maxTokensMáximo de tokens de finalización por solicitud. Predeterminado:8192.temperatureTemperatura de muestreo. Predeterminado:0.2.requestTimeoutTiempo máximo en segundos para esperar cada solicitud a este proveedor. Anula elrequestTimeout/requestTimeoutMsde nivel superior. Cuando ni este proveedor ni la configuración de nivel superior establecen un tiempo de espera, el valor predeterminado es120segundos. Establezca solo uno derequestTimeoutyrequestTimeoutMsen el mismo objeto.requestTimeoutMsTiempo máximo en milisegundos para esperar cada solicitud a este proveedor. Anula elrequestTimeout/requestTimeoutMsde nivel superior. Cuando ni este proveedor ni la configuración de nivel superior establecen un tiempo de espera, el valor predeterminado es120000(120 segundos). Establezca solo uno derequestTimeoutyrequestTimeoutMsen 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 unusage.costinformado 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 filaapi_calls.
El origen del coste se resuelve en este orden:
- una entrada
modelPricingcoincidente (anula este valor predeterminado del proveedor); - un coste informado por el proveedor (nunca se reemplaza);
- esta tarifa
pricing; - 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 } }. Anulapricingpara 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, soloproviders.cheaperinference) Cuandotrue, las solicitudes de chat envían"zdr": trueylist-models,check-modelsysuggest-modelscarganGET /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):
| Proveedor | URL base | Variable de entorno de clave de API |
|---|---|---|
alibaba | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 | ALIBABA_API_KEY |
anthropic | https://api.anthropic.com/v1 | ANTHROPIC_API_KEY |
apikeyfan | https://api.apikey.fan/v1 | APIKEYFAN_API_KEY |
cerebras | https://api.cerebras.ai/v1 | CEREBRAS_API_KEY |
cheaperinference | https://api.cheaperinference.com/v1 | CHEAPERINFERENCE_API_KEY |
deepseek | https://api.deepseek.com | DEEPSEEK_API_KEY |
gemini | https://generativelanguage.googleapis.com/v1beta/openai | GOOGLE_API_KEY |
groq | https://api.groq.com/openai/v1 | GROQ_API_KEY |
mistral | https://api.mistral.ai/v1 | MISTRAL_API_KEY |
nvidia | https://integrate.api.nvidia.com/v1 | NVIDIA_API_KEY |
ollama | http://localhost:11434/v1 | (ninguno) |
openai | https://api.openai.com/v1 | OPENAI_API_KEY |
openrouter | https://openrouter.ai/api/v1 | OPENROUTER_API_KEY |
xai | https://api.x.ai/v1 | XAI_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
"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
"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
"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 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". |
translateJson | 3 | JSON 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
trueomitido sin nada que traducir se omite: ningún bloque de interfaz de usuario tienesourceRoots, ningún bloque de documentos tienecontentPathsodocusaurusCatalogDir,json[]no tienecontentPathsosvgno está configurado. - Escribir el indicador como
truecuando ese pipeline no tiene trabajo es un error de configuración. - Escribir
falsedesactiva ese pipeline parasyncincluso cuando existen fuentes. --no-ui,--no-docs,--no-jsony--no-svgomiten 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.
descriptionNota opcional para las personas que leen la configuración (no se envía al modelo). Se muestra comoui[i] — descriptionen los encabezados de comandos,status,statisticsy el panel.sourceRootsDirectorios o patrones glob (relativos a cwd) escaneados en busca de llamadas at("…"). Admite patrones comosrc/o["src/**/*.ts"]. Se omite un bloque con una lista vacía a menos que--ui-blocklo nombre, lo cual es un error.stringsJsonRuta al archivo de catálogo maestro de este bloque. Actualizado porextract.flatOutputDirDirectorio donde se escriben los archivos JSON por configuración regional de este bloque (de.json, etc.).flatOutputCuandotrue(el valor predeterminado),translate-uiescribe un archivo JSON plano por cada configuración regional. Establezcafalsepara emitir solo gettext o resx. Un bloque conflatOutput: falsedebe establecergettextoresx.resxSalida opcional de.resxde .NET.outputDir(valor predeterminadoResources) ybaseName(valor predeterminadoSharedResource) escriben{baseName}.resxmás{baseName}.{culture}.resx.writeNeutral(valor predeterminado true) coloca el texto fuente en el archivo neutro para queResourceManagerpueda recurrir.localeFormatesbcp47(valor predeterminado,pt-BR) oposix(pt_BR).ingestExistingResx(valor predeterminado true) lee satélites duranteextract.neutralFileasigna claves con nombre heredadas comoLoginButtona través del valor neutro. Las claves de contexto usan U+2404. Las formas plurales son entradas separadas llamadas{singular}[{form}]. Un bloque conflatOutput: falsedebe establecergettextoresx.gettextSalida opcional de GNU gettext para este bloque.outputDir(valor predeterminado./locales) recibe<locale>/LC_MESSAGES/<domain>.poy, cuandocompileMoes true (el valor predeterminado), el.mocoincidente.domaintoma por defectomessages.potPathes el catálogo de plantillas.ingestExistingPo(valor predeterminadotrue) rellena las ranurasstrings.jsonvacías con valoresmsgstrno difusos duranteextracty no reemplaza una traducción no vacía o editada por el usuario.localeFormatesposix(valor predeterminado,pt_BR) obcp47(pt-BR). Las filas contextuales usan el separador\u0004de gettext. La misma cadena de idioma de origen en dos contextos no comparte un ID de catálogo.targetLocalesLista opcional de configuraciones regionales para este bloque. Cuando se omite o está vacía, el bloque usa la raíztargetLocales.languagesManifestPathRuta opcional dondeextractygenerate-ui-languagesescriben elui-languages.jsonde este bloque. Cuando se omite, el bloque 0 usa la raízlanguagesManifestPath(que a su vez toma por defecto el{flatOutputDir}/ui-languages.jsonde este bloque). Los bloques posteriores usan por defecto{flatOutputDir}/ui-languages.json.uiGlossaryCuandotrue(el valor predeterminado), elstrings.jsonde este bloque es una fuente de sugerencias de glosario paratranslate-docs,translate-jsonytranslate-svg.translate-ui,proofread-uiy el linting de código fuente usan sologlossary.userGlossary. Establezcafalsepara 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 heredadoreactExtractor.funcNames) Nombres de funciones adicionales para escanear (valor predeterminado:["t", "i18n.t"]).uiExtractor.extensions(o el heredadoreactExtractor.extensions) Extensiones de archivo a incluir (valor predeterminado:[".js", ".jsx", ".ts", ".tsx"]). Agregue.astropara el frontmatter de Astro y las expresiones de plantilla.uiExtractor.includePackageDescription(o el heredadoreactExtractor.includePackageDescription) Cuandotrue(valor predeterminado),extracttambién incluyepackage.jsondescriptioncomo una cadena de interfaz de usuario cuando está presente. Establezcafalseen bloques adicionales para que la misma descripción no se extraiga en cada catálogo.uiExtractor.packageJsonPath(o el heredadoreactExtractor.packageJsonPath) Ruta personalizada al archivopackage.jsonutilizado para esa extracción opcional de descripción.uiExtractor.includeUiLanguageEnglishNames(o el heredadoreactExtractor.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) odotnet(solo{0},{0,-10},{0:format}). En el estilodotnet, un signo de porcentaje es texto literal y las llaves dobles son llaves literales. La plantillaui-dotnetestablecedotnet.uiExtractor.excludePatrones Minimatch, relativos a la raíz del proyecto, descartados después del escaneo.bin,obj,.vs,TestResultsypackagesya se omiten por nombre de directorio. Las plantillasui-dotnetyui-dotnet-resxexcluyen**/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
cacheDirDirectorio de caché de SQLite (compartido por todos los bloquesdocs). Predeterminado.translation-cache. Reutilizar entre ejecuciones. Si está migrando desde una caché de traducción de documentación personalizada, archívela o elimínela;cacheDircrea su propia base de datos SQLite y no es compatible con otros esquemas.suggest-modelstambié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
.gitignoreo.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 utilizaai-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.
# 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 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.uiGlossary y glossary.uiGlossaryFromStringsJson | eliminados; la carga de la configuración falla. Use ui[].uiGlossary (booleano, valor predeterminado true) |
ui.reactExtractor | ui.uiExtractor (el alias aún se acepta) |
svg.svgExtractor.forceLowercase | svg.forceLowercase |
Fuentes de contenido
descriptionNota opcional legible para humanos sobre este bloque (no se usa para traducción). Se antepone en el encabezadotranslate-docs🌐cuando se establece; también se muestra en los encabezados de sección destatus.contentPathsCuerpos de páginas en Markdown/MDX y plantillas.astroa traducir (translate-docsanaliza estos en busca de.md,.mdxy.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.sourceFilesAlias opcional que se fusiona encontentPathsen tiempo de carga.targetLocalesSubconjunto opcional de configuraciones regionales solo para este bloque (en caso contrario, se usa la raíztargetLocales). Las configuraciones regionales efectivas de la documentación son la unión entre todos los bloques.docusaurusCatalogDirOpcional. Directorio de origen para los catálogos de etiquetas JSON de Docusaurus para este bloque (por ejemplo,"i18n/en"dedocusaurus write-translations). Los cuerpos de las páginas siempre provienen decontentPaths;docusaurusCatalogDirsolo proporciona JSON de shell/UI, no MDX.nextraMetaGlobGlob(s) opcional(es) para_meta.ts/_meta.tsx/_meta.jsde Nextra bajodocsRoot. CuandodocsOutput.stylees"nextra"y esto se omite, todos los archivos_metabajodocsRootse recopilan automáticamente.nextraMetaTranslatableKeysNombres de propiedades opcionales cuyos valores de cadena se traducen en objetos_metade Nextra (predeterminado:title,display,breadcrumb).nextraDictionaryPathMódulo de diccionario de tema de Nextra en inglés opcional (por ejemplo,"app/_dictionaries/en.ts"). Traducido a{dir}/{locale}.tsdurantetranslate-docs.nextraDictionaryOutputTemplatePlantilla de salida opcional para módulos de diccionario de configuración regional (predeterminado:{dir}/{locale}.tsen relación con el directorio del diccionario).
docsOutput
Diseño de salida para este bloque.
outputDirDirectorio raíz para la salida traducida de este bloque.docsOutput.style"nested"(predeterminado),"flat","doc-system", o alias"docusaurus"/"astro-starlight"/"vitepress"/"nextra".docsOutput.localeSubpathSegmento de ruta entre{locale}/y{relativeToDocsRoot}paradoc-system(obligatorio cuando se usastyle: "doc-system"directamente; preestablecido cuando se usa un alias). Use""para carpetas de configuración regional estilo Starlight.docsOutput.docsRootRaíz de documentos de origen para el diseño de Docusaurus (por ejemplo,"docs"). Predeterminado"docs"cuando se omite.docsOutput.pathTemplateRuta de salida de markdown personalizada. Marcadores de posición:"{outputDir}","{locale}","{LOCALE}","{llocale}","{relPath}","{stem}","{basename}","{extension}","{docsRoot}","{relativeToDocsRoot}".docsOutput.jsonPathTemplateRuta de salida JSON personalizada para archivos de etiquetas. Admite los mismos marcadores de posición quepathTemplate.docsOutput.localePathLowercaseCuandotrue, los diseños de salida integrados (nested,flat,doc-systemsinpathTemplate) usan segmentos de configuración regional en minúsculas en las rutas. Predeterminadofalse;astro-starlightydoc-systemconlocaleSubpathvacío se establecen de forma predeterminada entrueen la carga de configuración.docsOutput.flatPreserveRelativeDirCuandodocsOutput.style = "flat", mantenga los subdirectorios de origen para que los archivos con el mismo nombre base no colisionen. Predeterminadofalse.docsOutput.rewriteRelativeLinksReescribir enlaces relativos después de la traducción (habilitado automáticamente cuandodocsOutput.style = "flat"y sinpathTemplatepersonalizado).docsOutput.linkRewriteDocsRootRaí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.rewriteVitepressLinksCuandotrue, ejecute el normalizador de enlaces de VitePress después de la traducción. Se habilita por defecto cuandodocsOutput.stylees"vitepress". Úselo con cualquier diseñodoc-systemdonde las carpetas de idioma se encuentren junto a los archivos del idioma de origen bajodocsRoot. El idioma de origen essourceLocaley puede ser cualquier idioma. Reescribe las rutasdocs/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.rewriteNextraLinksCuandotrue, ejecute el normalizador de enlaces de Nextra después de la traducción. Se habilita por defecto cuandodocsOutput.stylees"nextra". Reescribe las rutascontent/en/…y.mdxrelativas a rutas del sitio neutrales al idioma (/guide/…) para Next.jsi18n. Consulte Integración de Nextra — Convenciones de enlaces.docsOutput.fumadocsParser"dot"(predeterminado) o"dir". Dot escribestem.{locale}.mdxjunto a los archivos del idioma de origen; dir escribe carpetas de idioma como Nextra. El idioma de origen essourceLocaley puede ser cualquier idioma. Consulte Integración de Fumadocs — Diseño de página.docsOutput.rewriteFumadocsLinksCuandotrue, ejecute el normalizador de enlaces de Fumadocs después de la traducción. Se habilita por defecto cuandodocsOutput.stylees"fumadocs". Reescribe las rutas de contenido y los enlaces.mdxrelativos a rutas/docs/….docsOutput.fumadocsUiCatalogOpcional. Arranque del catálogo de anulación de la interfaz de usuario de Fumadocs + traducción dentro detranslate-docs. Campos:sourcePath(p. ej.,lib/layout.shared.ts),catalogPath(JSON en inglés generado),outputPathTemplateopcional (predeterminado:ui.{locale}.jsonjunto acatalogPath).docs[].fumadocsMetaGlobGlob(s) opcional(es) para la colecciónmeta.jsoncuandodocsOutput.stylees"fumadocs". Predeterminado:meta.jsonrecursivo bajodocsOutput.docsRoot.docs[].fumadocsMetaTranslatableKeysNombres de propiedades cuyos valores de cadena se traducen enmeta.jsonde Fumadocs (predeterminado:title,description).docsOutput.localizedAssetsRenombrado opcional de URL de imágenes e iconos en el HTML traducido cuando existe un archivo de configuración regional. Campos:include(predeterminadoimg/**),pattern(predeterminado{stem}-{locale}{ext}),onlyIfExists(predeterminadotrue),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}. Laurl()CSS no se reescribe. Consulte Páginas HTML.docsOutput.htmlLista 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.formateslinksoselect.languageList.labeleslocal,englishoboth.hreflang.siteUrlañade prefijos a los enlaces alternativos; cuando se omite, los enlaces son relativos y se registra una advertencia.hreflang.xDefaulttiene como valor predeterminadosourceLocale.hreflang.stripIndexHtmlconvierteindex.htmlen una URL de directorio. Para HTML,docsRootse elimina antes de añadir la carpeta de configuración regional (site/index.html→site/{locale}/index.htmlcuandodocsRootessite). Consulte Páginas HTML.docsOutput.vitepressThemeCatalogOpcional. Inicialización del catálogo de tema/navegación/barra lateral de VitePress + traducción dentro detranslate-docs. Campos:configPath(configuración de VitePress con cadenas de tema),catalogPath(JSON anidado generado en inglés),outputPathTemplateopcional (predeterminado:theme.{locale}.jsonjunto acatalogPath).
Posprocesado
docsOutput.postProcessingTransformaciones 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 deaddFrontmatter.docsOutput.postProcessing.regexAdjustmentsLista ordenada de{ "description"?, "search", "replace" }.searches un patrón de expresión regular (la cadena simple usa la banderag, o/pattern/flags).replaceadmite 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. RequierelanguagesManifestPath(o un manifiesto enui.flatOutputDir/ui-languages.json) para etiquetas endónimas cuandolabel: "local".
Comportamiento y metadatos
translateFrontmatterFieldsAl mismo nivel quedocsOutput(por bloquedocs[]). Valor predeterminadotrue: traducir el texto YAML orientado al usuario para Starlight/Docusaurus (etiquetastitle,description,sidebar.label,sidebar_label,keywords,hero.title,hero.tagline,hero.image.alt,hero.actions[].text,pagination_label,prev/next). Establezcafalsepara mantener todo el bloque de front matter sin cambios; pase una matriz de cadenas para restringir a rutas de puntos específicas.segmentSplittingAl mismo nivel quedocsOutput(por bloquedocs[]). Segmentos opcionales más granulares para la extracción detranslate-docs:{ "enabled", "maxCharsPerSegment"?, "splitPipeTables"?, "splitDenseParagraphs"?, "maxLinesPerParagraphChunk"?, "splitLongLists"?, "maxListItemsPerChunk"?, "qualityRetrySplit"?, "maxQualityRetrySplitDepth"? }. Cuandoenabledestrue(predeterminado cuando se omitesegmentSplitting), 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": falsepara usar un segmento por bloque de cuerpo delimitado por línea en blanco solamente. CuandoqualityRetrySplitestrue(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(predeterminado3) limita las divisiones recursivas.warnMarkdownSourceIssuesCuandotrue(predeterminado cuando se omite), cada ejecución detranslate-docsvuelve 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 filasmarkdown_source_issuespara la ruta de archivo de caché de ese archivo. Establezcafalsepara omitir advertencias y actualizaciones de SQLite para este bloque.addFrontmatterCuandotrue(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 enfalsepara omitir.emphasisPlaceholdersPor bloquedocs[]. Cuandotrue, enmascara los delimitadores de énfasis de markdown como marcadores de posición antes de la traducción. Por defecto,truepara configuraciones regionales CJK (zh,ja,ko) y para las configuraciones regionales enumeradas enrtlLocales; de lo contrario, por defecto,false. Se puede anular mediante CLI--emphasis-placeholders/--no-emphasis-placeholders.rtlLocalesMatriz 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).
protectAttributesOpcional. 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 dearia-*, etc.). No distingue entre mayúsculas y minúsculas. Se aplica a:.astroextracción de parseo y reemplazo (etiquetas HTML estáticas y literales de cadena después deattr=dentro de bloques{expression}).- Extracción de marcadores de posición MDX durante la traducción de segmentos markdown/Astro (
label,tooltip, yaria-labelen etiquetas JSX en mayúsculas, además deTabItemvaluecuando sea aplicable).
- Extracción de marcadores de posición MDX durante la traducción de segmentos markdown/Astro (
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.
protectKeysOpcional. 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 ejemplolabel: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)
"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 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). |
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. |
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 predeterminado0.55, Arena0.45, umbral de calidad0.7price— ChrF predeterminado0.55, Arena0.45, umbral de calidad0.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.
"modelSuggestion": {
"quality": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.7 },
"price": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.6 }
}glossary
| Campo | Descripción |
|---|---|
userGlossary | Ruta 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). |
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. |
contextFiles | Archivos 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. |
contextMaxChars | Caracteres 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. |
labelCheckSkips | Lista 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:
{
"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:
ai-i18n-tools glossary-generatePara 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.