Localização de Ruby on Rails com a API i18n

A CLI da Lingo.dev traduz arquivos YAML do Rails config/locales por meio de um engine de localização configurado. O Rails já vem com a API i18n nativa — o texto traduzível do seu app fica em arquivos YAML por idioma. A Lingo.dev se encaixa no pipeline que você já usa, sem adicionar dependências em tempo de execução.

Este guia mostra como localizar um app Rails de ponta a ponta: configurar a CLI, organizar arquivos YAML por idioma, alternar idiomas no momento da requisição e automatizar traduções em CI.

Como a localização funciona no Rails#

O Rails lê traduções de arquivos YAML em config/locales/. Cada arquivo usa um código de idioma na raiz e contém chaves aninhadas que espelham os caminhos de busca que seu código usa com I18n.t.

A primeira chave de cada arquivo YAML do Rails é o próprio código do idioma – en:, es:, fr:. O Rails organiza as traduções por essa chave raiz, e não pelo nome do arquivo: ele carrega todos os arquivos em config/locales/ e armazena o conteúdo de cada um sob a raiz que ele declara. Por isso, um es.yml que ainda esteja enraizado em en: não é ignorado – ele é mesclado ao namespace en. No fim, o espanhol fica sem tradução nenhuma, e as strings em inglês são sobrescritas silenciosamente.

Traduzir esse formato, portanto, significa reescrever essa chave, e não apenas os valores. O formato yaml-root-key faz exatamente isso: percorre a árvore abaixo da chave raiz, traduz apenas os valores de string e grava o arquivo de destino com raiz no idioma de destino. Chaves aninhadas, tokens de interpolação %{name} e categorias de pluralização do CLDR (zero/one/two/few/many/other) fazem parte da estrutura, então passam intactos – assim como comentários e âncoras YAML.

Pré-requisitos#

ruby -v
rails -v

node -v

<h1>Welcome</h1>

<h1><%= t(".welcome") %></h1>

Organize os arquivos de tradução#

O Rails carrega automaticamente todo arquivo *.yml em config/locales/. Mantenha o idioma de origem ao lado das versões traduzidas para que o diretório funcione como fonte única da verdade:

config/locales/
  en.yml          # Source locale
  es.yml          # Generated by Lingo.dev
  fr.yml
  de.yml

Um arquivo en.yml típico combina strings simples, namespaces aninhados, interpolação %{name} e pluralização:

en:
  hello: "Hello"
  home:
    welcome: "Welcome, %{name}!"
    cta: "Get started"
  notifications:
    unread:
      zero: "No unread notifications"
      one: "1 unread notification"
      other: "%{count} unread notifications"
  errors:
    messages:
      blank: "can't be blank"

Configure a CLI#

Instale a CLI, autentique-se e vincule o projeto ao seu engine:

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

lingo init e lingo link criam .lingo/config.json com seus idiomas e o orgId e engineId do seu engine. Faça commit dele junto com .lingo/lock.json, para que todas as máquinas e todas as execuções em CI compartilhem o mesmo estado.

Aponte uma entrada files[] para o arquivo de idioma de origem e defina o formato explicitamente:

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" }]
}

"format": "yaml-root-key" é obrigatório aqui, não opcional. Um caminho .yml não revela se a chave raiz é um idioma ou uma configuração comum, então a CLI não tenta adivinhar: se você omitir format, o arquivo será tratado como yaml genérico, o que traduz os valores e mantém a raiz em en: – a falha silenciosa descrita acima.

Os destinos são derivados do caminho de origem, então config/locales/en.yml gera config/locales/es.yml, config/locales/fr.yml e config/locales/de.yml.

O Rails também carrega arquivos por contexto junto com en.yml – devise.en.yml, mailers.en.yml, activerecord.en.yml. Adicione uma segunda entrada com um glob para cobri-los:

