Arquitectura
Visión general de la arquitectura
El código base está organizado en cuatro capas. Utilice esta sección para el modelo mental; abra el árbol de origen cuando necesite detalles a nivel de archivo.
Cómo encaja una ejecución de sync
sync (y los comandos de traducción individuales) ejecutan las características habilitadas en orden:
| Paso | Comando | Qué hace |
|---|---|---|
| 1 | extract → translate-ui | Escanear fuentes de la interfaz de usuario → actualizar strings.json → rellenar JSON de configuración regional plana (de.json, …) |
| 2 | translate-svg (opcional) | Traducir texto SVG bajo config.svg |
| 3 | translate-docs | Traducir páginas de markdown, MDX, .astro; JSON de catálogo de Docusaurus; _meta / diccionario .ts de Nextra; catálogo de temas de VitePress |
| 4 | translate-json (opcional) | Traducir hojas JSON anidadas bajo json[] |
Cada pipeline sigue el mismo bucle central: extraer segmentos → proteger sintaxis → agrupar → buscar en caché o llamar a LLM → escribir salida. Los servicios compartidos en el medio —configuración, marcadores de posición, caché, glosario, LlmClient— se describen en Infraestructura compartida.
Mapa de módulos
| Capa | Carpeta | Rol |
|---|---|---|
| Entrada | src/cli/ | Comandos CLI: init, extract, mark-html, translate-ui, translate-docs, translate-json, translate-svg, sync, status, dashboard, … |
| Pipelines | src/extractors/ | Extracción de segmentos de JS/TS, marcadores HTML, markdown, JSON, SVG, .astro |
src/processors/ | Protección de marcadores de posición, procesamiento por lotes, validación, reescritura de enlaces | |
| Compartido | src/core/ | Configuración, tipos, caché SQLite, prompts, rutas de salida, utilidades de configuración regional |
src/api/ | LlmClient — cliente de chat agnóstico al proveedor (Vercel AI SDK) con fallback de modelo | |
src/glossary/ | Carga de glosario, sugerencias de términos y archivos de contexto de proyecto opcionales para las indicaciones | |
src/utils/ | Registrador, hashing, analizador de ignorados, tablas de ancho de visualización, cargador .env | |
| Tiempo de ejecución de su aplicación | src/runtime/ | Ayudantes i18next y utilidades de visualización — exportados como 'ai-i18n-tools/runtime' (Ayudantes de tiempo de ejecución) |
| Interfaz de usuario de la herramienta (dogfooding) | src/i18n/, src/dashboard-app/, src/server/ | Localiza la propia CLI y el Panel de traducción de este paquete — separado del contenido de tu proyecto (Autolocalización) |
Todo lo destinado a uso programático se reexporta desde src/index.ts (API programática).
Resúmenes de pipelines
| Canalización | Sección | Entrada → salida |
|---|---|---|
| Cadenas de interfaz de usuario | Elementos internos de las cadenas de interfaz de usuario | Archivos fuente → strings.json → {locale}.json plano |
| Documentos | Elementos internos de los documentos | Markdown / MDX / .astro / Docusaurus JSON → archivos por configuración regional en docs[].outputDir |
| Paquetes JSON | Elementos internos de JSON | JSON anidado en json[] → archivos JSON por configuración regional |
| SVG | Elementos internos de los documentos — extractores | Archivos SVG en config.svg → copias SVG traducidas |
Cadenas de interfaz de usuario internas
| Paso | Componente | Resultado |
|---|---|---|
| 1 | Archivos fuente (JS/TS; .astro / .html opcional) | Archivos en disco |
| 2 | UIStringExtractor (Babel a través de ui-string-babel.ts) | Segmentos identificados por hash MD5 |
| 3 | strings.json | Catálogo maestro: { hash: { source, translated, models?, locations? } } |
| 4 | LlmClient.translateUIBatch() | Matriz JSON de cadenas de origen → traducciones (+ ID de modelo por lote) |
| 5 | de.json, pt-BR.json, … | Mapas planos: cadena de origen → traducción (sin metadatos de modelo) |
UIStringExtractor
extractUiCallsFromFileContent en ui-string-babel.ts encuentra llamadas a t("literal") y i18n.t("literal"). Los archivos JS y TS se analizan con @babel/parser (código fuente del módulo, TypeScript y JSX). Para las fuentes .astro (cuando se enumeran en ui.uiExtractor.extensions), la misma función analiza los bloques de frontmatter y de plantilla {expression} y aplica las mismas reglas funcNames. Los nombres de función y las extensiones de archivo son configurables a través de ui.uiExtractor (ui.reactExtractor es un alias compatible). extract también fusiona entradas adicionales en el mismo catálogo: el proyecto package.json description cuando includePackageDescription está habilitado (predeterminado), y cada englishName del catálogo maestro de ui-languages incluido (creado a partir de sourceLocale + targetLocales) cuando includeUiLanguageEnglishNames es true (las cadenas ya encontradas en el código fuente mantienen la precedencia; no lee languagesManifestPath). extract también regenera ui-languages.json en languagesManifestPath. Los hashes de segmento son los primeros 8 caracteres hexadecimales MD5 de la cadena de origen recortada; estos se convierten en las claves en strings.json.
Para las fuentes .html / .htm (cuando se enumeran en ui.uiExtractor.extensions), extract en su lugar enruta el archivo a través de html-i18n-marks.ts, que escanea los atributos de marcador data-i18n / data-i18n-title / data-i18n-placeholder / data-i18n-alt / data-i18n-aria-label (configurables a través de ui.uiExtractor.htmlI18nAttributes). Un marcador simple toma su texto fuente del propio textContent o atributo del elemento; un marcador con valor (data-i18n="Key") usa el valor. data-i18n-locale-src y data-i18n-locale-href están reservados para el tiempo de ejecución del navegador y nunca se extraen. El mismo módulo impulsa el comando mark-html, que inserta los marcadores simples automáticamente (incluyendo alt y aria-label) y nunca inserta los marcadores de URL de configuración regional. Los archivos HTML nunca llegan al paso de Babel. El HTML de configuración regional generado bajo un outputDir de documentos se excluye de este escaneo.
Los sitios SSG de Astro simples pueden omitir i18next: cargar {locale}.json plano en tiempo de compilación y resolver t('source text') por clave de texto fuente. El idioma de origen es sourceLocale y puede ser cualquier idioma (consulte examples/astro-website/src/i18n/t.ts y Cadenas de interfaz de usuario — sitio web de Astro).
Las aplicaciones HTML puras siguen el mismo modelo de catálogo con atributos de marcador en lugar de llamadas a t() — consulta Marcado de HTML para traducción. El script listo para usar es ai-i18n-tools/html-runtime/i18n.js.
El HTML estático que debe convertirse en un archivo por configuración regional es un pipeline de documentos (HtmlTemplateExtractor dentro de translate-docs), no este catálogo. Consulte Páginas HTML.
strings.json
El catálogo maestro tiene la siguiente estructura:
{
"a1b2c3d4": {
"source": "The English string",
"translated": {
"de": "Der deutsche Text",
"pt-BR": "O texto em português"
},
"models": {
"de": "anthropic/claude-3.5-haiku",
"pt-BR": "openai/gpt-4o"
},
"locations": [{ "file": "src/app/page.tsx", "line": 51 }]
}
}models (opcional) — por configuración regional, qué modelo produjo esa traducción después de la última ejecución exitosa de translate-ui para esa configuración regional (o user-edited si el texto se guardó desde el Panel de traducción). locations (opcional) — dónde extract encontró la cadena (escáner + línea de descripción del paquete; las cadenas englishName del maestro incluido pueden omitir locations).
extract agrega nuevas claves y conserva los datos translated / models existentes para las claves que aún están presentes en el escaneo (literales del escáner, descripción opcional, englishName maestro incluido opcional). translate-ui completa las entradas translated faltantes, actualiza models para las configuraciones regionales que traduce y escribe archivos de configuración regional planos.
Manifiesto de ui-languages.json — Matriz JSON de { code, label, englishName, direction } (BCP-47 code, UI label, referencia englishName, "ltr" o "rtl"). Use generate-ui-languages o extract para construir un archivo de proyecto a partir de sourceLocale + targetLocales y el data/ui-languages-complete.json maestro incluido.
Archivos de configuración regional planos
Cada localización objetivo recibe un archivo JSON plano (de.json) que asocia cadena fuente → traducción (sin campo models):
{
"The English string": "Der deutsche Text",
"Save": "Speichern"
}i18next carga estos archivos como paquetes de recursos y busca traducciones mediante la cadena fuente (modelo de clave como valor por defecto).
Mensajes de traducción de interfaz
buildUIPromptMessages construye mensajes del sistema y del usuario que:
- Identifique los idiomas de origen y de destino (por nombre de visualización de
localeDisplayNamesoui-languages.json). - Anteponga una directiva de script cuando la configuración regional de destino tenga un sistema de escritura esperado (script BCP-47 explícito o un idioma predeterminado como
hi→ Devanagari,ar→ árabe,ja→ kana/kanji japonés). - Envíe una matriz JSON de cadenas y solicite una matriz JSON de traducciones a cambio.
- Incluya sugerencias de glosario cuando estén disponibles.
LlmClient.translateUIBatch prueba cada modelo en orden, recurriendo a errores de análisis, de red o de script incorrecto (incluyendo la alternativa romanizada/latina para configuraciones regionales de script nativo). La CLI construye esa lista por configuración regional de destino a partir de localeModels, el uiModels opcional y translationModels (consulta Modelos de IA).
Documentos internos
| Paso | Componente | Resultado |
|---|---|---|
| 1 | Archivos Markdown / MDX / JSON / .astro (translate-docs) | Archivos fuente |
| 2 | MarkdownExtractor / JsonExtractor / AstroTemplateExtractor | segments[] — segmentos tipados con hash + contenido |
| 3 | PlaceholderHandler | Texto protegido: HTML, advertencias, anclas, MDX, URL, código en línea, énfasis enmascarado como tokens |
| 4 | splitTranslatableIntoBatches | batches[] — agrupado por recuento + límite de caracteres |
| 5 | Búsqueda de TranslationCache | Acierto de caché → omitir; fallo → LlmClient.translateDocumentBatch |
| 6 | PlaceholderHandler.restoreAfterTranslation | Texto final — marcadores de posición restaurados |
| 7 | resolveDocumentationOutputPath | Archivo de salida — diseño Docusaurus o diseño plano |
Extractores
Todos los extractores extienden BaseExtractor e implementan extract(content, filepath): Segment[].
MarkdownExtractor- divide el markdown en segmentos tipados:frontmatter,heading,paragraph,code,admonition. El frontmatter YAML se clasifica como no traducible (slug,idy otras claves de enrutamiento permanecen estables). Los bloquesexport ...de nivel superior (por ejemplo, definiciones de componentes de React) se clasifican como segmentosotherno traducibles junto con el manejoimport ...existente. Los bloques de varias líneas que comienzan con una etiqueta JSX en mayúscula (por ejemplo, un bloque<Tabs>) se clasifican como párrafos traducibles. Los segmentos no traducibles (bloques de código, HTML sin formato) se conservan textualmente.AstroTemplateExtractor- análisis y reemplazo para páginas de marketing.astro(translate-docsa través detranslateAstroFileendoc-translate.ts). Extrae nodos de texto HTML visibles para el usuario y atributos traducibles (alt,title,aria-label,placeholder), además de literales de cadena dentro de bloques de plantilla{expression}cuando son visibles para el usuario. Omite TypeScript de frontmatter,<script>,<style>, valores de atributos/claves protegidos y literales dentro det('…'). El reensamblaje ajusta las importaciones relativas cuando las rutas de salida son más profundas (por ejemplo,src/pages/de/index.astro). Consulte Páginas del sitio web de Astro.JsonExtractor- extrae valores de cadena de archivos de etiquetas JSON de Docusaurus (catálogos de UI de Docusaurus, no cuerpo MDX).SvgExtractor- extrae contenido<text>,<title>y<desc>de SVG (utilizado portranslate-svgpara archivos bajoconfig.svg, no portranslate-docs).html-i18n-marks.ts: un escáner de etiquetas HTML enfocado utilizado porextractpara fuentes de.html/.htmy por el comandomark-html.collectHtmlI18nStrings/collectHtmlI18nLocationsleen los atributos de marcadordata-i18n*(marcador simple →textContent/title/placeholderdel elemento; marcador con valor → el valor), ymarkHtmlContentinserta marcadores simples en elementos de texto hoja / título / marcador de posición (idempotente, respetadata-i18n-ignore, omite elementos similares a código y de contenido mixto). El ayudante compartidonormalizeI18nTextmantiene las claves en tiempo de compilación idénticas al tiempo de ejecución del navegador.
Sitios híbridos de Astro (interfaz de usuario + HTML de página)
Las aplicaciones de Astro plano a menudo habilitan ambas cadenas de interfaz de usuario y documentos en una configuración (referencia: examples/astro-website/):
| Capa | Mecanismo | Salida |
|---|---|---|
| HTML de plantilla | AstroTemplateExtractor + translate-docs | .astro por configuración regional en docs[].outputDir |
Frontmatter / t('…') | ui-string-babel.ts + extract + translate-ui | public/locales/{locale}.json plano (cadena de idioma de origen como clave; sourceLocale puede ser cualquier idioma) |
El comando sync ejecuta los pasos habilitados en orden: extraer y luego traducir-interfaz de usuario (cuando features.translateUIStrings) → opcional traducir-svg → traducir-documentos → opcional traducir-json (a menos que se omita con --no-ui, --no-svg, --no-docs o --no-json). La plantilla de inicialización ui-astro-website crea solo cadenas de interfaz de usuario; agregue docs[] y features.translateDocs para HTML de página.
Inserción de anclas de encabezado (write-heading-ids CLI)
El comando write-heading-ids es un preprocesador local y sin uso de LLM para archivos markdown de documentación. Implementación: src/cli/write-heading-ids.ts coordina el descubrimiento de archivos; src/markdown/write-heading-ids-core.ts analiza las líneas e inserta anclajes.
Requiere una configuración válida con al menos un bloque docs[]. Para cada bloque, recopila archivos .md / .mdx en contentPaths, aplica las reglas .translate-ignore del proyecto (la misma idea que la traducción de documentos) y, opcionalmente, restringe a un subárbol con --path / --file. Cada archivo se transforma con applyHeadingAnchorsToMarkdown: para cada encabezado ATX plano (# … a ###### …) fuera de los bloques de código cercados, los ID de encabezado existentes de cualquier forma se reemplazan con el estilo seleccionado. Los estilos HTML escriben <a id="slug"></a> en la línea anterior a un encabezado sin sufijo; --slug-style mdx-comment escribe {/* #slug */} en la línea del encabezado (y elimina un ancla HTML precedente). Los slugs siempre provienen del texto del encabezado actual. --remove elimina los anclajes HTML, los sufijos clásicos de {#id} y los ID de comentarios MDX sin escribir nuevos. Los algoritmos de slug coinciden con los ecosistemas comunes —github (predeterminado), bitbucket, gitlab, pymdown (normalización Unicode opcional / banderas de codificación de porcentaje), azure-devops, más mdx-comment (slug de github + salida de comentarios MDX)— para que los ID de anclaje se mantengan consistentes con las herramientas existentes (doctoc, PyMdown, Docusaurus, etc.). --dry-run informa las ediciones que se realizarían sin escribirlas.
Después del pase de origen, el mismo comando reposiciona esos identificadores en inglés en el markdown traducido existente de cada configuración regional (resolveTranslatedOutputPath). Los títulos traducidos nunca se vuelven a slugificar; un {#id} / {/* #id */} a mitad de encabezado se mueve de nuevo al sufijo (o ancla HTML) que espera el estilo seleccionado. Los archivos de configuración regional que faltan se omiten.
Este comando no se ejecuta dentro de translate-docs ni sync; ejecútelo explícitamente cuando desee IDs de fragmento estables en los archivos fuente antes de la traducción o publicación.
Protección de marcadores de posición
Antes de la traducción, la sintaxis sensible se sustituye por tokens opacos para evitar corrupción por parte del LLM, aplicado en este orden (la restauración es el proceso inverso):
- Bloques de código delimitados (tres o más acentos graves o virgulillas, incluida una delimitación más larga que envuelve a una más corta): toda la delimitación, incluida la cadena de información, se reemplaza por
{{CDF_N}}y se mantiene en orden con los demás tokens estructurales. Esto mantiene las muestras dentro de contenedores como::: code-groupo::: tipen su sitio. Las cadenas de información de la delimitación (etiquetas de pestaña de VitePress) permanecen en el idioma de origen. Un delimitador de apertura sin cerrar se deja como texto para que no se absorba un delimitador de cierre de contenedor posterior. - Sufijos de ID de encabezado (
{#id}clásico /{/* #id */}de MDX al final de un encabezado ATX): se eliminan por completo de la línea y no se envían al modelo. Tras la restauración, se vuelven a fijar al final del encabezado correspondiente para que Docusaurus siga viendo un ID válido. Los comentarios a mitad de encabezado permanecen en el texto y son gestionados por las capas posteriores de MDX /{#…}. Los encabezados dentro de una delimitación enmascarada no se eliminan. - Etiquetas y comentarios HTML (
<strong>,<!-- ... -->, etc.): las etiquetas HTML en minúsculas de una lista de elementos permitidos conocida se reemplazan por tokens{{HTM_N}}. Las etiquetas JSX en mayúsculas (<Highlight>,<Tabs>,</Tab>) se gestionan por separado en la capa MDX (paso 6). - Marcadores de advertencia (
:::note,:::): solo el prefijo de la directiva en la línea de apertura se reemplaza por{{ADM_OPEN_N}}; cualquier título en la misma línea se deja para que el modelo lo traduzca. Se restauran con el texto original exacto. - Anclajes de documento (HTML
<a id="…">,{#…}de Docusaurus sobrante a mitad de encabezado): se conservan literalmente. - Construcciones exclusivas de MDX (
src/processors/mdx-placeholders.ts):- Comentarios de MDX (
{/* … */}, incluido un{/* #my-id */}a mitad de encabezado que no era un sufijo de final de línea) reemplazados por{{MDX_N}}. - Etiquetas JSX en mayúsculas (
<Highlight>,<Tabs>,<TabItem>,<TOCInline />,</Highlight>): se conservan como{{MDX_N}}con atributos de cadena traducibles (label,tooltip,aria-label) reescritos como{{JXA_N}}dentro de la etiqueta, a menos que el nombre del atributo aparezca endocs[].protectAttributes; también se extraenlabel:dentro de literales de objeto<Tabs values={[ { label: '…' } ]}>(se pueden omitir mediantedocs[].protectKeys) y<TabItem value="…">(cuando no existe ningún atributolabel, omitiendo los valores tipo slug en minúsculas). Se añaden al segmento como líneas||JXA_N: …||y se vuelven a fusionar medianterestoreMdx. - Expresiones entre llaves de MDX (
{frontMatter.title},style={{…}}): coincidencia sensible a la profundidad, reemplazadas por{{MDX_N}}.
- Comentarios de MDX (
- URL de Markdown (
](url),src="…"): se restauran desde un mapa después de la traducción. - Fragmentos de código en línea (
`code`) y código en línea envuelto en negrita (**code**): se conservan. - Énfasis de Markdown (opcional, habilitado automáticamente para configuraciones regionales CJK/RTL): delimitadores de énfasis enmascarados.
Después de que el modelo devuelva el resultado, translate-docs restaura los mapas y valida el segmento: debe estar presente el mismo multiconjunto de tokens de doble llave, los tokens estructurales ({{HTM_N}}, marcadores de advertencia, {{CDF_N}}) deben mantener su subsecuencia ordenada (los tokens de contenido como {{ILC_N}} / {{URL_N}} / {{SE}} pueden moverse con el orden de las palabras), los tipos de etiquetas HTML restauradas deben coincidir con el origen no protegido y cualquier identificador de doble llave sobrante ya debe haber existido en el origen (por lo que los tokens inventados fallan). La instrucción del documento también pide a los modelos que copien cada token una vez, mantengan el orden de los tokens estructurales y no inventen nuevos envoltorios de doble llave; las comprobaciones mecánicas siguen siendo las que prevalecen.
La protección compartida de atributos/claves para las plantillas Astro y MDX JSX se implementa en src/processors/expression-attribute-protection.ts y se controla por bloque mediante docs[].protectAttributes y docs[].protectKeys (consulte protectAttributes / protectKeys).
Caché (TranslationCache)
La base de datos SQLite (mediante node:sqlite) almacena filas indexadas por (source_hash, locale) con translated_text, model, filepath, last_hit_at y campos relacionados. El hash corresponde a los primeros 16 caracteres hexadecimales SHA-256 del contenido normalizado (espacios en blanco reducidos).
En cada ejecución, los segmentos se buscan por hash × configuración regional. Solo los fallos de caché van al LLM. Después de la traducción, last_hit_at se restablece para las filas de segmentos en el ámbito de traducción actual que no fueron alcanzadas. Los aciertos de caché exitosos durante la traducción de documentos eliminan las filas obsoletas de translation_failures para ese segmento.
cleanup ejecuta sync --force-update primero, luego:
- elimina filas de segmentos obsoletas (
last_hit_atnulo / ruta de archivo vacía); - purga claves de
file_trackingcuando la ruta de origen resuelta falta en el disco (doc-block:…,json-block:…,svg-files:…, etc.); - elimina filas de traducción cuya ruta de archivo de metadatos apunta a un archivo que falta;
- purga filas huérfanas de
translation_failures; - purga filas huérfanas de
markdown_source_issuescuya ruta de origen resuelta falta en el disco; - elimina filas de caché para configuraciones regionales ausentes de la configuración (
sourceLocale, raíztargetLocales, y cualquierdocs[]/json[]targetLocalespor bloque; solo SQLite — usapurge-localepara eliminar archivos generados).
No hace una copia de seguridad de cache.db a menos que se pase --backup <path>, lo que escribe una copia de seguridad en esa ruta primero.
Las llamadas al modelo facturadas (traducciones aceptadas y reintentos descartados) se almacenan en api_calls. Después de un comando que haya registrado llamadas, las filas de detalle con más de siete días naturales UTC pasan a las api_totals mensuales. usage y la vista de Uso y costos del panel combinan ambas tablas. Consulte Uso y costos.
Las notas Context del glosario y glossary.contextFiles se les asigna una huella digital (prompt_context_hash) y se inyectan en la interfaz de usuario, la documentación, JSON, SVG y las indicaciones de revisión. Cambiar esa guía invalida los segmentos en caché coincidentes y las filas de seguimiento de archivos en la siguiente ejecución. Las filas de caché del panel user-edited se mantienen. Cambiar solo una traducción preferida del glosario en una fila no forzada deja la caché existente en su lugar hasta --force / --force-update. Una fila Force no acierta en la caché solo para segmentos cuya fuente contiene ese término cuando el texto almacenado aún no incluye la traducción forzada, y se rechaza la omisión de archivos sin cambios para un archivo cuya salida aún no lo incluye. Deje Context vacío en esa fila; una nota de Contexto aún actualiza toda la configuración regional. Markdown también rechaza un segmento traducido que omite una etiqueta de interfaz de usuario citada de dos a cinco palabras (clave de catálogo o un prefijo con forma de etiqueta preestablecido). Una cita es texto en negrita, código en línea, un encabezado o una línea que es solo esa etiqueta. El uso de mayúsculas iniciales en una oración es una pista, para que la traducción pueda flexionarse (el hindi Cursor account puede convertirse en कर्सर खाते en lugar de la forma de diccionario कर्सर खाता). Una etiqueta de una sola palabra de contenido como Sign in sigue siendo una pista. La verificación ignora las mayúsculas en la traducción, por lo que una etiqueta en minúsculas en la oración sigue contando cuando la fuente la cita. La prosa ordinaria que utiliza las mismas palabras puede flexionarlas. Un prefijo preestablecido debe ser una etiqueta en mayúsculas cuya traducción compartida es una frase corta sin un marcador de posición; los inicios de oración no se preestablecen. Esa verificación reintenta el siguiente modelo y no divide el segmento.
El comando translate-docs también utiliza el seguimiento de archivos para que las fuentes sin cambios con salidas existentes y actualizadas puedan omitir el trabajo por completo. --check-cache vuelve a abrir las configuraciones regionales con un sistema de escritura esperado para que los segmentos en caché se vuelvan a validar; --force-update vuelve a ejecutar el procesamiento de archivos para cada configuración regional mientras sigue utilizando la caché de segmentos; --force borra el seguimiento de archivos y omite las lecturas de la caché de segmentos para la traducción de API. Cuando los modelos probados para un segmento de markdown fallan la validación AST, translate-docs puede dividir progresivamente el segmento y reintentar partes más pequeñas (docs[].segmentSplitting.qualityRetrySplit, activado por defecto). El mismo error de calidad tres veces finaliza esa lista de modelos antes de tiempo. Consulte Documentos — comportamiento de la caché y banderas para ver la tabla completa de banderas.
Formato de solicitud por lotes: translate-docs --prompt-format selecciona XML (<seg> / <t>) o formas de array/objeto JSON solo para LlmClient.translateDocumentBatch; la extracción, los marcadores de posición y la validación no cambian. Consulte Formato de solicitud por lotes.
Resolución de ruta de salida
resolveDocumentationOutputPath(config, cwd, locale, relPath, kind) mapea una ruta relativa a la fuente a la ruta de salida:
- Estilo
nested(predeterminado):{outputDir}/{locale}/{relPath}para Markdown. - Estilo
doc-system: bajodocsRoot, las salidas usan{outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}; las rutas fuera dedocsRootrecurren al diseño anidado. Alias:docusaurus(predeterminadolocaleSubpath= ruta del complemento Docusaurus),astro-starlight(localeSubpathvacío predeterminado),vitepress(igual quedoc-systemconlocaleSubpathvacío; conserva el uso de mayúsculas y minúsculas de la carpeta BCP-47). - Estilo
flat:{outputDir}/{stem}.{locale}{extension}. CuandoflatPreserveRelativeDirestrue, los subdirectorios de origen se mantienen bajooutputDir. - Personalizado
pathTemplate: cualquier diseño de Markdown que use{outputDir},{locale},{LOCALE},{relPath},{stem},{basename},{extension},{docsRoot},{relativeToDocsRoot}. - Personalizado
jsonPathTemplate: diseño personalizado separado para archivos JSON de etiquetas, usando los mismos marcadores de posición. linkRewriteDocsRootayuda al reescritor de enlaces planos a calcular los prefijos correctos cuando la salida traducida se encuentra en una ubicación distinta a la raíz del proyecto por defecto.
Reescritura plana de enlaces
Cuando docsOutput.style === "flat", los archivos markdown traducidos se colocan junto al origen con sufijos de configuración regional. Los enlaces relativos entre páginas se reescriben para que [Guide](./guide.md) en readme.de.md apunte a guide.de.md. Controlado por rewriteRelativeLinks (habilitado automáticamente para el estilo plano sin un pathTemplate personalizado). El mismo paso antepone un prefijo de profundidad por archivo a las URL de activos que no son markdown antes de que se ejecute postProcessing.regexAdjustments; consulte Reescritor de enlaces planos.
Internos de JSON
| Paso | Componente | Resultado |
|---|---|---|
| 1 | json[].contentPaths | Archivos resueltos (archivo, directorio o glob) |
| 2 | NestedJsonExtractor | Hojas de cadena seleccionadas por keyPolicy (rutas de puntos + minimatch) |
| 3 | PlaceholderHandler + lote + TranslationCache | Acierto de caché → omitir; fallo → LlmClient.translateDocumentBatch (SQLite compartido) |
| 4 | NestedJsonExtractor.reassemble | Archivo de salida a través de expandJsonBlockOutputPath(outputPathTemplate) |
NestedJsonExtractor(src/extractors/nested-json-extractor.ts) recorre JSON anidado arbitrario y emite un segmento por cada hoja de cadena translatable.keyPolicy.mode(allowlist,denylistoboth) filtra rutas con minimatch en notación de puntos (nombres sin procesar comoslugcoinciden con el segmento de clave final).- La pista de archivo de caché utiliza
json-block:{blockIndex}:{projectRelPath}enfile_tracking(mismocacheDirque documentos y SVG). - No para catálogos de Docusaurus
write-translations(forma{ message, description }) — esos usan Documentos (docs[].docusaurusCatalogDir+JsonExtractordentro detranslate-docs). - No para cadenas de interfaz de usuario
t()— cadenas de interfaz de usuario (strings.json+ paquetes planos). - CLI:
translate-json; orquestación ensrc/cli/translate-json-run.ts. Plantilla de inicio:ui-json-bundles.
Infraestructura compartida
LlmClient
Cliente de chat independiente del proveedor construido sobre el SDK de IA de Vercel (ai + @ai-sdk/openai-compatible). Resuelve el proveedor activo desde provider / providers, construye un cliente compatible con OpenAI (createOpenAICompatible) para baseUrl y la clave API de ese proveedor, y enruta todas las llamadas a través de generateText. OpenRouterClient se mantiene como un alias obsoleto. Comportamientos clave:
- Reserva de modelo: intenta cada modelo de la lista resuelta en orden; recurre a otro en caso de fallos de solicitud o de análisis. Cada configuración regional de destino obtiene su propia cadena resuelta:
localeModels(locale)primero cuando está configurado, luegouiModels(solo para pipelines de interfaz de usuario), luegotranslationModels. La traducción de documentos, JSON y SVG crea un cliente por configuración regional con la cadena que no es de interfaz de usuario. El comandobench-modelsen su lugar crea un cliente de un solo modelo por ID configurado (unión detranslationModels,uiModelsylocaleModels;translationModels: [id], sin reserva) para que pueda cronometrar y fijar el precio de cada modelo de forma independiente. - Tiempo de espera de la solicitud:
requestTimeout(segundos) orequestTimeoutMsen el proveedor activo; de lo contrario, las mismas claves en la parte superior de la configuración (120 segundos por defecto), interrumpe cada solicitud a través deAbortSignal.timeout. El mismo valor se aplica aGET /modelscuando la CLI carga la lista de modelos de un proveedor paracheck-models(cualquier proveedor). El filtro opcional previo al vuelo que descarta los ID de modelo desconocidos se ejecuta solo cuando el proveedor activo es OpenRouter. - Extras de OpenRouter (solo cuando
openrouterestá activo): enrutamiento de rendimiento a través del campo de solicitudprovidery los encabezadosHTTP-Referer/X-Title. El uso de tokens se informa para cada proveedor. OpenRouter y Cheaper Inference también devuelven un importe facturado en USD (usage.cost; Cheaper Inference recurre acheaper_inference.billing.billed_cost_usd). Cuando el proveedor omite ese importe, el coste en USD se calcula a partir deproviders.<name>.modelPricing, luego el valor predeterminadopricingde todo el proveedor, luego el precio de lista de entrada y salida de models.dev, y se almacena en la filaapi_calls. Un coste informado por el proveedor (incluido0) nunca se reemplaza. El coste desconocido permanece sin establecer. La tarificación de una llamada lee solo la parte de models.dev de<cacheDir>/benchmark-scores.json; no descarga languagebench ni el archivo Arena. - Registro de tráfico de depuración: si
debugTrafficFilePathestá configurado, añade JSON de solicitud y respuesta a un archivo (programático). La CLI--debug-failedescribe archivosFAILED-TRANSLATIONencacheDircon la solicitud del sistema/usuario, la respuesta bruta del asistente y los errores de validación para los intentos fallidos de verificación de traducción de UI, documentos, JSON y SVG. Los fallos de la API del proveedor o de cuerpo vacío se imprimen en la consola en lugar de volcar un archivo solo con la solicitud.
suggest-models y la pestaña Modelos del panel de control no llaman al LLM. Clasifican el catálogo de chat del proveedor activo con un índice de calidad de languagebench ChrF y LMArena Arena Score. El precio es una tasa combinada de 3:1 de USD por 1 millón de tokens (catálogo, luego models.dev, luego languagebench). --quality ordena por índice; --price recorre la frontera de Pareto de calidad-precio. Opcionalmente reemplazan providers.<name>.translationModels. Los agregados residen en <cacheDir>/benchmark-scores.json. Consulte Modelos de IA y suggest-models.
Carga de configuración
Canalización loadI18nConfigFromFile(configPath, cwd):
- Leer y analizar
ai-i18n-tools.config.json(JSON). mergeWithDefaults- fusión profunda condefaultI18nConfigPartial, y fusión de cualquier entradadocs[].sourceFilesencontentPaths.expandTargetLocalesFileReferenceInRawInput- convertirtargetLocalesa una matriz y rechazar entradas tipo ruta (deben ser códigos BCP-47, no una ruta aui-languages.json);languagesManifestPathpor defecto es{ui.flatOutputDir}/ui-languages.jsondurantemergeWithDefaults.expandDocumentationTargetLocalesInRawInput- lo mismo para cada entradadocs[].targetLocales.expandJsonTargetLocalesInRawInput- igual para cada entrada dejson[].targetLocales.parseI18nConfig- validación Zod +validateI18nBusinessRules.applyProviderOverrideToRawInput- cuando-P/--providerse pasa en la CLI.applyEnvOverrides- aplicarOPENROUTER_BASE_URL,OLLAMA_BASE_URL,I18N_SOURCE_LOCALEyI18N_TARGET_LOCALEScuando estén configurados (las claves API se resuelven por separado por proveedor dentro deLlmClient).augmentConfigWithUiLanguagesMaster- adjuntar nombres de visualización de manifiesto del catálogo maestro incluido.assertEffectiveLocalesInUiLanguagesMaster- validar códigos de configuración regional contra el catálogo maestro cuando corresponda.
init escribe configuraciones de inicio desde initConfigTemplates: ui-markdown (cadenas de interfaz de usuario más un bloque README plano), docs-markdown (solo README y Markdown), ui-docusaurus, ui-starlight, ui-vitepress (documentos de VitePress + vitepressThemeCatalog), ui-nextra (documentos de Nextra + nextraDictionaryPath), ui-astro-website (interfaz de usuario de Astro simple; añade docs[] para la traducción de páginas de .astro), ui-json-bundles (solo json[] JSON), ui-python, ui-python-gettext, ui-python-django y ui-python-flask. --with-readme añade ese mismo bloque README a cualquier plantilla que no liste ya README.md, y activa translateDocs. Consulta Cadenas de interfaz de usuario — Inicializar, Añadir i18n a tu README y documentos Markdown y Aplicaciones Python.
Registrador (Logger)
Logger admite niveles debug, info, warn, error con salida de colores ANSI. El modo detallado (-v) habilita debug. Cuando se establece logFilePath, las líneas de registro también se escriben en ese archivo.
Autolocalización (interfaz de usuario de la herramienta)
La herramienta localiza su propia interfaz de usuario — la ayuda de la CLI, los mensajes de registro/resumen/error de alto tráfico y el Panel de traducción — por separado del contenido que traduce para ti.
- Resolución de configuración regional (
resolveUiLocaleensrc/core/ui-locale.ts): selecciona la configuración regional de la interfaz de usuario de-L/--ui-lang>AI_I18N_LANG> configuraciónuiLanguage> configuración regional del sistema operativo host (Intl.DateTimeFormat().resolvedOptions().locale). El candidato se normaliza y se compara con el conjunto de paquetes distribuidos, ya sea exactamente o por la variación más cercana (p. ej.,pt-PT→pt-BR,en-US→en-GB), recurriendo a la configuración regional de origen (en-GB). La CLI resuelve una vez antes de que se construya la ayuda (escaneo de argv previo al análisis) y de nuevo después de la carga de configuración para que se apliqueuiLanguage(la bandera y la variable de entorno siguen prevaleciendo). - Tiempo de ejecución (
src/i18n/index.ts): unt(source, vars)mínimo con interpolación{{name}}, indexado por la cadena de origen en inglés contra paquetes planos por configuración regional ensrc/i18n/locales/<code>.json(copiado adist/i18n/localesen la compilación). Las claves o paquetes que faltan devuelven el texto de origen. Este es el mismo modelo de clave como predeterminado que las cadenas de la interfaz de usuario — no hay búsqueda por hash. - Panel de control: el servidor expone
GET /api/ui-i18nque devuelve{ locale, dir, bundle }para la configuración regional de la interfaz de usuario resuelta; el frontend establece<html lang>/diry localiza el marcado estático a través de atributosdata-i18n*. - Dogfooding: los paquetes son producidos por
pnpm i18n:self(sync-ui --ui-block src/i18n/strings.json), que extrae y traduce el bloqueuide la CLI y del panel de control enai-i18n-tools.config.json. Las claves del catálogo provienen de llamadas at()ensrc/cli/ysrc/i18n/más los marcadoresdata-i18n*del panel de control ensrc/dashboard-app/index.html.
Puntos de extensión
Nombres personalizados de funciones (extracción de interfaz de usuario)
Agrega nombres no estándar de funciones de traducción mediante la configuración:
{
"ui": {
"uiExtractor": {
"funcNames": ["t", "i18n.t", "translate", "i18n.translate"],
"extensions": [".js", ".jsx", ".ts", ".tsx", ".astro", ".html"],
"htmlI18nAttributes": ["data-i18n", "data-i18n-title", "data-i18n-placeholder", "data-i18n-alt", "data-i18n-aria-label"]
}
}
}(ui.reactExtractor es un alias completamente compatible para ui.uiExtractor.)
Añade .html / .htm a extensions para escanear atributos de marcador HTML durante la extract. ui.uiExtractor.htmlI18nAttributes es opcional y por defecto es ["data-i18n", "data-i18n-title", "data-i18n-placeholder"]; data-i18n se mapea al textContent del elemento y data-i18n-<attr> se mapea al valor de ese atributo (p. ej., data-i18n-aria-label).
Extractores personalizados
Implementa ContentExtractor desde el paquete:
import { BaseExtractor, type Segment } from 'ai-i18n-tools';
class MyExtractor extends BaseExtractor {
readonly name = 'my-format';
canHandle(filepath: string) { return filepath.endsWith('.myext'); }
extract(content: string, filepath: string): Segment[] { /* … */ }
reassemble(segments: Segment[], translations: Map<string, string>): string { /* … */ }
}Registre extractores personalizados extendiendo las clases de extractor públicas exportadas desde 'ai-i18n-tools' (por ejemplo, subclase MarkdownExtractor). La CLI conecta los extractores incorporados internamente; no hay una importación profunda compatible de doc-translate.ts.
Rutas de salida personalizadas
Use docsOutput.pathTemplate para cualquier disposición de archivos:
{
"docs": [
{
"docsOutput": {
"pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
}
}
]
}Árbol de origen
Diseño completo de src/ (referencia a nivel de archivo)
src/
├── index.ts Public API re-exports
│
├── cli/
│ ├── index.ts CLI entry point (commander)
│ ├── extract-strings.ts `extract` command implementation
│ ├── mark-html.ts `mark-html` command (insert bare `data-i18n*` markers into HTML)
│ ├── translate-ui-strings.ts `translate-ui` command implementation
│ ├── doc-translate.ts `translate-docs` command (documentation files only)
│ ├── translate-json-run.ts `translate-json` command (`json[]` nested locale bundles)
│ ├── translate-svg.ts `translate-svg` command (SVG files from `config.svg`)
│ ├── write-heading-ids.ts `write-heading-ids` command (markdown heading anchors)
│ ├── bench-models.ts `bench-models` command (per-model translate latency/token/cost benchmark)
│ ├── helpers.ts Shared CLI utilities
│ └── file-utils.ts File collection helpers
│
├── markdown/
│ └── write-heading-ids-core.ts Slug styles + `<a id="…">` insertion for `write-heading-ids`
│
├── core/
│ ├── types.ts Zod schemas + TypeScript types for all config shapes
│ ├── config.ts Config loading, merging, validation, init templates
│ ├── cache.ts SQLite translation cache (node:sqlite)
│ ├── prompt-builder.ts LLM prompt construction for docs and UI strings
│ ├── output-paths.ts Docusaurus / flat output path resolution
│ ├── ui-languages.ts ui-languages.json loading and locale resolution
│ ├── ui-locale.ts Resolve the tool's own UI locale (flag/env/config/OS → shipped bundle)
│ ├── locale-utils.ts BCP-47 normalisation, locale list parsing, script/Han-variant validation
│ └── errors.ts Typed error classes
│
├── extractors/
│ ├── base-extractor.ts Abstract base class for all extractors
│ ├── ui-string-extractor.ts JS/TS and `.astro` UI scanner (Babel via `ui-string-babel.ts`)
│ ├── ui-string-babel.ts Babel `t()` discovery (`extractUiCallsFromFileContent`)
│ ├── ui-string-locations.ts Source locations for extracted UI strings
│ ├── html-i18n-marks.ts HTML `data-i18n*` marker scanner + `mark-html` annotator
│ ├── classify-segment.ts Heuristic segment type classification
│ ├── markdown-extractor.ts Markdown / MDX segment extraction
│ ├── markdown-segment-split.ts Optional segment splitting for long markdown blocks
│ ├── frontmatter-fields.ts Selective YAML front matter field translation
│ ├── astro-template-extractor.ts `.astro` parse-and-replace (HTML + template expressions; used by `translate-docs`)
│ ├── json-extractor.ts Docusaurus catalog JSON extraction (`translate-docs`)
│ ├── nested-json-extractor.ts Arbitrary nested JSON leaves (`translate-json`, `json[]`)
│ └── svg-extractor.ts SVG text extraction
│
├── processors/
│ ├── placeholder-handler.ts Chain: HTML → admonitions → anchors → MDX → URLs → emphasis
│ ├── expression-attribute-protection.ts Shared protected attribute/key lists (Astro + MDX JSX)
│ ├── url-placeholders.ts Markdown URL protection/restore
│ ├── admonition-placeholders.ts Docusaurus admonition protection/restore
│ ├── anchor-placeholders.ts HTML anchor / heading ID protection/restore
│ ├── html-tag-placeholders.ts Lowercase HTML tag / comment protection ({{HTM_N}})
│ ├── placeholder-integrity.ts Pre/post-restore token sequence + tag-kind + invented {{IDENT}} checks
│ ├── mdx-placeholders.ts MDX comments, JSX tags, brace expressions, JSX attribute extraction
│ ├── batch-processor.ts Segment → batch grouping (count + char limits)
│ ├── validator.ts Post-translation structural checks
│ └── flat-link-rewrite.ts Relative link rewriting for flat output
│
├── api/
│ ├── llm-client.ts LlmClient: provider-agnostic chat client (AI SDK) with model fallback chain
│ └── provider-models-catalog.ts Fetch/parse any provider's OpenAI-compatible GET /models catalog
│
├── glossary/
│ ├── glossary.ts Glossary loading (CSV + auto-build from strings.json)
│ ├── matcher.ts Term hint extraction for prompts
│ └── translation-context.ts contextFiles loader and guidance fingerprints
│
├── runtime/
│ ├── index.ts Runtime re-exports
│ ├── template.ts interpolateTemplate, flipUiArrowsForRtl
│ ├── ui-language-display.ts getUILanguageLabel, getUILanguageLabelNative
│ └── i18next-helpers.ts RTL detection, i18next setup factories
│
├── i18n/ Self-localisation runtime for the tool's own UI
│ ├── index.ts t(source, vars) + bundle/manifest loaders (keyed by English source string)
│ └── locales/ Shipped UI bundles (de.json, es.json, …; generated by `pnpm i18n:self`)
│
├── dashboard-app/
│ ├── index.html Translation Dashboard static UI (HTML/CSS/JS)
│ ├── app.js
│ └── styles.css
│
├── server/
│ └── translation-dashboard.ts Express app for Translation Dashboard (cache / strings.json / glossary)
│
└── utils/
├── logger.ts Leveled logger with ANSI support
├── hash.ts Segment hash (SHA-256 first 16 hex)
├── table.ts Display-width aware table rendering (CJK/emoji column alignment)
├── load-dotenv.ts Load `.env` / `.env.local` beside the config when no API key is set
└── ignore-parser.ts .translate-ignore file parser