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

A CLI da Lingo.dev traduz ficheiros YAML do Rails config/locales através de um motor de localização configurado. O Rails já inclui a API i18n de raiz — o texto traduzível da sua app fica em ficheiros YAML por idioma. A Lingo.dev encaixa no pipeline existente sem acrescentar uma dependência em runtime.

Este guia mostra, de ponta a ponta, como localizar uma app Rails: configurar a CLI, organizar ficheiros YAML por idioma, alternar idiomas no momento do pedido e automatizar traduções com GitHub Actions.

Repositório de demonstração

Clone ou faça fork de lingodotdev/ruby-on-rails-localization-example para acompanhar. O repositório inclui uma app Rails funcional com ficheiros YAML config/locales, uma configuração da CLI da Lingo.dev e um workflow de GitHub Actions.

Como Funciona a Localização no Rails#

O Rails lê traduções de ficheiros YAML em config/locales/. Cada ficheiro usa um código de idioma como chave na raiz e contém chaves aninhadas que refletem os caminhos de procura que o seu código usa com I18n.t.

Camada	O que contém	Ficheiro de exemplo
Strings da interface	Botões, etiquetas, mensagens flash	`config/locales/en.yml`
Conteúdo de mailer	Assuntos e corpos para `ActionMailer`	`config/locales/mailers.en.yml`
Erros do modelo	Mensagens de validação e nomes de atributos	`config/locales/activerecord.en.yml`

A primeira chave de cada ficheiro YAML do Rails é o próprio código de idioma — en:, es:, fr:. O bucket yaml-root-key da CLI reconhece esta estrutura: remove o prefixo do idioma antes de enviar o conteúdo para o seu motor de localização e depois escreve um ficheiro paralelo com o código do idioma de destino como nova chave de raiz. As chaves aninhadas, os tokens de interpolação %{name} e as categorias de plural CLDR (zero/one/two/few/many/other) são preservados.

Pré-requisitos#

Criar um motor de localização

Cada execução da CLI envia conteúdo através de um motor de localização — a configuração que determina que modelo LLM, glossário, voz da marca e instruções se aplicam. Crie um no dashboard da Lingo.dev e gere uma chave de API.

Verificar Ruby e Rails

Este guia foi pensado para Rails 7.2 ou superior, que requer Ruby 3.1 ou superior. Verifique as versões:

bash

ruby -v
rails -v

Verificar Node.js

A CLI requer Node.js 18 ou superior:

bash

node -v

Configurar o i18n do Rails

