Skip to main content

Rails i18n: ghid complet de internaționalizare pentru Ruby on Rails

De la primul fișier de limbă până în producție: configurați Rails I18n, folosiți funcția ajutătoare t(), gestionați pluralizarea CLDR, remediați capcanele frecvente și adăugați lanțuri inteligente de rezervă pentru setările regionale.

1

Înțelegeți arhitectura Rails I18n

Rails include gem-ul I18n. Fișierele de traducere se află în config/locales/, în format YAML (implicit) sau Ruby. Cadrul de lucru oferă funcția ajutătoare t() (alias pentru I18n.translate) în vizualizări, controlere, modele și componentele de e-mail. Rails I18n este simplu prin concepție și gestionează direct traducerea de bază, interpolarea și pluralizarea.

config/application.rb
# Rails includes i18n out of the box via the i18n gem
# config/application.rb
module MyApp
  class Application < Rails::Application
    # Default locale
    config.i18n.default_locale = :en

    # Available locales
    config.i18n.available_locales = [:en, :de, :ja, :es, :fr, :'pt-BR']

    # Fallback to default locale when translation is missing
    config.i18n.fallbacks = true

    # Load translations from nested directories
    config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]
  end
end
config/routes.rb
# config/routes.rb
Rails.application.routes.draw do
  scope "/:locale", locale: /en|de|ja|es|fr|pt-BR/ do
    root "home#index"
    resources :products
  end

  root "home#index"
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

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

  def default_url_options
    { locale: I18n.locale }
  end
end
Rails încarcă automat toate fișierele .yml și .rb din config/locales/. Le puteți organiza cum doriți: după limbă (en.yml, de.yml), după funcționalitate (en/users.yml, en/orders.yml) sau folosind ambele criterii (en/users.yml, de/users.yml). Rails îmbină toate fișierele la pornire.
2

Configurați setările de limbă

Setați default_locale, available_locales și comportamentul mecanismului de rezervă în config/application.rb sau într-un inițializator. Configurați detectarea limbii în ApplicationController folosind before_action, pentru a seta limba din URL, sesiune, dintr-un cookie sau din antetul Accept-Language.

config/locales/en.yml
# config/locales/en.yml
en:
  nav:
    home: "Home"
    about: "About"
    settings: "Settings"
  greeting: "Hello, %{name}!"
  cart:
    item_count:
      one: "%{count} item"
      other: "%{count} items"

# config/locales/de.yml
de:
  nav:
    home: "Startseite"
    about: "Über uns"
    settings: "Einstellungen"
  greeting: "Hallo, %{name}!"
  cart:
    item_count:
      one: "%{count} Artikel"
      other: "%{count} Artikel"
Setarea I18n.locale într-un before_action este sigură pentru fiecare solicitare, dar setarea I18n.default_locale în timpul execuției este globală și afectează toate firele de execuție. Folosiți întotdeauna I18n.locale (specifică firului de execuție) pentru schimbările de limbă limitate la o solicitare și niciodată I18n.default_locale.
3

Folosiți funcția ajutătoare t()

Funcția ajutătoare t() este disponibilă pretutindeni în Rails: în vizualizări, controlere, modele, componente de e-mail și sarcini. Acceptă o cheie, variabile opționale de interpolare și opțiuni precum valorile implicite și domeniul. În vizualizări, Rails acceptă căutări relative care restrâng automat cheile la controlerul și acțiunea curente.

app/views/example.html.erb
# In views (ERB)
<h1><%= t('nav.home') %></h1>
<p><%= t('greeting', name: @user.name) %></p>

# In controllers
flash[:notice] = t('flash.product_created')

# In models
validates :name, presence: { message: I18n.t('errors.blank') }

# With HTML (safe)
<%= t('terms_html', link: link_to(t('terms_link'), '/terms')) %>
4

Gestionați pluralizarea

Rails I18n folosește categoriile de plural CLDR: zero, one, two, few, many, other. Engleza are nevoie numai de one și other, dar alte limbi necesită mai multe forme. Definiți traducerile de plural drept chei YAML imbricate sub categoriile numerice necesare limbilor vizate.

Plural forms
# In YAML:
en:
  cart:
    item_count:
      zero: "No items"
      one: "%{count} item"
      other: "%{count} items"

