class I18n::Catalog
- I18n::Catalog
- Reference
- Object
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.crConstant Summary
-
DEFAULT_LOCALE =
"en"
-
The default locale that is considered when no other locales are configured nor activated.
Constructors
-
.from_config(config : Config) : self
Initializes a new catalog from a specific configuration object.
- .new(default_locale : String = DEFAULT_LOCALE, available_locales : Array(String) | Nil = nil, fallbacks : Locale::Fallbacks | Nil = nil)
Instance Method Summary
-
#activate(locale : String | Symbol) : String
Activates a locale for translations.
-
#available_locales : Array(String)
Returns the available locales for the catalog.
-
#default_locale : String
Returns the default locale used by the catalog.
-
#inject(loader : Loader::Base) : Nil
Injects the hash of translations returned by a specific loader.
-
#inject(translations : TranslationsHash) : Nil
Injects a hash of translations into the catalog.
-
#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.
Constructor Detail
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.
Instance 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 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.
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
.
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:
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).