{
  "files": [
    { "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
    { "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
  ]
}

Os dois padrões não se sobrepõem: o primeiro corresponde apenas a en.yml, e o segundo apenas a arquivos terminados em .en.yml, então arquivos já traduzidos como es.yml e devise.es.yml nunca são capturados como origem. devise.en.yml gera devise.es.yml.

Configure o Rails para vários idiomas#

Informe ao Rails quais idiomas estão disponíveis e qual deve ser usado como padrão. Em config/application.rb:

module YourApp
  class Application < Rails::Application
    config.i18n.available_locales = [:en, :es, :fr, :de]
    config.i18n.default_locale = :en
    config.i18n.fallbacks = [:en]
  end
end

Defina o idioma da requisição em ApplicationController com base em um parâmetro de URL ou no cabeçalho Accept-Language:

class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

  def switch_locale(&action)
    locale = params[:locale] || http_accept_locale || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def http_accept_locale
    header = request.headers["Accept-Language"].to_s
    header.scan(/[a-z]{2}/).find { |l| I18n.available_locales.map(&:to_s).include?(l) }
  end

  def default_url_options
    { locale: I18n.locale }
  end
end

Renderize traduções nas views#

Use os helpers t e l em templates ERB. Um ponto no início da chave faz a resolução com base no caminho da view atual, mantendo as chaves de tradução lado a lado com os templates que as usam:

<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>
<%= link_to t(".cta"), signup_path, class: "btn-primary" %>

Adicione um alternador de idioma ao layout:

<nav>
  <% I18n.available_locales.each do |locale| %>
    <%= link_to locale.upcase, url_for(locale: locale) %>
  <% end %>
</nav>

Traduza localmente#

lingo push --wait

push envia os arquivos de origem, processa tudo no seu engine de localização e grava de volta os arquivos traduzidos. --wait mantém o comando em execução até que as saídas cheguem – vale a pena passá-lo explicitamente, porque uma mudança já prevista altera o padrão para que push envie a execução e retorne imediatamente, deixando você responsável por buscar os resultados com lingo pull.

As execuções seguintes traduzem apenas o delta: push gera um hash da origem e compara com .lingo/lock.json, então entradas inalteradas não geram consumo. A primeira execução em um projeto – ou depois de adicionar um idioma – precisa processar o corpus inteiro:

lingo push --backfill-missing

Restrinja uma execução a um subconjunto de arquivos passando um glob:

lingo push "config/locales/**"

Para buscar saídas geradas em outro lugar – outra máquina ou CI – execute lingo pull.

Reinicie o servidor Rails após a primeira execução de tradução para que os novos arquivos YAML sejam carregados:

bin/rails server

Acesse /es para ver a versão em espanhol.

Plurais#

O Rails usa categorias de plural do CLDR — zero, one, two, few, many, other. Passe um argumento count: para I18n.t e o Rails escolherá a chave correspondente:

t("notifications.unread", count: 0)   # => "No unread notifications"
t("notifications.unread", count: 1)   # => "1 unread notification"
t("notifications.unread", count: 12)  # => "12 unread notifications"

A CLI traduz cada variante de plural no lugar. Se o idioma de destino precisar de mais categorias do que one/other no inglês, defina-as no arquivo de origem en.yml.

Automatize no CI#

O Lingo.dev GitHub App traduz a cada push e pull request, do lado do servidor – sem runner e sem chave de API armazenada no seu repositório. Ele resolve o engine a partir do .lingo/config.json versionado, então orgId e engineId precisam estar presentes no arquivo que você commitar.

Se você preferir executar a CLI no seu próprio pipeline – GitHub Actions, GitLab CI, Bitbucket Pipelines – veja CI/CD Workflows. Forneça LINGO_API_KEY como segredo e chame lingo push --wait como qualquer outra etapa de build.

Verifique antes do deploy#

Use lingo check como gate de deploy para garantir que nenhum conteúdo sem tradução chegue à produção. Ele retorna um status diferente de zero se ainda houver entradas que precisem de tradução e não grava nada:

lingo check

Adicione isso como uma etapa separada no CI antes da pré-compilação de assets ou da build do container:

- name: Verify translations
  run: lingo check
- name: Precompile assets
  run: bundle exec rails assets:precompile

Próximos passos#