class I18n::Catalog

Overview

A catalog of translations.

Catalogs of translations hold all the translations for multiple locales and provide the ability to activate specific locales in order to define in which locales the translated strings should be returned.

Defined in:

i18n/catalog.cr

Constant Summary

DEFAULT_LOCALE = "en"

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

Constructors

Instance Method Summary

Constructor Detail

def self.from_config(config : Config) : self #

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.


[View source]
def self.new(default_locale : String = DEFAULT_LOCALE, available_locales : Array(String) | Nil = nil, fallbacks : Locale::Fallbacks | Nil = nil) #

[View source]

Instance Method Detail

def activate(locale : String | Symbol) : String #

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).


[View source]
def available_locales : Array(String) #

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.


[View source]
def default_locale : String #

Returns the default locale used by the catalog.


[View source]
def inject(loader : Loader::Base) : Nil #

Injects the hash of translations returned by a specific loader.


[View source]
def inject(translations : TranslationsHash) : Nil #

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)

[View source]
def l(object : Number, format : String | Symbol = :default) : String #

Alias for #localize.


[View source]
def l(object : Time | Tuple(Int32, Int32, Int32), format : String | Symbol = :default, **kwargs) : String #

Alias for #localize.


[View source]
def locale : String #

Returns the currently active locale.

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


[View source]
def locale=(locale : String | Symbol) : String #

Alias for #activate.


[View source]
def localize(object : Number, format : String | Symbol = :default) : String #

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.


[View source]
def localize(object : Time | Tuple(Int32, Int32, Int32), format : String | Symbol = :default, **kwargs) : String #

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

[View source]
def t(key : String | Symbol, params : Hash | NamedTuple | Nil = nil, count : Float | Int | Nil = nil, scope : Array(String | Symbol) | String | Symbol | Nil = nil, default = nil, **kwargs) : String #

Alias for #translate.


[View source]
def t!(key : String | Symbol, params : Hash | NamedTuple | Nil = nil, count : Float | Int | Nil = nil, scope : Array(String | Symbol) | String | Symbol | Nil = nil, default = nil, **kwargs) : String #

Alias for #translate!.


[View source]
def translate(key : String | Symbol, params : Hash | NamedTuple | Nil = nil, count : Float | Int | Nil = nil, scope : Array(String | Symbol) | String | Symbol | Nil = nil, default = nil, **kwargs) : String #

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"

[View source]
def translate!(key : String | Symbol, params : Hash | NamedTuple | Nil = nil, count : Float | Int | Nil = nil, scope : Array(String | Symbol) | String | Symbol | Nil = nil, default = nil, **kwargs) : String #

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"

[View source]
def with_locale(locale : String | Symbol, &) #

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).


[View source]