JSON
Dirigido a: proyectos que ya guardan el contenido en archivos JSON anidados por idioma (por ejemplo, src/i18n/en/translation.json) y quieren mantener esa estructura. Si tu fuente tiene texto plano y aún no tiene t(), empieza en Añadir i18n a una aplicación JS/TS en su lugar.
La CLI recorre los valores de cadena de esos archivos, los traduce con los modelos del proveedor de LLM activo y escribe los resultados por configuración regional usando json[].outputPathTemplate. Utiliza la misma caché de SQLite que translate-docs y translate-svg (cacheDir).
Este pipeline no ejecuta extract; no hay un catálogo strings.json. Habilítelo con features.translateJson y una o más entradas en el json[] de nivel superior.
Anulaciones de modelo por configuración regional
translate-json resuelve los modelos por configuración regional de destino: primero localeModels(locale) cuando está configurado y, a continuación, translationModels. Utiliza esta opción para paquetes JSON anidados en los que determinadas configuraciones regionales se benefician de modelos dedicados, por ejemplo, los archivos de tema zh-Hans / zh-Hant. Consulta Modelos de IA.
Paso 1: Inicializar para JSON anidado
ai-i18n-tools init -t ui-json-bundles -P ollamaEsa plantilla configura features.translateJson: true, deshabilita la extracción de la interfaz de usuario y la traducción de documentos, y estructura un único bloque json[] que apunta a src/i18n/en/translation.json con la salida src/i18n/{llocale}/translation.json. También incluye el bloque provider / providers para el preajuste que pasas con -P — establece la clave de API correspondiente (o usa Ollama local) antes de ejecutar translate-json o sync; consulta Proveedor y clave de API. Edita sourceLocale, targetLocales, contentPaths y outputPathTemplate para el diseño de tu repositorio.
Paso 2: Configurar json[]
Cada bloque json[] describe una canalización:
contentPaths— uno o más archivos.json, directorios o patrones (por ejemplo,"src/i18n/en/translation.json"o"src/i18n/en/overrides/*.json"). Las rutas se resuelven desde la raíz del proyecto.outputPathTemplate— obligatorio. Dónde escribir cada archivo por configuración regional. Marcadores de posición:{locale},{LOCALE},{llocale}(configuración regional en minúsculas, útil para carpetas de rutas de Astro),{stem},{basename},{extension},{relativeToSourceRoot}.targetLocales(opcional) — subconjunto solo para este bloque; si no, se aplica eltargetLocalesraíz.keyPolicy— qué claves JSON contienen texto traducible frente a identificadores estables (ver más abajo).description(opcional) — se muestra en los encabezados de la CLI y en la salida destatus.
Ejemplo (múltiples archivos de origen, carpetas de configuración regional en minúsculas):
{
"sourceLocale": "en",
"targetLocales": ["de", "fr", "pt-BR"],
"features": {
"translateJson": true
},
"cacheDir": ".translation-cache",
"json": [
{
"description": "App UI bundle",
"contentPaths": [
"src/i18n/en/translation.json",
"src/i18n/en/overrides/*.json"
],
"outputPathTemplate": "src/i18n/{llocale}/{basename}",
"keyPolicy": {
"mode": "denylist",
"skipKeys": ["id", "slug", "href", "url", "key", "code"],
"translateKeys": []
}
}
]
}keyPolicy
mode | Comportamiento |
|---|---|
allowlist | Solo se traducen las claves que coincidan con translateKeys (rutas con puntos; patrones minimatch). |
denylist | Traduce todos los valores de cadena excepto las claves que coincidan con skipKeys. |
both | Aplica primero translateKeys, luego elimina las coincidencias de skipKeys. |
Las rutas usan notación con puntos (nav.home.label). Un nombre simple como slug coincide con el segmento final de la clave a cualquier profundidad.
Paso 3: Traducir paquetes JSON
ai-i18n-tools translate-jsonMarcadores opcionales (las mismas ideas que translate-docs): -l / --locale para un subconjunto de destinos, -p / --path para limitar archivos, --dry-run, --force (borrar el seguimiento de archivos y la caché de segmentos para los archivos coincidentes), --force-update (volver a procesar cuando el hash del archivo coincide; la caché de segmentos sigue aplicándose), --check-cache (volver a validar los segmentos en caché para las configuraciones regionales con un script nativo forzado incluso cuando el seguimiento de archivos coincide), -b / --batch-concurrency, --prompt-format (xml | json-array | json-object).
Los proyectos solo JSON pueden ejecutar:
ai-i18n-tools sync --no-ui --no-svg --no-docsCuando también están habilitadas la interfaz de usuario o la documentación, sync ejecuta translate-json después de translate-docs (a menos que se use --no-json). Omita JSON con --no-json.
Verifique la cobertura por archivo y configuración regional:
ai-i18n-tools statusCuando translateJson está activado, status imprime una sección json[] (✓ actualizada, ● obsoleta o ausente).
JSON vs. otros pipelines
| Situación | Uso |
|---|---|
Cadenas de UI en t("…") / i18n.t("…") en JS/TS/Astro | Cadenas de UI — extract + translate-ui |
Catálogo Docusaurus write-translations ({ "key": { "message": "…", "description": "…" } }) | Documentos — docs[].docusaurusCatalogDir + translate-docs, no json[] |
| Cadenas de tema/navegación/barra lateral de VitePress | Documentos — docsOutput.vitepressThemeCatalog + translate-docs; no use json[] — consulte Integración de VitePress |
Etiquetas _meta.ts de Nextra y diccionario de temas .ts | Documentos — translate-docs (_meta automático cuando style: "nextra", nextraDictionaryPath opcional); no use json[] — consulte Integración de Nextra |
Etiquetas meta.json de Fumadocs y catálogo de anulaciones de UI | Documentos — translate-docs (meta.json automático cuando style: "fumadocs", fumadocsUiCatalog opcional); no use json[] — consulte Integración de Fumadocs |
JSON de configuración regional anidada independiente (árboles translation.json estilo ZenBrowser) | JSON — json[] + translate-json |
Archivos de espacio de nombres de i18next (public/locales/en/common.json, tokens {{name}}, sufijos key_one / key_other) | JSON — json[] + translate-json (ver archivos de espacio de nombres de i18next) |
Diccionarios Intlayer *.content.ts + useIntlayer (migrar de Intlayer) | Migrar de Intlayer — migrate-intlayer, luego cadenas de interfaz de usuario |
Diccionarios Intlayer *.content.ts (mantener Intlayer, rellenar traducciones) | Traducir Intlayer in situ — translate-intlayer |
Archivos .svg ilustrados con <text> / <title> / <desc> | features.translateSVG + svg + translate-svg (opcional; no es una de las tres tuberías principales) |
Referencia de campo: json en Referencia de configuración. Las claves de caché para la limpieza usan json-block:{blockIndex}:{projectRelPath} en file_tracking.
Archivos de espacio de nombres de i18next
La canalización JSON cubre los archivos de configuración regional de clave/valor típicos de i18next: objetos anidados, matrices de cadenas, interpolación de {{name}} en los valores y claves de sufijo plural independientes (welcome_one, welcome_other). No re escribe los sitios de llamada de t("some.key"); estos permanecen basados en claves. Para migrar un proyecto al esquema de cadena de origen t() de ai-i18n-tools, cambie los sitios de llamada a t("source text"). El texto está escrito en sourceLocale, que puede ser cualquier idioma. Cuando el origen es Intlayer .content.ts, ejecute migrate-intlayer. Para mantener Intlayer y solo traducir sus diccionarios, utilice translate-intlayer.
Ejemplo (espacios de nombres de origen en inglés en public/locales/en/):
{
"sourceLocale": "en",
"targetLocales": ["de", "fr", "pt-BR"],
"features": { "translateJson": true },
"json": [
{
"description": "i18next namespaces",
"contentPaths": ["public/locales/en/*.json"],
"outputPathTemplate": "public/locales/{locale}/{basename}"
}
]
}key_one / key_other / key_zero (y otros sufijos CLDR) se traducen como hojas separadas. Eso es suficiente para que i18next siga resolviendo los plurales por sufijo; la canalización no los reagrupa en una sola fila del catálogo.