module I18n

Overview

The I18n module provides a simple interface for internationalization and localization.

Basic setup

Assuming that a config/locales relative folder exists, with the following en.yml file in it:

en:
  simple:
    translation: "This is a simple translation"
    interpolation: "Hello, %{name}!"
    pluralization:
      one: "One item"
      other: "%{count} items"

The following I18n setup could be defined:

require "i18n"

I18n.config.loaders << I18n::Loader::YAML.new("config/locales")
I18n.init

Translations lookups

Translations can be resolved using the #translate method (or the shorter version #t) and the #translate! method (or the shorter version #t!):

I18n.t("simple.translation")                     # outputs "This is a simple translation"
I18n.t("simple.interpolation", name: "John Doe") # outputs "Hello, John Doe!"
I18n.t("simple.pluralization", count: 42)        # outputs "42 items"

Localization

It is possible to localize date time objects using the #localize method (or the shorter version #l):

I18n.l(Time.local)                 # => Sun, 13 Dec 2020 21:11:08 -0500
I18n.l(Time.local, :short)         # => 13 Dec 21:11
I18n.l(Time.local.date)            # => 2020-12-13
I18n.l(Time.local.date, :long)     # => December 13, 2020
I18n.l(Time.local, "%a, %d %b %Y") # => Sun, 13 Dec 2020

Defined in:

i18n.cr
i18n/catalog.cr
i18n/config.cr
i18n/errors.cr
i18n/loader/base.cr
i18n/loader/json.cr
i18n/loader/yaml.cr
i18n/locale/fallbacks.cr
i18n/locale/tag.cr
i18n/pluralization.cr
i18n/pluralization/rule.cr
i18n/pluralization/rule/arabic.cr
i18n/pluralization/rule/breton.cr
i18n/pluralization/rule/central_morocco_tamazight.cr
i18n/pluralization/rule/colognian.cr
i18n/pluralization/rule/east_slavic.cr
i18n/pluralization/rule/irish.cr
i18n/pluralization/rule/langi.cr
i18n/pluralization/rule/latvian.cr
i18n/pluralization/rule/lithuanian.cr
i18n/pluralization/rule/macedonian.cr
i18n/pluralization/rule/maltese.cr
i18n/pluralization/rule/manx.cr
i18n/pluralization/rule/one_other.cr
i18n/pluralization/rule/one_two_other.cr
i18n/pluralization/rule/one_up_to_two_other.cr
i18n/pluralization/rule/one_with_zero_other.cr
i18n/pluralization/rule/other.cr
i18n/pluralization/rule/polish.cr
i18n/pluralization/rule/romanian.cr
i18n/pluralization/rule/scottish_gaelic.cr
i18n/pluralization/rule/slovenian.cr
i18n/pluralization/rule/upper_sorbian.cr
i18n/pluralization/rule/welsh.cr
i18n/pluralization/rule/west_slavic.cr
i18n/translation_hash.cr

Constant Summary

VERSION = "0.2.1"

Class Method Summary

Class Method Detail

def self.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 main catalog of translations (ie. if no translations were defined for the considered locale).


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

Returns the available locales.

If no translations have been loaded yet, an array with the default locale in it will be returned.


[View source]
def self.config : Config #

Returns the main configuration object.

This methods return the main I18n::Config object used by the I18n module to persist configuration options.


[View source]
def self.config=(config : Config) : Config #

Allows to replace the main configuration object.

This method will replace the main configuration object used by the I18n module but will not change the main catalog of translation. Calling #init once the new I18n::Config object has been assigned might be necessary in order to ensure that the main catalog of translations used by the I18n module is reinitialized.


[View source]
def self.init : Nil #

Initializes the I18n module.

Calling this method at application startup is necessary in order to ensure that the configuration options that were set through the use of the I18n::Config object (returned by the #config method) are read in order to initialize the main catalog of translations. Calling this will ensure that the translations files that were defined using I18n::Config#loaders are read and processed in order to allow further translations lookups.


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

Alias for #localize.


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

Alias for #localize.


[View source]
def self.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 self.locale=(locale : String | Symbol) : String #

Alias for #activate.


[View source]
def self.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, but custom formats can be used as well:

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

[View source]
def self.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, but custom formats can be used as well:

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
I18n.localize(Time.local, "%a, %d %b %Y") # => Sun, 13 Dec 2020

[View source]
def self.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 self.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 self.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.

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

[View source]
def self.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.

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

[View source]
def self.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:

I18n.config.default_locale # outputs "en"
I18n.with_locale(:es) do
  I18n.translate!("test.translation") # outputs a spanish translation
end
I18n.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 (ie. if no translations were defined for this locale).


[View source]