module I18n::Base
def available_locales_initialized?
def available_locales_initialized? config.available_locales_initialized? end
def config
def config Thread.current[:i18n_config] ||= I18n::Config.new end
def config=(value)
def config=(value) Thread.current[:i18n_config] = value end
def eager_load!
Rails production environment. Backends can implement whatever strategy
Tells the backend to load translations now. Used in situations like the
def eager_load! config.backend.eager_load! end
def enforce_available_locales!(locale)
def enforce_available_locales!(locale) if locale != false && config.enforce_available_locales raise I18n::InvalidLocale.new(locale) if !locale_available?(locale) end end
def exists?(key, _locale = nil, locale: _locale, **options)
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? config.backend.exists?(locale, key, options) end
def handle_exception(handling, exception, locale, key, options)
I18n.exception_handler = I18nExceptionHandler.new # an object
I18n.exception_handler.call(exception, locale, key, options) # will be called like this
I18n.exception_handler = lambda { |*args| ... } # a lambda
I18n.custom_exception_handler(exception, locale, key, options) # will be called like this
I18n.exception_handler = :custom_exception_handler # this is the default
Examples:
method #call will be called on the exception_handler object.
a method call. A Proc will simply be called. In any other case the
If exception_handler is a Symbol then it will simply be sent to I18n as
be raised or thrown (MissingTranslation).
which can be a Symbol, a Proc or any other Object unless they're forced to
Any exceptions thrown in translate will be sent to the @@exception_handler
def handle_exception(handling, exception, locale, key, options) case handling when :raise raise exception.respond_to?(:to_exception) ? exception.to_exception : exception when :throw throw :exception, exception else case handler = options[:exception_handler] || config.exception_handler when Symbol send(handler, exception, locale, key, options) else handler.call(exception, locale, key, options) end end end
def locale_available?(locale)
Returns true when the passed locale, which can be either a String or a
def locale_available?(locale) I18n.config.available_locales_set.include?(locale) end
def localize(object, locale: nil, format: nil, **options)
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
def normalize_key(key, separator)
def normalize_key(key, separator) @@normalized_key_cache[separator][key] ||= case key when Array key.flat_map { |k| normalize_key(k, separator) } else keys = key.to_s.split(separator) keys.delete('') keys.map! do |k| case k when /\A[-+]?([1-9]\d*|0)\z/ # integer k.to_i when 'true' true when 'false' false else k.to_sym end end keys end end
def normalize_keys(locale, key, scope, separator = nil)
Splits keys that contain dots into multiple keys. Makes sure all
Merges the given locale, key and scope into a single array of keys.
def normalize_keys(locale, key, scope, separator = nil) separator ||= I18n.default_separator locale = locale.to_sym if locale result = [locale] result.concat(normalize_key(scope, separator)) if scope result.concat(normalize_key(key, separator)) end
def reload!
Rails development environment. Backends can implement whatever strategy
Tells the backend to reload translations. Used in situations like the
def reload! config.clear_available_locales_set config.backend.reload! end
def translate(key = nil, throw: false, raise: false, locale: nil, **options) # TODO deprecate :raise
I18n.t(:salutation, any_hash)
I18n.t(:salutation, { :gender => 'w', :name => 'Smith' })
Bad:
I18n.t(:salutation, **any_hash)
I18n.t(:salutation, **{ :gender => 'w', :name => 'Smith' })
I18n.t(:salutation, :gender => 'w', :name => 'Smith')
Good:
The "hash" parameter must be passed as keyword argument.
There is a breaking change in ruby that produces warning with ruby 2.7 and won't work as expected with ruby 3.0
This method uses keyword arguments.
*Ruby 2.7+ keyword arguments warning*
values.
always return the same translations/values per unique combination of argument
from the argument values passed to #translate. Therefore your lambdas should
a cache layer is put in front of I18n.translate it will generate a cache key
It is recommended to use/implement lambdas in an "idempotent" way. E.g. when
lambda { |key, options| options[:gender] == 'm' ? "Mr. %{name}" : "Mrs. %{name}" }
so the following lambda would give the same result:
Note that the string returned by lambda will go through string interpolation too,
Then I18n.t(:salutation, :gender => 'w', :name => 'Smith') will result in "Mrs. Smith".
lambda { |key, options| options[:gender] == 'm' ? "Mr. #{options[:name]}" : "Mrs. #{options[:name]}" }
E.g. assuming the key :salutation resolves to:
called and passed the key and options.
Both translations and defaults can be given as Ruby lambdas. Lambdas will be
*LAMBDAS*
I18n.t [:foo, :bar], :scope => :baz
Which is the same as using a scope option:
I18n.t [:'baz.foo', :'baz.bar']
Can be used with dot-separated nested keys:
I18n.t [:foo, :bar]
This returns an array with the translations for :foo and :bar.
*BULK LOOKUP*
I18n.t :foo, :default => [:bar, 'default']
or default if no translations for :foo and :bar were found.
Returns the translation for :foo or the translation for :bar
I18n.t :foo, :default => :bar
translation for :foo was found:
This returns the translation for :foo or the translation for :bar if no
I18n.t :foo, :default => 'default'
This returns the translation for :foo or default if no translation was found:
*DEFAULTS*
I18n.t :foo, :count => 1 # => '1 foo'
be interpolated to the pluralized translation:
:foo => ['%{count} foo', '%{count} foos'], count will
E.g., with the translation
The :count option can be used both for pluralization and interpolation.
I18n.t :foo, :count => 2 # => 'Foos'
I18n.t :foo, :count => 0 # => 'Foos'
These both return the plural version of a pluralized translation:
I18n.t :foo, :count => 1 # => 'Foo'
This returns the singular version of a pluralized translation:
pluralization rules. Other algorithms can be supported by custom backends.
Note that I18n::Backend::Simple only supports an algorithm for English
are arrays of singular/plural versions of translations like ['Foo', 'Foos'].
Translation data can contain pluralized translations. Pluralized translations
*PLURALIZATION*
I18n.t :foo, :bar => 'baz' # => 'foo baz'
value for the key +bar+ will be interpolated into the translation:
E.g., with a translation :foo => "foo %{bar}" the option
the interpolation variable names.
values passed to #translate as part of the options hash, with the keys matching
Translations can contain interpolation variables which will be replaced by
*INTERPOLATION*
I18n.t 'short', :scope => %w(date formats)
I18n.t 'short', :scope => 'date.formats'
I18n.t 'formats.short', :scope => 'date'
I18n.t 'date.formats.short'
examples will all look up the same short date format:
or dot-separated keys. Keys and scopes can be combined freely. So these
Scope can be either a single key, a dot-separated key or an array of keys
I18n.t :'date.formats.short'
I18n.t 'date.formats.short'
work). E.g., the short format can be looked up using both:
Key can be either a single key or a dot-separated key (both Strings and Symbols
returns the whole translations hash {:formats => {:short => "%b %d"}}.
and the scope option. E.g., in this example I18n.t :date
Translations can be looked up at any level of this hash using the key argument
:date => {:formats => {:short => "%b %d"}}.
as namespaces. E.g., ActionView ships with the translation:
Translation data is organized as a nested hash using the upper-level keys
*LOOKUP*
scope, and default, as well as interpolation values.
Translates, pluralizes and interpolates a given key using a given locale,
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
def translate!(key, **options)
Wrapper for translate that adds :raise => true. With
def translate!(key, **options) translate(key, **options, raise: true) end
def translate_key(key, throw, raise, locale, backend, options)
def translate_key(key, throw, raise, locale, backend, options) result = catch(:exception) do backend.translate(locale, key, options) end if result.is_a?(MissingTranslation) handle_exception((throw && :throw || raise && :raise), result, locale, key, options) else result end end
def transliterate(key, throw: false, raise: false, locale: nil, replacement: nil, **options)
I18n.transliterate("Jürgen", :locale => :en) # => "Jurgen"
I18n.transliterate("Jürgen") # => "Juergen"
I18n.locale = :de
I18n.transliterate("Jürgen") # => "Jurgen"
I18n.locale = :en
Transliterating strings:
store_translations(:xx, :i18n => {:transliterate => {:rule => translit})
translit = lambda {|string| MyTransliterator.transliterate(string) }
Setting a Proc:
})
}
}
'ö' => 'oe'
'ü' => 'ue',
rule: {
transliterate: {
store_translations(:de, i18n: {
Setting a Hash using Ruby:
ö: "oe"
ü: "ue"
rule:
transliterate:
i18n:
Setting a Hash in
*Examples*
rules, while Procs do not.
single string argument. Hash rules inherit the default transliteration
Transliteration rules can either be a Hash or a Proc. Procs must accept a
i18n.transliterate.rule.
expects transliteration rules to be stored at
It's also possible to add support for per-locale transliterations. I18n
# => "???"
I18n.transliterate("日本語")
# => "AEroskobing"
I18n.transliterate("Ærøskøbing")
transliterate only Latin strings to an ASCII approximation:
Transliterates UTF-8 characters to ASCII. By default this method will
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
def with_locale(tmp_locale = nil)
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