Module: I18n::Base

Included in:
I18n
Defined in:
lib/i18n.rb

Instance Method Summary collapse

Instance Method Details

#available_locales_initialized? ⇒ Boolean

Returns:

  • (Boolean) 


386
387
388
 
# File 'lib/i18n.rb', line 386

def available_locales_initialized?
  config.available_locales_initialized?
end

#config ⇒ Object

Gets I18n configuration object.



57
58
59
 
# File 'lib/i18n.rb', line 57

def config
  Thread.current[:i18n_config] ||= I18n::Config.new
end

#config=(value) ⇒ Object

Sets I18n configuration object.



62
63
64
 
# File 'lib/i18n.rb', line 62

def config=(value)
  Thread.current[:i18n_config] = value
end

#eager_load! ⇒ Object

Tells the backend to load translations now. Used in situations like the Rails production environment. Backends can implement whatever strategy is useful.



91
92
93
 
# File 'lib/i18n.rb', line 91

def eager_load!
  config.backend.eager_load!
end

#enforce_available_locales!(locale) ⇒ Object

Raises an InvalidLocale exception when the passed locale is not available.



380
381
382
383
384
 
# File 'lib/i18n.rb', line 380

def enforce_available_locales!(locale)
  if locale != false && config.enforce_available_locales
    raise I18n::InvalidLocale.new(locale) if !locale_available?(locale)
  end
end

#exists?(key, _locale = nil, locale: _locale, **options) ⇒ Boolean

Returns true if a translation exists for a given key, otherwise returns false.

Returns:

  • (Boolean)

Raises:



265
266
267
268
269
270
271
 
# File 'lib/i18n.rb', line 265

def exists?(key, _locale = nil, locale: _locale, **options)
  locale ||= config.locale
  raise Disabled.new('exists?') if locale == false
  raise I18n::ArgumentError if (key.is_a?(String) && key.empty?) || key.nil?

  config.backend.exists?(locale, key, options)
end

#interpolation_keys(key, **options) ⇒ Object

Returns an array of interpolation keys for the given translation key

Examples

Suppose we have the following:

I18n.t 'example.zero' == 'Zero interpolations'
I18n.t 'example.one' == 'One interpolation %{foo}'
I18n.t 'example.two' == 'Two interpolations %{foo} %{bar}'
I18n.t 'example.three' == ['One %{foo}', 'Two %{bar}', 'Three %{baz}']
I18n.t 'example.one', locale: :other == 'One interpolation %{baz}'

Then we can expect the following results:

I18n.interpolation_keys('example.zero') #=> []
I18n.interpolation_keys('example.one') #=> ['foo']
I18n.interpolation_keys('example.two') #=> ['foo', 'bar']
I18n.interpolation_keys('example.three') #=> ['foo', 'bar', 'baz']
I18n.interpolation_keys('one', scope: 'example', locale: :other) #=> ['baz']
I18n.interpolation_keys('does-not-exist') #=> []
I18n.interpolation_keys('example') #=> []

Raises:



254
255
256
257
258
259
260
261
262
 
# File 'lib/i18n.rb', line 254

def interpolation_keys(key, **options)
  raise I18n::ArgumentError if !key.is_a?(String) || key.empty?

  return [] unless exists?(key, **options.slice(:locale, :scope))

  translation = translate(key, **options.slice(:locale, :scope))
  interpolation_keys_from_translation(translation)
    .flatten.compact
end

#locale_available?(locale) ⇒ Boolean

Returns true when the passed locale, which can be either a String or a Symbol, is in the list of available locales. Returns false otherwise.

Returns:

  • (Boolean) 


375
376
377
 
# File 'lib/i18n.rb', line 375

def locale_available?(locale)
  I18n.config.available_locales_set.include?(locale)
end

#localize(object, locale: nil, format: nil, **options) ⇒ Object Also known as: l

Localizes certain objects, such as dates and numbers to local formatting.

Raises:



335
336
337
338
339
340
341
342
 
# File 'lib/i18n.rb', line 335

def localize(object, locale: nil, format: nil, **options)
  locale ||= config.locale
  raise Disabled.new('l') if locale == false
  enforce_available_locales!(locale)

  format ||= :default
  config.backend.localize(locale, object, format, options)
