Localize um aplicativo web

Conecte os catálogos traduzidos à seleção de idioma, ao carregamento de recursos e às verificações de renderização do seu framework.

Se o seu aplicativo web já renderiza mensagens a partir de arquivos de idioma, mantenha essa estrutura. O Lingo.dev pode traduzir os catálogos de origem enquanto a biblioteca existente continua selecionando o idioma, carregando as mensagens e renderizando o conteúdo. Conclua esse ciclo em uma tela antes de traduzir o restante do aplicativo.

Este guia aborda catálogos existentes baseados em chaves em diferentes frameworks. Para mensagens baseadas em texto de origem e contexto com @lingo.dev/react, use o guia de início rápido do React ou o guia de migração. Os identificadores extraídos nessa abordagem são diferentes das chaves de um catálogo existente do i18next ou next-intl.

Prepare um caso de teste de ponta a ponta #

Escolha uma tela com um rótulo, uma mensagem com variável e uma mensagem com plural ou condição. Renderize-a no idioma de origem com a biblioteca existente. Preserve os namespaces, a sintaxe de interpolação e as chaves de consulta; uma tradução genérica de JSON não converte a gramática de mensagens de uma biblioteca na de outra.

Para um arquivo de origem existente do react-i18next em public/locales/en/translation.json, inicialize a CLI na raiz do projeto:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo link

O .lingo/config.json vinculado deve ter esta estrutura:

json
{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es"],
  "files": [{ "pattern": "public/locales/en/translation.json" }]
}

Mantenha os IDs reais da organização e do engine de localização gerados na vinculação. Para outro framework, use o caminho de origem indicado nas seções abaixo. Selecione apenas os catálogos de origem e ajuste o caminho de destino ao carregador. Use caminhos de destino explícitos para estruturas sem um segmento de idioma.

Traduza os destinos ausentes com:

sh
lingo push --backfill-missing --wait

Ao concluir, inspecione o catálogo gerado e carregue a tela em espanhol. Compare os mesmos valores de variáveis e casos de plural nos dois idiomas. A etapa específica de cada framework, descrita abaixo, conecta esse arquivo à requisição ou à compilação real. Um primeiro push simples pode salvar uma versão de referência sem solicitar as traduções ausentes.

Não altere os destinos enquanto aguarda a execução da gravação de retorno. Se as correções locais existentes precisarem de proteção contra conflitos, envie sem --wait, inspecione lingo pull --dry-run e depois recupere os resultados no checkout usado para o envio. Consulte Preservar traduções revisadas.

React com react-i18next #

Com o react-i18next, mantenha os namespaces e as chamadas de consulta existentes. Uma origem em public/locales/en/translation.json corresponde a public/locales/es/translation.json. Se o aplicativo usa vários namespaces, configure cada origem em inglês em vez de usar um padrão glob que também inclua os arquivos gerados em espanhol.

Configure o carregador de recursos do i18next para solicitar o idioma de destino e o namespace. Em seguida, use as chamadas useTranslation existentes para renderizar o caso de teste. Verifique a substituição de variáveis e a convenção de chaves de plural usada pela versão instalada do i18next. Um tradutor genérico de JSON não converte o esquema de plurais de uma biblioteca no de outra. Em um aplicativo executado no cliente, inspecione tanto a requisição de rede do recurso quanto o texto visível; o uso do inglês como idioma alternativo pode ocultar a ausência de um arquivo em espanhol.

Next.js App Router com next-intl #

Para o next-intl, uma origem comum é messages/en.json, que gera messages/es.json. Configure a resolução do idioma no momento da requisição e o carregamento das mensagens correspondentes na configuração do next-intl. Mantenha as rotas e a navegação por idioma alinhadas a essa escolha.

Renderize o caso de teste tanto por uma requisição direta no idioma de destino quanto pela navegação a partir de outro idioma. Verifique o conteúdo renderizado no servidor, a hidratação no cliente e as variáveis ou os plurais ICU. Traduzir apenas o arquivo de mensagens não adiciona um segmento de idioma ao App Router nem um seletor de idioma. Para documentos longos que acompanham esses catálogos de interface, use Markdoc com Next.js.

Next.js Pages Router com next-i18next #

Com o next-i18next, configure o padrão de origem de acordo com o diretório de idiomas e os namespaces existentes. Se forem public/locales/en/common.json e public/locales/en/checkout.json, traduza ambos para os arquivos correspondentes em espanhol. Se você usa messages/en.json, mantenha o carregador personalizado que de fato o utiliza.

Carregue os namespaces necessários pelo fluxo de carregamento de dados já usado pela página, seja no servidor ou de forma estática. Verifique uma requisição direta à página localizada e uma mudança de rota no cliente. Confira se os dados iniciais da página e o ambiente de execução no cliente usam o mesmo idioma e namespace; ter um arquivo traduzido no disco não basta se a página nunca o inclui.

Vue com vue-i18n #

O vue-i18n pode carregar dicionários como src/locales/en.json e src/locales/es.json. Traduza a origem em inglês e registre ou carregue dinamicamente o dicionário em espanhol na instância i18n existente. Defina o idioma selecionado no ponto em que o aplicativo já faz esse gerenciamento.

Execute as chamadas $t ou useI18n no caso de teste. Verifique as chaves aninhadas, a interpolação e a sintaxe de mensagens de plural da biblioteca instalada. Teste tanto a troca de idioma sem recarregar a página quanto um novo carregamento. Se os dicionários forem empacotados por meio de importações, confirme que o arquivo traduzido está incluído na compilação.

Nuxt com o módulo i18n #

Para o Nuxt i18n, traduza uma origem como locales/en.json para locales/es.json. Registre o idioma e o arquivo na configuração do módulo adequada à versão instalada. Alinhe o diretório de idiomas configurado ao caminho de saída da CLI.

