Skip to content

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 ​

bash
ai-i18n-tools init -t ui-json-bundles -P ollama

Esa 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 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):

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

modeComportamiento
allowlistSolo se traducen las claves que coincidan con translateKeys (rutas con puntos; patrones minimatch).
denylistTraduce todos los valores de cadena excepto las claves que coincidan con skipKeys.
bothAplica 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 ​

bash
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:

bash
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:

bash
ai-i18n-tools status

Cuando translateJson está activado, status imprime una sección json[] (✓ actualizada, ● obsoleta o ausente).

JSON vs. otros pipelines ​

SituaciónUso
Cadenas de UI en t("…") / i18n.t("…") en JS/TS/AstroCadenas 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 VitePressDocumentos — docsOutput.vitepressThemeCatalog + translate-docs; no use json[] — consulte Integración de VitePress
Etiquetas _meta.ts de Nextra y diccionario de temas .tsDocumentos — 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 UIDocumentos — 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/):

json
{
  "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.

Publicado bajo la licencia MIT.