Module: I18n::Base
- Included in:
- I18n
- Defined in:
- lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb
Instance Method Summary collapse
- #available_locales_initialized? ⇒ Boolean
-
#config ⇒ Object
Gets I18n configuration object.
-
#config=(value) ⇒ Object
Sets I18n configuration object.
-
#eager_load! ⇒ Object
Tells the backend to load translations now.
-
#enforce_available_locales!(locale) ⇒ Object
Raises an InvalidLocale exception when the passed locale is not available.
-
#exists?(key, _locale = nil, locale: _locale, **options) ⇒ Boolean
Returns true if a translation exists for a given key, otherwise returns false.
-
#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.
-
#localize(object, locale: nil, format: nil, **options) ⇒ Object
(also: #l)
Localizes certain objects, such as dates and numbers to local formatting.
-
#normalize_keys(locale, key, scope, separator = nil) ⇒ Object
Merges the given locale, key and scope into a single array of keys.
-
#reload! ⇒ Object
Tells the backend to reload translations.
-
#translate(key = nil, throw: false, raise: false, locale: nil, **options) ⇒ Object
(also: #t)
Translates, pluralizes and interpolates a given key using a given locale, scope, and default, as well as interpolation values.
-
#translate!(key, **options) ⇒ Object
(also: #t!)
Wrapper for
translate
that adds:raise => true
. -
#transliterate(key, throw: false, raise: false, locale: nil, replacement: nil, **options) ⇒ Object
Transliterates UTF-8 characters to ASCII.
-
#with_locale(tmp_locale = nil) ⇒ Object
Executes block with given I18n.locale set.
Instance Method Details
#available_locales_initialized? ⇒ Boolean
355 356 357 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 355 def available_locales_initialized? config.available_locales_initialized? end |
#config ⇒ Object
Gets I18n configuration object.
56 57 58 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 56 def config Thread.current[:i18n_config] ||= I18n::Config.new end |
#config=(value) ⇒ Object
Sets I18n configuration object.
61 62 63 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 61 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.
90 91 92 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 90 def eager_load! config.backend.eager_load! end |
#enforce_available_locales!(locale) ⇒ Object
Raises an InvalidLocale exception when the passed locale is not available.
349 350 351 352 353 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 349 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.
235 236 237 238 239 240 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 235 def exists?(key, _locale = nil, locale: _locale, **) 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, ) 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.
344 345 346 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 344 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.
304 305 306 307 308 309 310 311 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 304 def localize(object, locale: nil, format: nil, **) locale ||= config.locale raise Disabled.new('l') if locale == false enforce_available_locales!(locale) format ||= :default config.backend.localize(locale, object, format, ) 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.
332 333 334 335 336 337 338 339 340 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 332 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.
82 83 84 85 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 82 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, | [:gender] == 'm' ? "Mr. #{[:name]}" : "Mrs. #{[:name]}" }
Then <tt>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, | [: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)
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 210 def translate(key = nil, throw: false, raise: false, locale: nil, **) # 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, ) end else translate_key(key, throw, raise, locale, backend, ) 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
229 230 231 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 229 def translate!(key, **) translate(key, **, 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"
293 294 295 296 297 298 299 300 301 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 293 def transliterate(key, throw: false, raise: false, locale: nil, replacement: nil, **) 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, ) end |
#with_locale(tmp_locale = nil) ⇒ Object
Executes block with given I18n.locale set.
315 316 317 318 319 320 321 322 323 324 325 326 327 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/i18n-1.12.0/lib/i18n.rb', line 315 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 |