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.cri18n/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
-
.activate(locale : String | Symbol) : String
Activates a locale for translations.
-
.available_locales : Array(String)
Returns the available locales.
-
.config : Config
Returns the main configuration object.
-
.config=(config : Config) : Config
Allows to replace the main configuration object.
-
.init : Nil
Initializes the
I18n
module. -
.l(object : Number, format : String | Symbol = :default) : String
Alias for
#localize
. -
.l(object : Time | Tuple(Int32, Int32, Int32), format : String | Symbol = :default, **kwargs) : String
Alias for
#localize
. -
.locale : String
Returns the currently active locale.
-
.locale=(locale : String | Symbol) : String
Alias for
#activate
. -
.localize(object : Number, format : String | Symbol = :default) : String
Localizes a number.
-
.localize(object : Time | Tuple(Int32, Int32, Int32), format : String | Symbol = :default, **kwargs) : String
Localizes a datetime or a date.
-
.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
. -
.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!
. -
.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.
-
.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.
-
.with_locale(locale : String | Symbol, &)
Allows to activate a specific locale for a specific block.
Class Method Detail
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).
Returns the available locales.
If no translations have been loaded yet, an array with the default locale in it will be returned.
Returns the main configuration object.
This methods return the main I18n::Config
object used by the I18n
module to persist configuration options.
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.
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.
Alias for #localize
.
Returns the currently active locale.
The returned value will default to the default locale unless another locale is explicitly activated.
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
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
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.
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"
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"
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).