Siga a estratégia de rotas por idioma do projeto em vez de criar uma segunda estratégia na tarefa de tradução. Verifique a renderização no servidor, o carregamento sob demanda, a navegação localizada e os metadados na página de teste. Adicionar um destino à configuração de tradução não o adiciona automaticamente à lista de idiomas do Nuxt.

Dicionários do Svelte e do SvelteKit #

Para o svelte-i18n, traduza um dicionário como src/lib/locales/en.json. Registre o dicionário de destino ou seu carregador sob demanda e inicialize o idioma selecionado antes que o componente precise dele.

Renderize o caso de teste usando o armazenamento de traduções existente no aplicativo. Se o aplicativo usa SSR, teste uma nova requisição com renderização no servidor e, em seguida, uma troca de idioma no cliente. Verifique se o estado do idioma fica isolado entre as requisições ao servidor e se o dicionário de destino termina de carregar. Não use o conteúdo exibido no idioma alternativo como prova de que a tradução foi concluída.

XLIFF do Angular #

Use o workflow de i18n do Angular para marcar e extrair as mensagens primeiro. O processador de XLIFF oferece suporte a XLIFF 1.2 e 2.x, incluindo texto simples e códigos em linha. O texto dentro de códigos em pares, como <g> e <pc>, é traduzido sem alterar sua estrutura; códigos independentes, como <ph>, permanecem protegidos. Mantenha estáveis os identificadores de mensagens e de códigos em linha e inspecione os marcadores retornados antes de importar o catálogo de destino.

Para entradas compatíveis, src/locale/en/messages.xlf corresponde a src/locale/es/messages.xlf. O XLIFF não usa substituição de sufixo de messages.en.xlf para messages.es.xlf; use o diretório do idioma ou um modelo de destino explícito. Preserve os identificadores das mensagens ao devolver as traduções ao Angular.

Registre o arquivo de destino na configuração de compilação para localização do Angular, compile o pacote do idioma de destino e disponibilize-o para inspecionar a tela. A localização em tempo de compilação do Angular é diferente de um carregador JSON em tempo de execução: alterar o idioma do navegador não compila um pacote localizado que está faltando. Verifique a cobertura das mensagens e a renderização dos marcadores antes de aceitar o pacote.

Astro #

Para rótulos de interface, traduza src/i18n/en.json para o arquivo de destino correspondente e configure seu próprio carregador de dicionários para selecioná-lo. Para coleções de conteúdo, traduza os arquivos de origem Markdown ou MDX específicos de cada idioma e use o workflow de conteúdo estático.

Configure o roteamento por idioma do Astro independentemente da tradução. Compile e acesse as rotas de destino geradas, verificando os links entre as versões de idioma e as ilhas no cliente que carregam suas próprias mensagens. Uma coleção de conteúdo e o dicionário de interface de uma ilha podem precisar de entradas separadas.

Laravel #

Para a localização do Laravel, uma origem PHP como lang/en/messages.php corresponde a lang/es/messages.php. Preserve as chaves do array e os nomes usados nas substituições em tempo de execução. Consulte a referência do formato PHP antes de selecionar arquivos que contenham código executável além da estrutura de catálogo compatível.

Defina o idioma da requisição pelo middleware ou pela política do controlador já existente no aplicativo e renderize as mensagens com as funções auxiliares de tradução do Laravel. Teste os valores de substituição e a seleção de plurais. Teste uma requisição em cada idioma compatível e um caso que recorra ao idioma alternativo; os arquivos traduzidos não escolhem o idioma da requisição.

Django #

Use o workflow de extração do Django para criar locale/en/LC_MESSAGES/django.po e depois traduza esse arquivo PO de origem para o diretório do idioma de destino. Preserve os identificadores das mensagens gettext, o contexto e a interpolação. Compile o PO traduzido para gerar o recurso que o Django de fato carrega, usando a etapa de compilação gettext existente no projeto.

Configure a seleção de idioma do Django e a lista de idiomas. Verifique uma requisição localizada pelo middleware de tradução e renderize chamadas no singular e no plural. A existência de um arquivo PO no disco não comprova que o catálogo compilado está atualizado. Consulte Gettext para ver os requisitos do arquivo.

Rails #

O Rails identifica arquivos YAML com idioma na raiz pela chave raiz. Selecione yaml-root-key e depois verifique a configuração de idioma, as funções auxiliares e a interpolação do Rails. O guia Localize um aplicativo Rails apresenta o procedimento completo, incluindo arquivos separados por responsabilidade, troca de idioma por requisição e atualizações com escopo definido.

Gere resultados fáceis de revisar nas traduções recorrentes #

Quando a tela estiver funcionando, adicione os demais catálogos de origem e seus carregadores. Mantenha os destinos aceitos junto com a revisão do código-fonte e o Lockfile da CLI. Nas alterações posteriores da origem, use lingo push --wait para processar normalmente as diferenças; um padrão de arquivo passado como argumento posicional seleciona, em vez disso, um planejamento com escopo definido.

Escolha os gatilhos de alteração na origem e a forma de gravação de retorno pelo GitHub App ou pelas receitas de CI. As receitas do GitLab, Bitbucket e GitHub Actions executam a CLI e precisam de um mecanismo próprio de gravação de retorno no repositório. Execute a compilação ou as verificações de recursos do framework sobre o resultado e depois revise o sentido da tradução. lingo check não valida todos os frameworks nem garante que os arquivos PHP, PO ou XLIFF estejam completos.

Um agente pode ajudar a inspecionar carregadores e propor alterações na configuração. Aplique a essas edições as mesmas verificações de seleção de origem, compilação e tela renderizada antes de expandir o workflow.