# Arabic (6 forms):
ar:
  cart:
    item_count:
      zero: "لا عناصر"
      one: "عنصر واحد"
      two: "عنصران"
      few: "%{count} عناصر"
      many: "%{count} عنصرًا"
      other: "%{count} عنصر"

# Usage in views:
<%= t('cart.item_count', count: @cart.items.size) %>
Rails generează I18n::InvalidPluralizationData dacă lipsește o categorie de plural necesară pentru limba activă. Dacă limba rusă definește numai one și other (copiate din engleză), valori precum 2, 3 și 4 vor provoca o eroare deoarece rusa necesită categoria few. Definiți întotdeauna toate categoriile CLDR ale fiecărei limbi.
5

Adăugați lanțuri de rezervă pentru setările regionale

I18n.fallbacks încorporat în Rails oferă numai un mecanism de bază, care trece de la varianta regională la limba implicită. Un utilizator pt-BR căruia îi lipsește o cheie vede textul în engleză în locul celui în pt-PT. rails-locale-chain adaugă lanțuri configurabile cu îmbinare profundă, astfel încât utilizatorii regionali să vadă întotdeauna cea mai apropiată traducere disponibilă.

Lazy lookups
# Lazy lookups use the controller/action as scope
# app/views/products/index.html.erb
# Instead of t('products.index.title'), just use:
<h1><%= t('.title') %></h1>
<p><%= t('.description') %></p>

# Rails looks up: products.index.title and products.index.description

# config/locales/en.yml
en:
  products:
    index:
      title: "All Products"
      description: "Browse our catalog"
rails-locale-chain include peste 75 de lanțuri de rezervă predefinite, care acoperă 11 familii de limbi. Adăugați-l în Gemfile și configurați-l într-un inițializator, iar utilizatorii regionali vor vedea imediat traducerile limbii-părinte în locul fragmentelor lipsă afișate în engleză.
6

Automatizați traducerile

După configurarea Rails I18n, traduceți fișierele YAML de limbă cu ajutorul IA. i18n Agent acceptă nativ YAML: indicați-i fișierul limbii-sursă, iar acesta generează toate limbile vizate, păstrând cheile imbricate, variabilele de interpolare și formele de plural.

config/initializers/locale_chain.rb
# Gemfile
gem 'rails-locale-chain'

# config/initializers/locale_chain.rb
Rails.application.config.i18n.fallbacks = {
  'pt-BR': ['pt', 'en'],
  'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
  'es-419': ['es', 'en'],
}

# The gem deep-merges translations across the chain
# pt-BR -> pt -> en
# Missing keys in pt-BR are filled from pt, then en
Traduceți incremental: când adăugați chei noi, traduceți doar diferențele. Astfel păstrați traducerile existente și evitați regenerarea șirurilor nemodificate.

Capcane frecvente

Erori InvalidPluralizationData

Rails se oprește cu I18n::InvalidPluralizationData când lipsește o categorie de plural CLDR necesară. Cel mai adesea, problema apare când formele de plural englezești (one/other) sunt copiate în limbi care necesită mai multe categorii (rusa necesită few, iar araba zero/two/few/many). Instalați rails-i18n pentru reguli CLDR corecte și definiți toate categoriile.

Căutări relative în afara vizualizărilor

Căutările relative (t('.key')) funcționează numai în vizualizări, unde Rails cunoaște controlerul și acțiunea. Folosirea t('.key') într-un model, într-o componentă de e-mail sau într-un obiect de serviciu returnează o eroare de traducere lipsă. Folosiți chei complete (t('users.show.key')) în afara vizualizărilor.

Erorile de sintaxă YAML împiedică toate traducerile

O singură eroare de sintaxă YAML (indentare greșită, caractere speciale fără ghilimele, tabulator în loc de spații) împiedică încărcarea întregului fișier de limbă. Toate traducerile din fișier returnează erori de cheie lipsă. Validați fișierele YAML în CI cu un analizor și includeți între ghilimele șirurile care conțin două puncte, paranteze drepte sau caractere speciale inițiale.

Încercați acum i18n Agent

Plasați aici fișierul de traducere

JSON, YAML, PO, XML, CSV, Markdown, Properties

sau faceți clic pentru a-l selecta

Limbi țintă

Nu este necesară înregistrareaEstimare instantanee

Întrebări frecvente despre Rails i18n