Localize um aplicativo Rails
Traduza arquivos YAML do Rails com idioma na raiz e verifique a busca de mensagens, a interpolação, as formas de plural e a seleção de idioma por requisição.
O Rails já atribui nomes estáveis às mensagens por meio de t e I18n.t. O Lingo.dev pode traduzir o YAML associado a esses nomes enquanto o Rails continua cuidando da busca de mensagens, da interpolação e da seleção de idioma. Comece com uma saudação e uma contagem de notificações e confira as duas com as mesmas funções auxiliares que o aplicativo usa.
Coloque as mensagens de origem em um arquivo de idioma do Rails #
Crie ou amplie config/locales/en.yml:
en:
home:
index:
welcome: "Welcome, %{name}!"
cta: "Create an account"
notifications:
unread:
one: "One unread notification"
other: "%{count} unread notifications"Em app/views/home/index.html.erb, a saudação pode usar uma busca relativa à visualização:
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>O caminho da visualização determina a chave completa home.index.welcome de .welcome. O código que faz a chamada fornece name e count; a tradução deve preservar esses nomes de interpolação. Chaves de plural como one e other identificam as variantes e devem permanecer inalteradas.
À medida que ampliar a cobertura, mova os demais rótulos definidos diretamente nas visualizações, os textos de e-mail e as mensagens de erro dos modelos para os namespaces de idioma apropriados. Traduzir um arquivo só afeta o código que carrega suas mensagens.
Selecione YAML com idioma na raiz #
O Rails lê o idioma na raiz do YAML. Renomear en.yml para es.yml e manter en: ainda define mensagens em inglês. Use o processador yaml-root-key para traduzir os valores e renomear a raiz na mesma operação.
Instale e vincule a CLI a partir da raiz do projeto:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo linkMantenha os IDs da organização e do engine de localização gravados em .lingo/config.json. Configure o array files desse arquivo com as entradas de origem usadas pelo projeto:
[
{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
{ "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]A segunda entrada abrange arquivos organizados por responsabilidade, como mailers.en.yml, sem selecionar os arquivos de tradução correspondentes. Remova-a se o projeto não tiver arquivos desse tipo. Defina o formato explicitamente: o YAML genérico preserva todas as raízes, enquanto a descoberta pela CLI exige uma escolha explícita para fontes YAML. YAML com idioma na raiz descreve o requisito de mapeamento com raiz única e o comportamento de reconstrução.
Traduza e inspecione os valores carregados #
Para os arquivos de destino que ainda não existem, execute:
lingo push --backfill-missing --waitAo fim da execução, abra config/locales/es.yml e confirme que a raiz é es:. Verifique se as chaves aninhadas e os nomes de interpolação correspondem aos da origem. Inspecione os comentários, as âncoras e os aliases após a serialização. Uma estrutura de origem diferente pode exigir um caminho de destino explícito.
Carregue o resultado no console do Rails ou nos testes do aplicativo, selecionando o idioma explicitamente:
I18n.with_locale(:es) do
puts I18n.t("home.index.welcome", name: "Alex", raise: true)
[0, 1, 2, 20].each do |count|
puts I18n.t("notifications.unread", count: count, raise: true)
end
endConfigure :en, :es e :fr como idiomas disponíveis antes dessa verificação. O exemplo testa a busca e a interpolação; confira se o texto expressa a saudação e a contagem de notificações pretendidas. Os idiomas de destino podem exigir regras e variantes de plural além das formas em inglês da origem. Faça a mesma verificação para o francês e para os namespaces de e-mail e validação do aplicativo à medida que forem adicionados.
Faça as requisições selecionarem o mesmo idioma #
Declare os idiomas compatíveis e um idioma padrão na configuração do Rails. Envolva o processamento das requisições em I18n.with_locale, usando um valor desse conjunto de idiomas, para que o estado do idioma não seja transferido para outra requisição.
Para URLs como /es, configure tanto o escopo da rota quanto o controlador que lê params[:locale]. Preserve o idioma nos links gerados. Se o aplicativo também negociar Accept-Language, interprete os pesos de qualidade e os identificadores regionais em vez de extrair apenas uma substring de duas letras. A seleção explícita do usuário deve ter prioridade quando o aplicativo oferecer essa opção.
Defina com cuidado o comportamento de fallback. Ele pode manter uma página utilizável e, ao mesmo tempo, ocultar a ausência de uma mensagem em espanhol. Por isso, verifique as entradas de destino obrigatórias sem depender dele. Quando apropriado, use a função auxiliar l do Rails para localizar datas e horas, em vez de traduzir uma data pré-formatada como texto.
Abra uma página no idioma de destino tanto diretamente quanto pela navegação. Confirme que o Rails seleciona o namespace de destino, exibe os valores interpolados esperados e lida com textos mais longos. lingo check não verifica se o YAML do Rails está completo; mantenha o carregamento pelo Rails, a renderização e a revisão linguística no processo de aceitação.
Mantenha as traduções em dia com as alterações na origem #
Mantenha juntos os arquivos de origem, as traduções de destino aceitas, a configuração e .lingo/lock.json. Após alterar uma mensagem, execute lingo push --wait para processar as alterações incrementais de rotina e compare a mensagem alterada com uma mensagem vizinha que não mudou. Para fazer uma correção pontual em um texto cuja origem não mudou, edite o destino diretamente: o escopo por chave YAML pode reutilizar a tradução existente. Para gerar as traduções novamente após uma mudança nas orientações, salve as traduções aceitas antes de substituir arquivos inteiros no escopo definido, conforme descrito em escopos de tradução.
Se as correções locais nas traduções de destino precisarem de proteção contra divergências, envie sem --wait, inspecione lingo pull --dry-run e recupere o resultado no checkout usado para o envio. A gravação de retorno no modo de espera não faz essa nova verificação de conflitos. Outros checkouts recebem pelo controle de versão as traduções registradas em commits. Consulte Preserve as traduções revisadas.
Quando o ciclo local estiver funcionando, escolha o GitHub App ou a automação de CI. Execute as mesmas verificações do Rails nos recursos gerados antes de integrar as alterações de tradução.