JSON

Diseñado para proyectos que mantienen las copias de la interfaz de usuario en archivos JSON anidados por configuración regional (por ejemplo, src/i18n/en/translation.json) en lugar de t("…") en el código fuente. La CLI recorre los valores de cadena en esos archivos, los traduce a través del proveedor de LLM activo y escribe las salidas 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, luego translationModels. Utilice esto para paquetes JSON anidados donde ciertas configuraciones regionales se benefician de modelos dedicados, por ejemplo, archivos de tema zh-Hans / zh-Hant. Consulte Proveedores y modelos.

Paso 1: Inicializar para JSON anidado

ai-i18n-tools init -t ui-json-bundles [-P <provider>]

Esa plantilla establece 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 salida src/i18n/{llocale}/translation.json. También incluye un bloque predeterminado provider / providers (openrouter a menos que pases -P <provider>) — establece la clave API coincidente (o usa Ollama local) antes de ejecutar translate-json o sync; consulta Proveedor y clave 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 el targetLocales raí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 de status.

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-json

Marcadores 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-docs

Cuando 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 status

Cuando 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 de Intlayer *.content.ts + useIntlayer	Migración desde Intlayer — migrate-intlayer, luego cadenas de interfaz de usuario
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 clave/valor típicos de i18next: objetos anidados, matrices de cadenas, interpolación {{name}} en valores y claves de sufijo plural independientes (welcome_one, welcome_other). No reescribe los sitios de llamada t("some.key"); estos permanecen basados en claves. Para mover un proyecto al esquema t() de cadena de origen en inglés de ai-i18n-tools, cambie los sitios de llamada a t("English text") (o ejecute migrate-intlayer cuando el origen sea Intlayer .content.ts).

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.