Skip to content

Strings da UI ​

Referência para extract e translate-ui, o pipeline que transforma chamadas t() em catálogos por localidade. Adicionando i18n a um aplicativo pela primeira vez? Comece em Adicionar i18n a um aplicativo JS/TS, Adicionar i18n a um aplicativo Python ou Adicionar i18n a um aplicativo .NET. Eles cobrem a etapa de encapsulamento e, em seguida, o enviam de volta aqui para as Etapas 2 a 4.

Este pipeline atende a projetos JS/TS (React, componentes de cliente e servidor Next.js, serviços Node.js, HTML simples, sites Astro e ferramentas CLI), aplicativos Python e aplicativos .NET. JS/TS pesquisa strings com i18next depois que o código-fonte chama t(). Python chama t() ou gettext por meio de um i18n.py gerado (Django mantém o gettext do Django). .NET chama T() por meio de um I18n.cs gerado.

Qual guia ler ​

Seu appLeia a seguir
JS/TS com strings de origem codificadas diretamente, ainda sem t()Adicionar i18n a um app JS/TS
React / Next.js / Node, t() já no código-fonteConectar o i18next
Python (t(), _(), gettext, Jinja, Django)Aplicações Python. Inicialização: ui-python, ui-python-gettext, ui-python-flask, ou ui-python-django. Auxiliar: i18n.py. Para adicionar localidades a um aplicativo existente, consulte Adicionar i18n a um aplicativo Python, ou Adicionar i18n a um aplicativo Django / Python gettext quando o aplicativo usa gettext.
.NET (T(), Tn, Tp, XAML loc:Tr)Aplicativos .NET. Inicialização: ui-dotnet (I18n.cs) ou ui-dotnet-resx (Adicionar i18n a um aplicativo .NET ResourceManager). Para adicionar localidades a um aplicativo existente, consulte Adicionar i18n a um aplicativo .NET.
HTML puro (sem t() na marcação)Aplicativos HTML puros
Site de marketing Astro (híbrido)Site Astro
Regras de t(), interpolação, pluraisChamadas t() e plurais
Seletor de idioma / RTLSeletor de idioma e RTL
Assinaturas da API de tempo de execuçãoAjudantes de tempo de execução
Dicionários .content.ts do Intlayer, migrando do IntlayerMigrando do Intlayer
Dicionários .content.ts do Intlayer, mantendo o IntlayerTraduzindo o Intlayer no local

Passo 1: Inicializar ​

bash
ai-i18n-tools init -P openrouter

Isso grava ai-i18n-tools.config.json com o modelo ui-markdown (incluindo o bloco provider / providers dessa predefinição). Esse modelo também ativa a tradução de documentos para README.md, gravados como arquivos simples em translated-docs/. Repositórios apenas com README usam init -t docs-markdown em vez disso. Consulte Adicionar i18n ao seu README e à documentação em Markdown. Antes de executar translate-ui ou sync, defina a chave de API desse provedor no ambiente ou em .env — com exceção do Ollama; consulte Provedor e chave de API. Quatro chaves importam para strings da interface:

  • sourceLocale: o código BCP-47 do idioma em que o texto de origem está escrito. Qualquer idioma é válido; "en-GB" é apenas um exemplo. Ele deve corresponder a SOURCE_LOCALE exportado do arquivo de configuração de i18n em tempo de execução (src/i18n.ts / src/i18n.js). A string dentro de t() é esse idioma de origem, e os arquivos simples de localidade a usam como chave.
  • targetLocales: códigos BCP-47 dos seus idiomas de destino (por exemplo, ["de", "fr", "pt-BR"]). Execute generate-ui-languages para criar o manifesto ui-languages.json a partir desta lista.
  • ui.sourceRoots: diretórios ou padrões glob a serem verificados em busca de chamadas t("…") (por exemplo, ["src/"]).
  • ui.stringsJson e ui.flatOutputDir: onde o catálogo mestre e os arquivos por localidade (de.json, pt-BR.json) são gravados.

Todas as outras chaves, incluindo providers.<active>.uiModels, estão em Configuração.

Passo 2: Extrair strings ​

extract não faz nada útil até que essas chamadas t() / i18n.t() existam. Primeiro encapsule o texto codificado diretamente: Adicionar i18n a um app JS/TS.

bash
ai-i18n-tools extract

Verifica arquivos em ui.sourceRoots em busca de chamadas t("literal") e i18n.t("literal"). Grava (ou mescla em) ui.stringsJson.