end

#normalize_keys(locale, key, scope, separator = nil) ⇒ Object

Merges the given locale, key and scope into a single array of keys. Splits keys that contain dots into multiple keys. Makes sure all keys are Symbols.



363
364
365
366
367
368
369
370
371
 
# File 'lib/i18n.rb', line 363

def normalize_keys(locale, key, scope, separator = nil)
  separator ||= I18n.default_separator

  [
    *normalize_key(locale, separator),
    *normalize_key(scope, separator),
    *normalize_key(key, separator)
  ]
end

#reload! ⇒ Object

Tells the backend to reload translations. Used in situations like the Rails development environment. Backends can implement whatever strategy is useful.



83
84
85
86
 
# File 'lib/i18n.rb', line 83

def reload!
  config.clear_available_locales_set
  config.backend.reload!
end

#translate(key = nil, throw: false, raise: false, locale: nil, **options) ⇒ Object Also known as: t

Translates, pluralizes and interpolates a given key using a given locale, scope, and default, as well as interpolation values.

LOOKUP

Translation data is organized as a nested hash using the upper-level keys as namespaces. E.g., ActionView ships with the translation: :date => {:formats => {:short => "%b %d"}}.

Translations can be looked up at any level of this hash using the key argument and the scope option. E.g., in this example I18n.t :date returns the whole translations hash {:formats => {:short => "%b %d"}}.

Key can be either a single key or a dot-separated key (both Strings and Symbols work). E.g., the short format can be looked up using both:

I18n.t 'date.formats.short'
I18n.t :'date.formats.short'

Scope can be either a single key, a dot-separated key or an array of keys or dot-separated keys. Keys and scopes can be combined freely. So these examples will all look up the same short date format:

I18n.t 'date.formats.short'
I18n.t 'formats.short', :scope => 'date'
I18n.t 'short', :scope => 'date.formats'
I18n.t 'short', :scope => %w(date formats)

INTERPOLATION

Translations can contain interpolation variables which will be replaced by values passed to #translate as part of the options hash, with the keys matching the interpolation variable names.

E.g., with a translation :foo => "foo %{bar}" the option value for the key bar will be interpolated into the translation:

I18n.t :foo, :bar => 'baz' # => 'foo baz'

PLURALIZATION

Translation data can contain pluralized translations. Pluralized translations are arrays of singular/plural versions of translations like ['Foo', 'Foos'].

Note that I18n::Backend::Simple only supports an algorithm for English pluralization rules. Other algorithms can be supported by custom backends.

This returns the singular version of a pluralized translation:

I18n.t :foo, :count => 1 # => 'Foo'

These both return the plural version of a pluralized translation:

I18n.t :foo, :count => 0 # => 'Foos'
I18n.t :foo, :count => 2 # => 'Foos'

The :count option can be used both for pluralization and interpolation. E.g., with the translation :foo => ['%{count} foo', '%{count} foos'], count will be interpolated to the pluralized translation:

I18n.t :foo, :count => 1 # => '1 foo'

DEFAULTS

This returns the translation for :foo or default if no translation was found:

I18n.t :foo, :default => 'default'

This returns the translation for :foo or the translation for :bar if no translation for :foo was found:

I18n.t :foo, :default => :bar

Returns the translation for :foo or the translation for :bar or default if no translations for :foo and :bar were found.

I18n.t :foo, :default => [:bar, 'default']

BULK LOOKUP

This returns an array with the translations for :foo and :bar.

I18n.t [:foo, :bar]

Can be used with dot-separated nested keys:

I18n.t [:'baz.foo', :'baz.bar']

Which is the same as using a scope option:

I18n.t [:foo, :bar], :scope => :baz

LAMBDAS

Both translations and defaults can be given as Ruby lambdas. Lambdas will be called and passed the key and options.

E.g. assuming the key :salutation resolves to:

lambda { |key, options| options[:gender] == 'm' ? "Mr. #{options[:name]}" : "Mrs. #{options[:name]}" }

Then I18n.t(:salutation, :gender => 'w', :name => 'Smith') will result in “Mrs. Smith”.

