Localizar uma aplicação Web
Ligue os catálogos traduzidos à seleção de idioma, ao carregamento de recursos e às verificações de renderização da sua framework.
Se a sua aplicação Web já apresenta mensagens a partir de ficheiros de idioma, mantenha o que já funciona. O Lingo.dev pode traduzir os catálogos de origem enquanto a biblioteca existente continua a selecionar o idioma, a carregar as mensagens e a apresentá-las. Complete este ciclo num ecrã antes de traduzir o resto da aplicação.
Este guia abrange catálogos existentes baseados em chaves, em várias frameworks. Para mensagens baseadas no texto de origem e no contexto com @lingo.dev/react, utilize o guia de início rápido de React ou o guia de migração. Os identificadores extraídos por esta abordagem diferem das chaves de um catálogo i18next ou next-intl existente.
Preparar um caso de teste de ponta a ponta #
Escolha um ecrã com uma etiqueta, uma mensagem com uma variável e uma mensagem com plural ou condição. Apresente-o no idioma de origem através da biblioteca existente. Mantenha os espaços de nomes, a sintaxe de interpolação e as chaves de pesquisa; uma tradução genérica de JSON não converte a gramática de mensagens de uma biblioteca na de outra.
Para um ficheiro de origem react-i18next existente em public/locales/en/translation.json, inicialize a CLI a partir da raiz do projeto:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'public/locales/en/translation.json' --yes
lingo linkO .lingo/config.json associado deve ter esta estrutura:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [{ "pattern": "public/locales/en/translation.json" }]
}Mantenha os IDs reais da organização e do motor de localização obtidos na associação. Para outra framework, utilize o caminho de origem indicado nas secções abaixo. Selecione apenas catálogos de origem e faça corresponder o caminho de destino ao carregador. Utilize caminhos de destino explícitos para estruturas sem um segmento de idioma.
Traduza os destinos em falta com:
lingo push --backfill-missing --waitQuando terminar, inspecione o catálogo gerado e carregue o ecrã em espanhol. Compare os mesmos valores de variáveis e casos de plural nos dois idiomas. O passo específico de cada framework, descrito abaixo, liga esse ficheiro ao pedido ou à compilação efetivos. Um primeiro envio simples pode guardar uma versão de referência sem solicitar as traduções em falta.
Não altere os destinos enquanto aguarda a execução da gravação dos resultados. Se precisar de proteger as correções locais existentes contra conflitos, submeta sem --wait, inspecione lingo pull --dry-run e, em seguida, obtenha os resultados no checkout a partir do qual fez a submissão. Consulte Preservar traduções revistas.
React com react-i18next #
Com react-i18next, mantenha os espaços de nomes e as chamadas de pesquisa existentes. Um ficheiro de origem em public/locales/en/translation.json corresponde a public/locales/es/translation.json. Se a aplicação utilizar vários espaços de nomes, configure cada ficheiro de origem em inglês, em vez de usar um padrão glob que também inclua os ficheiros em espanhol gerados.
Configure o carregador de recursos do i18next para pedir o idioma e o espaço de nomes de destino. Em seguida, utilize as chamadas useTranslation existentes para apresentar o caso de teste. Verifique a substituição de variáveis e a convenção de chaves de plural utilizada 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. Numa aplicação cliente, inspecione tanto o pedido de rede do recurso como o texto visível; a apresentação em inglês como alternativa pode ocultar a falta de um ficheiro em espanhol.
Next.js App Router com next-intl #
Para next-intl, um ficheiro de origem comum é messages/en.json, que produz messages/es.json. Configure a resolução do idioma no momento do pedido e carregue as mensagens correspondentes na configuração do next-intl. Mantenha as rotas e a navegação dependentes do idioma coerentes com essa escolha.
Apresente o caso de teste tanto através de um pedido direto no idioma de destino como através da 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. A tradução do ficheiro de mensagens, por si só, não adiciona um segmento de idioma ao App Router nem um seletor de idioma. Para documentos extensos que acompanhem estes catálogos de interface, utilize Markdoc com Next.js.
Next.js Pages Router com next-i18next #
Com next-i18next, configure o padrão de origem para corresponder ao diretório de idiomas e aos espaços de nomes existentes. Se forem public/locales/en/common.json e public/locales/en/checkout.json, traduza ambos para os respetivos ficheiros em espanhol. Se utilizar messages/en.json, mantenha o carregador personalizado que efetivamente o lê.
Carregue os espaços de nomes necessários através do processo de carregamento de dados já utilizado pela página, no servidor ou de forma estática. Verifique um pedido direto à página localizada e uma mudança de rota no cliente. Confirme que os dados iniciais da página e o ambiente de execução do cliente utilizam o mesmo idioma e espaço de nomes; um ficheiro traduzido no disco não é suficiente se a página nunca o incluir.
Vue com vue-i18n #
O vue-i18n pode carregar dicionários como src/locales/en.json e src/locales/es.json. Traduza o ficheiro de origem em inglês e registe ou carregue dinamicamente o dicionário em espanhol na instância i18n existente. Defina o idioma selecionado onde a sua aplicação já faz essa gestão.
Teste as chamadas $t ou useI18n no caso de teste. Verifique as chaves aninhadas, a interpolação e a sintaxe de mensagens no plural da biblioteca instalada. Teste uma mudança de idioma sem recarregar a página e também um novo carregamento da página. Se os dicionários forem integrados através de importações, confirme que o ficheiro traduzido é incluído na compilação.
Nuxt com o módulo i18n #
Para Nuxt i18n, traduza um ficheiro de origem como locales/en.json para locales/es.json. Registe o idioma e o ficheiro na configuração do módulo adequada à versão instalada. Faça corresponder o diretório de idiomas configurado ao caminho de saída da CLI.
Siga a estratégia de rotas dependentes do idioma já utilizada no projeto, em vez de criar uma segunda estratégia na tarefa de tradução. Verifique a renderização no servidor, o carregamento diferido, a navegação localizada e os metadados na página do caso de teste. Adicionar um destino à configuração de tradução não o adiciona, por si só, à lista de idiomas do Nuxt.
Dicionários de Svelte e SvelteKit #
Para svelte-i18n, traduza um dicionário como src/lib/locales/en.json. Registe o dicionário de destino ou o respetivo carregador diferido e inicialize o idioma selecionado antes de o componente precisar dele.
Apresente o caso de teste através do armazenamento de traduções existente na aplicação. Se a aplicação utilizar SSR, teste um novo pedido renderizado no servidor e, em seguida, uma mudança de idioma no cliente. Verifique se o estado do idioma está isolado entre pedidos ao servidor e se o dicionário de destino termina de carregar. Não use o conteúdo apresentado no idioma alternativo como prova de que a tradução está concluída.
XLIFF no Angular #
Utilize o workflow i18n do Angular para começar por marcar e extrair as mensagens. O processador XLIFF suporta XLIFF 1.2 e 2.x, incluindo texto simples e códigos em linha. O texto dentro de códigos emparelhados, como <g> e <pc>, é traduzido, mantendo a respetiva estrutura; os códigos autónomos, como <ph>, permanecem protegidos. Mantenha estáveis os identificadores das mensagens e dos códigos em linha e inspecione os marcadores de posição devolvidos antes de importar o catálogo de destino.
Para entradas suportadas, src/locale/en/messages.xlf corresponde a src/locale/es/messages.xlf. O XLIFF não utiliza a substituição de sufixos de messages.en.xlf para messages.es.xlf; utilize o diretório do idioma ou um modelo de destino explícito. Preserve os identificadores das mensagens ao devolver as traduções ao Angular.
Registe o ficheiro 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 o ecrã. A localização do Angular em tempo de compilação difere de um carregador JSON em tempo de execução: alterar o idioma do navegador não compila um pacote localizado em falta. Verifique a cobertura das mensagens e a apresentação dos marcadores de posição antes de aceitar o pacote.
Astro #
Para etiquetas da interface, traduza src/i18n/en.json para o respetivo ficheiro de destino e configure o seu próprio carregador de dicionários para o selecionar. Para coleções de conteúdo, traduza os ficheiros de origem Markdown ou MDX específicos de cada idioma e utilize o workflow de conteúdo estático.
Configure o encaminhamento por idioma do Astro de forma independente da tradução. Compile e visite as rotas de destino geradas, verificando as ligações entre versões de idioma e quaisquer ilhas de cliente que carreguem as suas próprias mensagens. Uma coleção de conteúdo e o dicionário da interface de uma ilha podem precisar de entradas separadas.
Laravel #
Para a localização no Laravel, um ficheiro de origem PHP como lang/en/messages.php corresponde a lang/es/messages.php. Preserve as chaves dos arrays e os nomes dos parâmetros de substituição em tempo de execução. Consulte a referência do formato PHP antes de selecionar ficheiros que contenham código executável para além da estrutura de catálogo suportada.
Defina o idioma do pedido através do middleware existente da aplicação ou da política do controlador e apresente as mensagens através das funções auxiliares de tradução do Laravel. Teste os valores de substituição e a seleção de plurais. Teste um pedido em cada idioma suportado e um caso de recurso a um idioma alternativo; os ficheiros traduzidos não escolhem o idioma do pedido.
Django #
Utilize o workflow de extração do Django para criar locale/en/LC_MESSAGES/django.po e, em seguida, traduza esse ficheiro 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 o recurso que o Django efetivamente carrega, utilizando o passo de compilação gettext já existente no projeto.
Configure a seleção de idioma do Django e a lista de idiomas. Verifique um pedido localizado através do middleware de tradução e apresente as mensagens de chamadas no singular e no plural. A existência de um ficheiro PO no disco não prova que o respetivo catálogo compilado esteja atualizado. Consulte Gettext para conhecer os requisitos do ficheiro.
Rails #
O Rails identifica os ficheiros YAML cuja raiz é um idioma pela respetiva chave de raiz. Selecione yaml-root-key e, em seguida, verifique a configuração de idiomas, as funções auxiliares e a interpolação do Rails. O guia Localizar uma aplicação Rails apresenta o procedimento completo, incluindo ficheiros por área funcional, mudança de idioma por pedido e atualizações de âmbito limitado.
Gerar resultados prontos para revisão nas traduções recorrentes #
Assim que o ecrã funcionar, adicione os restantes catálogos de origem e os respetivos carregadores. Guarde os destinos aceites juntamente com a revisão do código-fonte e o Lockfile da CLI. Nas alterações posteriores à origem, utilize lingo push --wait para processar as diferenças habituais; um padrão de ficheiros como argumento posicional seleciona, em alternativa, um planeamento de âmbito limitado.
Escolha os eventos de alteração da origem que desencadeiam a tradução e configure a gravação dos resultados através da GitHub App ou das receitas de CI. As receitas de GitLab, Bitbucket e GitHub Actions executam a CLI e precisam do seu próprio mecanismo para gravar os resultados no repositório. Execute a compilação ou as verificações de recursos da framework sobre o resultado e, em seguida, reveja o sentido das traduções. lingo check não valida todas as frameworks nem garante que os ficheiros PHP, PO ou XLIFF estejam completos.
Um agente pode ajudar a inspecionar os carregadores e a propor alterações de configuração. Antes de alargar o workflow, aplique a essas alterações as mesmas verificações de seleção de origens, compilação e apresentação do ecrã.