O scanner é configurável: adicione nomes de funções personalizadas via ui.uiExtractor.funcNames (ou o legado ui.reactExtractor.funcNames). Para páginas e componentes Astro, adicione .astro a ui.uiExtractor.extensions. Para HTML puro, consulte Aplicativos HTML puros.

O que o extract verifica ​

  • As extensões padrão são apenas .js, .jsx, .ts e .tsx. .mjs, .cjs, .mts e .cts são incluídas somente quando você as adiciona a ui.uiExtractor.extensions.
  • Uma chave não literal, como t(variable) ou um literal de template, é ignorada sem aviso.
  • package.json description é incluído por padrão (ui.uiExtractor.includePackageDescription).
  • Componentes de arquivo único do Vue e do Svelte não são compatíveis. Adicionar .vue ou .svelte a extensions não extrai o texto do template. Não há parser de SFC.

Passo 3: Traduzir strings da UI ​

bash
ai-i18n-tools translate-ui

Lê strings.json, envia lotes para os modelos no provedor LLM ativo para cada localidade de destino, escreve arquivos JSON simples (de.json, fr.json, etc.) em ui.flatOutputDir. A seleção do modelo usa a cadeia da UI: localeModels(locale) → uiModels → translationModels (consulte Modelos de IA). Dentro de uma localidade, até uiBatchConcurrency lotes são executados simultaneamente (padrão 2; consulte Configuração — uiBatchConcurrency). -j ainda apenas paraleliza as localidades de destino. Cada lote bem-sucedido é gravado em strings.json e no arquivo de localidade simples antes que o próximo lote comece, portanto, interromper a execução ou um erro de API posterior mantém os lotes já concluídos.

Banco de dados de traduções (strings.json) ​

Para cada entrada, translate-ui armazena o ID do modelo do provedor ativo que traduziu com sucesso cada localidade em um objeto models opcional (mesmas chaves de localidade que translated). As strings editadas no Painel de Tradução são marcadas com o valor sentinela user-edited em models para essa localidade. Os arquivos planos por localidade em ui.flatOutputDir permanecem string de origem → tradução apenas; eles não incluem models (para que os pacotes de tempo de execução permaneçam inalterados).

Nota: As edições do painel para strings da interface do usuário residem em strings.json, não no cache de documentação SQLite. Execute sync ou translate-ui simples (sem flag especial) para reescrever arquivos de localidade planos do catálogo — --force-update não é encaminhado para a etapa da interface do usuário. Evite --force em comandos da interface do usuário após edições manuais: ele retraduz cada entrada e pode sobrescrever suas linhas user-edited. As linhas do catálogo cuja tradução armazenada falha na verificação do sistema de escrita da localidade (por exemplo, hindi romanizado para hi) são tratadas como ausentes e retraduzidas sem --force.

Etapa 4: Use a saída no seu app ​

translate-ui apenas grava arquivos. O app precisa carregá-los.

Opcional ​

Substituições de modelo por localidade ​

Alguns modelos traduzem certas línguas melhor do que outros. Por exemplo, os modelos qwen e z-ai tendem a se sair bem com idiomas asiáticos. Adicione entradas providers.<active>.localeModels para fornecer uma lista de modelos priorizada para cada localidade BCP-47. Essas listas são testadas antes de uiModels e translationModels para essa localidade. As tags de localidade correspondem sem distinção entre maiúsculas e minúsculas (zh-cn e ZH-CN são equivalentes). Sem uma entrada correspondente, a ferramenta usa a ordem padrão uiModels e translationModels. O mesmo mecanismo localeModels se aplica à tradução de documentos, JSON e SVG.

Exportando para XLIFF 2.0 ​

Para entregar strings da interface a um fornecedor de tradução, TMS ou ferramenta CAT, exporte o catálogo como XLIFF 2.0 (um arquivo por localidade de destino). Este comando é somente leitura: não modifica strings.json nem chama nenhuma API.

bash
ai-i18n-tools export-ui-xliff

Por padrão, os arquivos são gravados ao lado de ui.stringsJson, com nomes como strings.de.xliff, strings.pt-BR.xliff (nome base do seu catálogo + localidade + .xliff). Use -o / --output-dir para gravar em outro local. Traduções existentes de strings.json aparecem em <target>; localidades ausentes usam state="initial" sem <target>, para que as ferramentas possam preenchê-las. Use --untranslated-only para exportar apenas unidades que ainda precisam de tradução para cada localidade (útil para lotes enviados a fornecedores). --dry-run exibe os caminhos sem gravar arquivos.

Lançado sob a Licença MIT.