Note that the string returned by lambda will go through string interpolation too, so the following lambda would give the same result:

lambda { |key, options| options[:gender] == 'm' ? "Mr. %{name}" : "Mrs. %{name}" }

It is recommended to use/implement lambdas in an “idempotent” way. E.g. when a cache layer is put in front of I18n.translate it will generate a cache key from the argument values passed to #translate. Therefore your lambdas should always return the same translations/values per unique combination of argument values.

Ruby 2.7+ keyword arguments warning

This method uses keyword arguments. There is a breaking change in ruby that produces warning with ruby 2.7 and won’t work as expected with ruby 3.0 The “hash” parameter must be passed as keyword argument.

Good:

I18n.t(:salutation, :gender => 'w', :name => 'Smith')
I18n.t(:salutation, **{ :gender => 'w', :name => 'Smith' })
I18n.t(:salutation, **any_hash)

Bad:

I18n.t(:salutation, { :gender => 'w', :name => 'Smith' })
I18n.t(:salutation, any_hash)

Raises:



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/i18n.rb', line 211

def translate(key = nil, throw: false, raise: false, locale: nil, **options) # TODO deprecate :raise
  locale ||= config.locale
  raise Disabled.new('t') if locale == false
  enforce_available_locales!(locale)

  backend = config.backend

  if key.is_a?(Array)
    key.map do |k|
      translate_key(k, throw, raise, locale, backend, options)
    end
  else
    translate_key(key, throw, raise, locale, backend, options)
  end
end

#translate!(key, **options) ⇒ Object Also known as: t!

Wrapper for translate that adds :raise => true. With this option, if no translation is found, it will raise I18n::MissingTranslationData



230
231
232
 
# File 'lib/i18n.rb', line 230

def translate!(key, **options)
  translate(key, **options, raise: true)
end

#transliterate(key, throw: false, raise: false, locale: nil, replacement: nil, **options) ⇒ Object

Transliterates UTF-8 characters to ASCII. By default this method will transliterate only Latin strings to an ASCII approximation:

I18n.transliterate("Ærøskøbing")
# => "AEroskobing"

I18n.transliterate("日本語")
# => "???"

It’s also possible to add support for per-locale transliterations. I18n expects transliteration rules to be stored at i18n.transliterate.rule.

Transliteration rules can either be a Hash or a Proc. Procs must accept a single string argument. Hash rules inherit the default transliteration rules, while Procs do not.

Examples

Setting a Hash in <locale>.yml:

i18n:
  transliterate:
    rule:
      ü: "ue"
      ö: "oe"

Setting a Hash using Ruby:

store_translations(:de, i18n: {
                     transliterate: {
                       rule: {
                         'ü' => 'ue',
                         'ö' => 'oe'
                       }
                     }
                   })

Setting a Proc:

translit = lambda {|string| MyTransliterator.transliterate(string) }
store_translations(:xx, :i18n => {:transliterate => {:rule => translit})

Transliterating strings:

I18n.locale = :en
I18n.transliterate("Jürgen") # => "Jurgen"
I18n.locale = :de
I18n.transliterate("Jürgen") # => "Juergen"
I18n.transliterate("Jürgen", :locale => :en) # => "Jurgen"
I18n.transliterate("Jürgen", :locale => :de) # => "Juergen"



324
325
326
327
328
329
330
331
332
 
# File 'lib/i18n.rb', line 324

def transliterate(key, throw: false, raise: false, locale: nil, replacement: nil, **options)
  locale ||= config.locale
  raise Disabled.new('transliterate') if locale == false
  enforce_available_locales!(locale)

  config.backend.transliterate(locale, key, replacement)
rescue I18n::ArgumentError => exception
  handle_exception((throw && :throw || raise && :raise), exception, locale, key, options)
end

#with_locale(tmp_locale = nil) ⇒ Object

Executes block with given I18n.locale set.



346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/i18n.rb', line 346

def with_locale(tmp_locale = nil)
  if tmp_locale == nil
    yield
  else
    current_locale = self.locale
    self.locale = tmp_locale
    begin
      yield
    ensure
      self.locale = current_locale
    end
  end
end