Skip to content

JSON ​

Para quem se destina: projetos que já mantêm o texto em arquivos JSON aninhados por localidade (por exemplo, src/i18n/en/translation.json) e desejam manter esse layout. Se seu código-fonte tiver texto simples e ainda não tiver t(), comece em Adicionar i18n a um app JS/TS.

A CLI percorre os valores de string nesses arquivos, os traduz com os modelos no provedor de LLM ativo e grava as saídas por localidade usando json[].outputPathTemplate. Ela usa o mesmo cache SQLite que o translate-docs e o translate-svg (cacheDir).

Este pipeline não executa extract — não há catálogo strings.json. Habilite-o com features.translateJson e uma ou mais entradas no json[] de nível superior.

Substituições de modelo por localidade ​

translate-json resolve modelos por localidade de destino: primeiro localeModels(locale) quando configurado, depois translationModels. Use isso para pacotes JSON aninhados em que determinadas localidades se beneficiam de modelos dedicados — por exemplo, arquivos de tema zh-Hans / zh-Hant. Consulte Modelos de IA.

Etapa 1: Inicializar para JSON aninhado ​

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

Esse modelo define features.translateJson: true, desabilita a extração de UI e a tradução de documentos, e estrutura um único bloco json[] apontando para src/i18n/en/translation.json com saída src/i18n/{llocale}/translation.json. Ele também inclui o bloco provider / providers para o preset que você passa com -P — defina a chave de API correspondente (ou use o Ollama local) antes de executar translate-json ou sync; consulte Provedor e chave de API. Edite sourceLocale, targetLocales, contentPaths e outputPathTemplate para o layout do seu repositório.

Etapa 2: Configurar json[] ​

Cada bloco json[] descreve um pipeline:

  • contentPaths — um ou mais arquivos .json, diretórios ou padrões glob (por exemplo, "src/i18n/en/translation.json" ou "src/i18n/en/overrides/*.json"). Os caminhos são resolvidos a partir da raiz do projeto.
  • outputPathTemplate — obrigatório. Local onde cada arquivo de localidade de destino será escrito. Marcadores: {locale}, {LOCALE}, {llocale} (localidade em minúsculas, útil para pastas de rotas do Astro), {stem}, {basename}, {extension}, {relativeToSourceRoot}.
  • targetLocales (opcional) — subconjunto apenas para este bloco; caso contrário, o targetLocales raiz será aplicado.
  • keyPolicy — quais chaves JSON contêm texto traduzível versus identificadores estáveis (veja abaixo).
  • description (opcional) — exibido nos cabeçalhos da CLI e na saída status.

Exemplo (múltiplos arquivos de origem, pastas de localidade em 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

modeComportamento
allowlistApenas chaves que correspondem a translateKeys (caminhos com ponto; padrões minimatch) são traduzidas.
denylistTraduz todos os valores string, exceto chaves que correspondem a skipKeys.
bothAplica primeiro translateKeys, depois remove correspondências de skipKeys.

Os caminhos usam notação por pontos (nav.home.label). Um nome simples como slug corresponde ao último segmento da chave em qualquer profundidade.

Etapa 3: Traduzir pacotes JSON ​

bash
ai-i18n-tools translate-json

Sinalizadores opcionais (mesmas ideias que translate-docs): -l / --locale para um subconjunto de destinos, -p / --path para limitar arquivos, --dry-run, --force (limpar rastreamento de arquivos e cache de segmento para arquivos correspondentes), --force-update (reprocessar quando o hash do arquivo corresponder; o cache de segmento ainda se aplica), --check-cache (revalidar segmentos em cache para localidades com um script nativo imposto, mesmo quando o rastreamento de arquivos corresponder), -b / --batch-concurrency, --prompt-format (xml | json-array | json-object).

Projetos apenas com JSON podem executar:

bash
ai-i18n-tools sync --no-ui --no-svg --no-docs

Quando a interface ou documentos também estão habilitados, sync executa translate-json após translate-docs (a menos que --no-json). Pule o JSON com --no-json.

Verifique a cobertura por arquivo e localidade:

bash
ai-i18n-tools status

Quando translateJson está ativado, status imprime uma seção json[] (✓ atualizado, ● desatualizado ou ausente).

JSON vs outros pipelines ​

SituaçãoUso
Strings da UI em t("…") / i18n.t("…") em JS/TS/AstroStrings da UI — extract + translate-ui
Catálogo Docusaurus write-translations ({ "key": { "message": "…", "description": "…" } })Documentos — docs[].docusaurusCatalogDir + translate-docs, não json[]
Strings de tema/navegação/barra lateral do VitePressDocumentos — docsOutput.vitepressThemeCatalog + translate-docs; não use json[] — consulte integração VitePress
Rótulos _meta.ts do Nextra e dicionário de tema .tsDocumentos — translate-docs (_meta automático quando style: "nextra", nextraDictionaryPath opcional); não use json[] — consulte integração Nextra
Rótulos meta.json do Fumadocs e catálogo de substituições de IUDocumentos — translate-docs (meta.json automático quando style: "fumadocs", fumadocsUiCatalog opcional); não use json[] — consulte integração Fumadocs
JSON de localidade aninhada autônoma (árvores translation.json estilo ZenBrowser)JSON — json[] + translate-json
arquivos de namespace i18next (public/locales/en/common.json, {{name}} tokens, sufixos key_one / key_other)JSON — json[] + translate-json (consulte arquivos de namespace i18next)
Dicionários *.content.ts do Intlayer + useIntlayer (migrar do Intlayer)Migrando do Intlayer — migrate-intlayer, depois, strings de UI
Dicionários *.content.ts do Intlayer (manter o Intlayer, preencher traduções)Traduzindo o Intlayer no local — translate-intlayer
Arquivos .svg ilustrados com <text> / <title> / <desc>features.translateSVG + svg + translate-svg (opcional; não é um dos três pipelines principais)

Referência de campo: json em Referência de configuração. As chaves de cache para limpeza usam json-block:{blockIndex}:{projectRelPath} em file_tracking.

Arquivos de namespace i18next ​

O pipeline de JSON abrange arquivos de localidade de chave/valor típicos do i18next: objetos aninhados, arrays de strings, interpolação {{name}} em valores e chaves de sufixo de plural independentes (welcome_one, welcome_other). Ele não reescreve os locais de chamada de t("some.key") — eles permanecem baseados em chave. Para migrar um projeto para o esquema de string de origem t() do ai-i18n-tools, altere os locais de chamada para t("source text"). O texto é escrito em sourceLocale, que pode ser qualquer idioma. Quando a origem for o Intlayer .content.ts, execute migrate-intlayer. Para manter o Intlayer e apenas traduzir seus dicionários, use translate-intlayer.

Exemplo (namespaces de origem em inglês em 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 (e outros sufixos CLDR) são traduzidos como folhas separadas. Isso é suficiente para o i18next continuar resolvendo plurais por sufixo; o pipeline não os reagrupa em uma única linha de catálogo.

Lançado sob a Licença MIT.