Skip to main content

Rails i18n: täielik Ruby on Rails'i internatsionaliseerimise juhend

Esimesest lokaadifailist tootmiskeskkonnani: seadista Rails I18n, kasuta t()-abifunktsiooni, töötle CLDR-i mitmusereegleid, paranda levinud komistuskivid ja lisa nutikad varulokaadiahelad.

1

Mõista Rails I18n-i arhitektuuri

Rails sisaldab I18n gemi. Tõlkefailid asuvad kataloogis config/locales/ YAML-failidena (vaikimisi) või Ruby-failidena. Raamistik pakub t()-abifunktsiooni (I18n.translate'i alias) vaadetes, kontrollerites, mudelites ja meilisaatjates. Rails I18n on taotluslikult lihtne — see haldab kohe põhitõlget, interpoleerimist ja mitmusevorme.

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 laadib automaatselt kõik kataloogi config/locales/ .yml- ja .rb-failid. Neid saab korraldada kuidas soovid — keele järgi (en.yml, de.yml), funktsiooni järgi (en/users.yml, en/orders.yml) või mõlema järgi (en/users.yml, de/users.yml). Rails ühendab kõik failid käivitamisel.
2

Määra lokaadiseaded

Määra default_locale, available_locales ja varukäitumine failis config/application.rb või lähtestajas. Seadista lokaadituvastus ApplicationControlleris before_actioni abil, mis määrab lokaadi URL-ist, seansist, küpsisest või Accept-Language'i päisest.

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"
I18n.locale määramine before_actionis on päringupõhiselt ohutu, kuid I18n.default_locale'i käitusaegne määramine on globaalne ja mõjutab kõiki lõimi. Päringupõhisteks lokaadimuudatusteks kasuta alati I18n.locale'i (lõimekohalik), mitte kunagi I18n.default_locale'i.
3

Kasuta t()-abifunktsiooni

t()-abifunktsioon on saadaval kõikjal Rails'is — vaadetes, kontrollerites, mudelites, meilisaatjates ja töödes. See võtab vastu võtme, valikulised interpoleerimismuutujad ning sellised valikud nagu vaikeväärtused ja skoop. Vaadetes toetab Rails laisku otsinguid, mis seovad võtmed automaatselt praeguse kontrolleri ja toiminguga.

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

Töötle mitmusevorme

Rails I18n kasutab CLDR-i mitmusekategooriaid: zero, one, two, few, many, other. Inglise keel vajab ainult one ja other, kuid teised keeled vajavad rohkem vorme. Määra mitmusetõlked pesastatud YAML-võtmetena sihtkeelte vajalike kogusekategooriate all.

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 viskab I18n::InvalidPluralizationData tõrke, kui aktiivsest lokaadist puudub nõutud mitmusekategooria. Kui vene lokaat määratleb ainult inglise keelest kopeeritud one ja other, põhjustavad kogused 2, 3 ja 4 krahhi, sest vene keel vajab few-kategooriat. Määra alati iga keele kõik CLDR-i kategooriad.
5

Lisa varulokaadiahelad

Rails'i sisseehitatud I18n.fallbacks pakub ainult lihtsat taandumist piirkondlikust vaikelokaadile. Puuduva võtmega pt-BR kasutaja näeb pt-PT asemel inglise keelt. rails-locale-chain lisab seadistatavad süvaühendatud ahelad, et piirkondlikud kasutajad näeksid alati lähimat saadaolevat tõlget.

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 sisaldab enam kui 75 sisseehitatud varulokaadiahelat 11 keelepere jaoks. Lisa see Gemfile'i ja seadista lähtestajas ning piirkondlikud kasutajad näevad kohe ingliskeelsete lünkade asemel põhilokaadi tõlkeid.
6

Automatiseeri tõlked

Kui Rails I18n-i seadistus on valmis, tõlgi YAML-lokaadifailid tehisintellektiga. i18n Agent toetab YAML-i loomupäraselt — suuna see lähtekeele failile ning see loob kõik sihtkeeled, säilitades pesastatud võtmed, interpoleerimismuutujad ja mitmusevormid.

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
Tõlgi järk-järgult — kui lisad uusi võtmeid, tõlgi ainult diff. Nii säilivad olemasolevad tõlked ja väldid muutmata stringide uuesti loomist.

Levinud komistuskivid

InvalidPluralizationData tõrked

Rails jookseb I18n::InvalidPluralizationData tõrkega kokku, kui nõutud CLDR-i mitmusekategooria puudub. Enamasti juhtub see siis, kui inglise mitmusevormid (one/other) kopeeritakse rohkem kategooriaid vajavatesse keeltesse (vene keel vajab few, araabia keel zero/two/few/many). Paigalda õigete CLDR-i reeglite jaoks rails-i18n ja määra kõik kategooriad.

Laisad otsingud väljaspool vaateid

Laisad otsingud (t('.key')) töötavad ainult vaadetes, kus Rails teab kontrollerit ja toimingut. t('.key') kasutamine mudelis, meilisaatjas või teenuseobjektis tagastab puuduva tõlke tõrke. Väljaspool vaateid kasuta täielikke võtmeid (t('users.show.key')).

YAML-i süntaksivead rikuvad kõik tõlked

Üks YAML-i süntaksiviga (vale taane, jutumärkideta erimärgid, tühikute asemel tabeldusmärk) takistab kogu lokaadifaili laadimist. Kõik selle faili tõlked tagastavad puuduva võtme tõrke. Valideeri YAML-failid CI-s linteriga ning pane kooloneid, sulge või algavaid erimärke sisaldavad stringid jutumärkidesse.

Proovi i18n Agent'i kohe

Kukuta tõlkefail siia

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

või klõpsa faili valimiseks

Sihtkeeled

Registreerumine pole vajalikKohene hinnang

Rails i18n-i KKK