I18n::Catalog

The default locale that is considered when no other locales are configured nor activated.

Initializes a new catalog from a specific configuration object.

This class methods provides the ability to initialize a new catalog of translation from an existing I18n::Config object: all the configuration options set on this object will be used to intialize the new catalog of translations.

Activates a locale for translations.

This method allows to set the locale used to produce translated contents. Note that once activated, the current locale will remain active until it's explicly changed again. #with_locale should be used instead of #activate for cases where it is important to ensure that the previous active locale is restored.

An I18n::Errors::InvalidLocale exception will be raised by this method if the passed locale is not available in the catalog (ie. if no translations was injected into this catalog for the considered locale).

Returns the available locales for the catalog.

If no translations have injected into the catalog of translations yet, an array with the default locale in it will be returned.

Returns the default locale used by the catalog.

Injects the hash of translations returned by a specific loader.

Injects a hash of translations into the catalog.

This method can be used to inject a hash of loaded translations into a specific catalog. This is mainly useful if a custom catalog is created manually:

loader = I18n::Loader::YAML.new("config/locales")
catalog = I18n::Catalog.new
catalog.inject(loader.load)

Alias for #localize.

Alias for #localize.

Returns the currently active locale.

The returned value will default to the default locale unless another locale is explicitly activated.

Alias for #activate.

Localizes a number.

This method allows to localize a Number object (such as an integer or a float). By default, the :default format is used:

I18n.localize(123_456.789) # => 123,456.789

Custom formats can be used as well, for example:

I18n.localize(123_456.789, :custom) # => 123,456.79

This method requires the following structure to be defined in localization files (the following example uses YAML, but this can be easily applied to JSON files too):

en:
  i18n:
    number:
      formats:
        default:
          delimiter: ","
          separator: "."
          decimal_places: 3
          group: 3
          only_significant: false

Custom formats can be defined under i18n.number.formats in order to use other combinations of delimiters, separators, decimal places, etc.

Localizes a datetime or a date.

This method allows to localize a Time object or a Tuple(Int32, Int32, Int32) object (which correspond to a date obtained through the use of Time#date). Both time or "date" objects can be localized using a predefined format such as :default, :short or :long:

I18n.localize(Time.local)             # => Sun, 13 Dec 2020 21:11:08 -0500
I18n.localize(Time.local, :short)     # => 13 Dec 21:11
I18n.localize(Time.local.date)        # => 2020-12-13
I18n.localize(Time.local.date, :long) # => December 13, 2020

Custom format strings can be specified too. For example:

I18n.localize(Time.local, "%a, %d %b %Y") # => Sun, 13 Dec 2020

This method requires the following structure to be defined in localization files (the following example uses YAML, but this can easily be applied to JSON files too):

en:
  i18n:
    date:
      abbr_day_names: [Mon, Tue, Wed, Thu, Fri, Sat, Sun]
      abbr_month_names: [Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
      day_names: [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]
      month_names: [January, February, March, April, May, June,
                    July, August, September, October, November, December]
      formats:
        default: "%Y-%m-%d"
        long: "%B %d, %Y"
        short: "%b %d"
    time:
      am: am
      formats:
        default: "%a, %d %b %Y %H:%M:%S %z"
        long: "%B %d, %Y %H:%M"
        short: "%d %b %H:%M"
      pm: pm

Alias for #translate.

Alias for #translate!.

Performs a translation lookup.

This method performs a translation lookup for a given key. If no translation can be found for the given key, a default string stating that the translation is missing will be returned.

catalog.translate("simple.translation")               # => "Simple translation"
catalog.translate("hello.user", name: "John")         # => "Hello John!"
catalog.translate(:blank, scope: "error.username")    # => "Username cannot be blank"
catalog.translate(:blank, scope: [:error, :username]) # => "Username cannot be blank"

Performs a translation lookup.

This method performs a translation lookup for a given key. If no translation can be found for the given key, an I18n::Errors::MissingTranslation exception will be raised.

catalog.translate!("simple.translation")               # => "Simple translation"
catalog.translate!("hello.user", name: "John")         # => "Hello John!"
catalog.translate!(:blank, scope: "error.username")    # => "Username cannot be blank"
catalog.translate!(:blank, scope: [:error, :username]) # => "Username cannot be blank"

Allows to activate a specific locale for a specific block.

This method allows to activate a specific locale for a specific block, ensuring that the change of locale does not leak outside of the block. When the block execution completes, the locale that was previously activated prior to the block execution will be automatically activated again:

catalog = I18n::Catalog.new(default_locale: "en")
catalog.with_locale(:es) do
  catalog.translate!("test.translation") # outputs a spanish translation
end
catalog.translate!("test.translation") # outputs an english translation

An I18n::Errors::InvalidLocale exception will be raised by this method if the passed locale is not available in the catalog (ie. if no translations was injected into this catalog for the considered locale).