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 app | Leia 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-fonte | Conectar 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, plurais | Chamadas t() e plurais |
| Seletor de idioma / RTL | Seletor de idioma e RTL |
| Assinaturas da API de tempo de execução | Ajudantes de tempo de execução |
Dicionários .content.ts do Intlayer, migrando do Intlayer | Migrando do Intlayer |
Dicionários .content.ts do Intlayer, mantendo o Intlayer | Traduzindo o Intlayer no local |
Passo 1: Inicializar
ai-i18n-tools init -P openrouterIsso 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 aSOURCE_LOCALEexportado do arquivo de configuração de i18n em tempo de execução (src/i18n.ts/src/i18n.js). A string dentro det()é 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"]). Executegenerate-ui-languagespara criar o manifestoui-languages.jsona partir desta lista.ui.sourceRoots: diretórios ou padrões glob a serem verificados em busca de chamadast("…")(por exemplo,["src/"]).ui.stringsJsoneui.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.
ai-i18n-tools extractVerifica 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,.tse.tsx..mjs,.cjs,.mtse.ctssão incluídas somente quando você as adiciona aui.uiExtractor.extensions. - Uma chave não literal, como
t(variable)ou um literal de template, é ignorada sem aviso. package.jsondescriptioné incluído por padrão (ui.uiExtractor.includePackageDescription).- Componentes de arquivo único do Vue e do Svelte não são compatíveis. Adicionar
.vueou.svelteaextensionsnão extrai o texto do template. Não há parser de SFC.
Passo 3: Traduzir strings da UI
ai-i18n-tools translate-uiLê 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. Executesyncoutranslate-uisimples (sem flag especial) para reescrever arquivos de localidade planos do catálogo —--force-updatenão é encaminhado para a etapa da interface do usuário. Evite--forceem comandos da interface do usuário após edições manuais: ele retraduz cada entrada e pode sobrescrever suas linhasuser-edited. As linhas do catálogo cuja tradução armazenada falha na verificação do sistema de escrita da localidade (por exemplo, hindi romanizado parahi) 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.
- JS/TS: configure o i18next com os auxiliares de tempo de execução, carregue o arquivo de localidade que o usuário escolher e adicione um seletor de idioma. Consulte Conectar i18next e Seletor de idioma e RTL.
- Python: use o
i18n.pygerado ou seus catálogos gettext. Consulte Aplicativos Python. - .NET: use o
I18n.csgerado, ouI18nResx.csquando o aplicativo já usaResourceManager. Consulte Aplicativos .NET e Adicionar i18n a um aplicativo .NET ResourceManager.migrate-dotnet-i18nreescreve argumentosT()inseguros.--wrapaudita rótulos não marcados. - HTML simples: carregue o script de tempo de execução ao lado da página. Consulte Aplicativos HTML simples.
- Astro: consulte Site Astro.
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.
ai-i18n-tools export-ui-xliffPor 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.