Crystal I18n

# Configuration

Crystal I18n can be configured through the use of the I18n#config object (instance of I18n::Config). This object allows to configure various aspects of the behaviour of Crystal I18n, such as: how translation files are loaded, the default locale, etc.

# loaders

Default value: [] of I18n::Loader::Base

The I18n::Config#loaders method gives access to the list of configured translations loaders and allows to easily append new ones. For example:

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

Each object in the loaders array must be an instance of a subclass of I18n::Loader::Base (abstract class which defines how translations should be "loaded" in order to be injected into catalogs of translations). Crystal I18n has built-in support for two loader types:

Each of the above loader implementation supports translations organized accross multiple files (eg. multiple YAML files organized in sub-directories for a specific locale). The above loaders are initialized from an absolute or relative directory path (where translations files will be looked up).

TIP

The built-in translations loaders (YAML or JSON) provide the ability to embed raw translations in compiled binaries (so that translations files are not loaded at runtime). This is possible through the use of the #embed macro:

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

It's also possible to fully define the existing loaders at once through the use of the I18n::Config#loaders= method:

I18n.config.loaders = [I18n::Loader::YAML.new("config/locales")] of I18n::Loader::Base

WARNING

The order of #loaders is important, especially if the same translations are defined in multiple places accross files that are targetted by multiple loaders. For example in a situation where a simple.translation translation is defined by a file that is loaded by a loader L1 while the same translation is also defined by a file that is loaded by a loader L2, the second translation will be used if L1 comes first in the #loaders array.

# default_locale

Default value: "en"

The I18n::Config#default_locale= method allows to set the default locale used by Crystal I18n. The default locale is set to "en" (English) unless explicitly set:

I18n.config.default_locale = :fr

# available_locales

Default value: nil

The I18n::Config#available_locales= method allows to define the locales that can be activated in order to perform translation lookups and localizations. Unless explicitly specified, this list corresponds to the locales that are automatically discovered by translations loaders configured via the #loaders method.

I18n.config.available_locales = [:en, :fr]

# fallbacks

Default value: nil

The I18n::Config#fallbacks= method allows to set the locale fallbacks. Setting locale fallbacks will force Crystal I18n to try to lookup translations in other (configured) locales if the current locale the translation is requested into is missing.

For example, the specified fallbacks can be a hash or a named tuple defining the chains of fallbacks to use for specific locales:

I18n.config.fallbacks = {"en-CA" => ["en-US", "en"], "fr-CA" => "fr"}

It can also be a simple array of fallbacks. In that case, this chain of fallbacked locales will be used as a default for all the available locales when translations are missing:

I18n.config.fallbacks = ["en-US", "en"]

It's also possible to specficy both default fallbacks and a mapping of fallbacks by initializing an I18n::Locale::Fallbacks object as follows:

I18n.config.fallbacks = I18n::Locale::Fallbacks.new(
  {"fr-CA-special": ["fr-CA", "fr", "en"]},
  default: ["en"]
)

Finally, using nil in the context of this method will reset the configured fallbacks (and remove any previously configured fallbacks).

It's also important to always ensure that fallback locales are available locales: they should all be present in the #available_locales array.

← Translation loaders →