Este guia parte do princípio de que a sua app já armazena traduções em config/locales/*.yml. Se tiver strings hardcoded em views ou controllers, extraia-as primeiro para chamadas t(). Por exemplo, substitua:

erb

<h1>Welcome</h1>

por:

erb

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

e depois adicione a chave correspondente a config/locales/en.yml. Consulte o guia de internacionalização do Rails para ver todos os passos da migração.

Organizar os Ficheiros de Tradução#

O Rails carrega automaticamente todos os ficheiros *.yml em config/locales/. Mantenha o idioma de origem ao lado das respetivas versões traduzidas, para que a diretoria funcione como a única fonte de verdade:

text

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

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

yaml

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"

Configurar a CLI#

Crie um ficheiro i18n.json na raiz do projeto. Declare um bucket yaml-root-key apontado aos ficheiros de idioma:

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "yaml-root-key": {
      "include": ["config/locales/[locale].yml"]
    }
  }
}

O marcador [locale] é resolvido para cada código de idioma configurado. Com source: "en", a CLI lê config/locales/en.yml e escreve os ficheiros traduzidos em config/locales/es.yml, config/locales/fr.yml e config/locales/de.yml.

O Rails carrega sem problemas mailers.en.yml, pages.en.yml e assim sucessivamente, em conjunto com en.yml. Adicione padrões extra ao array include do seu bucket yaml-root-key:

json

{
  "buckets": {
    "yaml-root-key": {
      "include": [
        "config/locales/[locale].yml",
        "config/locales/mailers.[locale].yml",
        "config/locales/pages.[locale].yml"
      ]
    }
  }
}

Configurar o Rails para Vários Idiomas#

Diga ao Rails que idiomas estão disponíveis e qual deve ser usado por defeito. Em config/application.rb:

ruby

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 do pedido em ApplicationController a partir de um parâmetro na URL ou do cabeçalho Accept-Language:

ruby

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

Renderizar Traduções nas Views#

Use os helpers t e l em templates ERB. Um ponto no início da chave resolve em relação ao caminho da view atual, mantendo as chaves de tradução junto dos templates que as usam:

erb

<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 seletor de idioma ao layout:

erb

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

Traduzir Localmente#

Defina a sua chave de API e execute a CLI:

bash

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

A CLI lê todos os ficheiros que correspondem aos padrões do seu bucket, identifica entradas por traduzir com o lockfile, traduz apenas o delta através do seu motor de localização e escreve os resultados em cada ficheiro do idioma de destino. A chave de raiz do idioma, os namespaces aninhados, os tokens de interpolação no estilo %{name} e as categorias de plural são preservados — só muda o texto traduzível.

Para direcionar um idioma específico durante o desenvolvimento:

bash

npx lingo.dev@latest run --target-locale es

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

bash

bin/rails server

Visite /es para ver o resultado em espanhol.

Plurais#

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

ruby

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 mesmo local. Se o seu idioma de destino precisar de mais categorias do que one/other em inglês, defina-as no en.yml de origem.

Automatizar com GitHub Actions#

Adicione um ficheiro de workflow em .github/workflows/translate.yml para traduzir a cada push:

As traduções são submetidas diretamente para a main — zero fricção, ideal para equipas pequenas:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Guarde a sua chave de API como LINGODOTDEV_API_KEY em Settings > Secrets and variables > Actions no repositório GitHub.

Verificar Antes de Fazer Deploy#

Use a flag --frozen como gate de deploy para garantir que não chega conteúdo por traduzir à produção. A CLI termina com um estado diferente de zero se alguma entrada precisar de tradução:

bash

npx lingo.dev@latest run --frozen

Adicione isto como um passo de CI separado antes da pré-compilação de assets ou da build do contentor:

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen
- name: Precompile assets
  run: bundle exec rails assets:precompile

Próximos Passos#

Localização de Conteúdo Estático

Tipos de bucket para Markdown, MDX, JSON, YAML e muito mais

Localização de Apps Web

Padrões de strings de interface nos frameworks web mais comuns

Workflows de CI/CD

Padrões para GitHub Actions, GitLab CI e Bitbucket Pipelines

Glossários

Proteja nomes de marca e termos técnicos contra tradução

Repositório de demonstração

Como Funciona a Localização no Rails#

Camada	O que contém	Ficheiro de exemplo
Strings da interface	Botões, etiquetas, mensagens flash	`config/locales/en.yml`
Conteúdo de mailer	Assuntos e corpos para `ActionMailer`	`config/locales/mailers.en.yml`
Erros do modelo	Mensagens de validação e nomes de atributos	`config/locales/activerecord.en.yml`

Pré-requisitos#

Criar um motor de localização

Verificar Ruby e Rails

Este guia foi pensado para Rails 7.2 ou superior, que requer Ruby 3.1 ou superior. Verifique as versões:

bash

ruby -v
rails -v

Verificar Node.js

A CLI requer Node.js 18 ou superior:

bash

node -v

Configurar o i18n do Rails

erb

<h1>Welcome</h1>

por:

erb

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

e depois adicione a chave correspondente a config/locales/en.yml. Consulte o guia de internacionalização do Rails para ver todos os passos da migração.

Organizar os Ficheiros de Tradução#

text

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

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

yaml

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"

Configurar a CLI#

Crie um ficheiro i18n.json na raiz do projeto. Declare um bucket yaml-root-key apontado aos ficheiros de idioma:

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "yaml-root-key": {
      "include": ["config/locales/[locale].yml"]
    }
  }
}

O Rails carrega sem problemas mailers.en.yml, pages.en.yml e assim sucessivamente, em conjunto com en.yml. Adicione padrões extra ao array include do seu bucket yaml-root-key:

json

{
  "buckets": {
    "yaml-root-key": {
      "include": [
        "config/locales/[locale].yml",
        "config/locales/mailers.[locale].yml",
        "config/locales/pages.[locale].yml"
      ]
    }
  }
}

Configurar o Rails para Vários Idiomas#

Diga ao Rails que idiomas estão disponíveis e qual deve ser usado por defeito. Em config/application.rb:

ruby

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 do pedido em ApplicationController a partir de um parâmetro na URL ou do cabeçalho Accept-Language:

ruby

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

Renderizar Traduções nas Views#

Use os helpers t e l em templates ERB. Um ponto no início da chave resolve em relação ao caminho da view atual, mantendo as chaves de tradução junto dos templates que as usam:

erb

<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 seletor de idioma ao layout:

erb

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

Traduzir Localmente#

Defina a sua chave de API e execute a CLI:

bash

export LINGO_API_KEY="your-api-key"
npx lingo.dev@latest run

Para direcionar um idioma específico durante o desenvolvimento:

bash

npx lingo.dev@latest run --target-locale es

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

bash

bin/rails server

Visite /es para ver o resultado em espanhol.

Plurais#

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

ruby

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 mesmo local. Se o seu idioma de destino precisar de mais categorias do que one/other em inglês, defina-as no en.yml de origem.

Automatizar com GitHub Actions#

Adicione um ficheiro de workflow em .github/workflows/translate.yml para traduzir a cada push:

As traduções são submetidas diretamente para a main — zero fricção, ideal para equipas pequenas:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lingo.dev
        uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Guarde a sua chave de API como LINGODOTDEV_API_KEY em Settings > Secrets and variables > Actions no repositório GitHub.

Verificar Antes de Fazer Deploy#

Use a flag --frozen como gate de deploy para garantir que não chega conteúdo por traduzir à produção. A CLI termina com um estado diferente de zero se alguma entrada precisar de tradução:

bash

npx lingo.dev@latest run --frozen

Adicione isto como um passo de CI separado antes da pré-compilação de assets ou da build do contentor:

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen
- name: Precompile assets
  run: bundle exec rails assets:precompile

Próximos Passos#

Localização de Conteúdo Estático

Tipos de bucket para Markdown, MDX, JSON, YAML e muito mais

Localização de Apps Web

Padrões de strings de interface nos frameworks web mais comuns

Workflows de CI/CD

Padrões para GitHub Actions, GitLab CI e Bitbucket Pipelines

Glossários

Proteja nomes de marca e termos técnicos contra tradução