class RubyI18n::Yaml

Overview

Backend for the ruby-i18n format. This class contains methods to parse and interact with them

Defined in:

backend/ruby-i18n-yaml/ruby-i18n-yaml.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(locale_directory_path : String, reference_locale : String = "en") #

Creates a new ruby-i18n YAML instance that reads from the given locale directory path.

RubyI18n::Yaml.new("locales")

[View source]

Instance Method Detail

def create #

Returns self | Here for compatibility with Gettext::MOBackend and Gettext::POBackend

catalogue = RubyI18n::Yaml.new("locales")
catalogue == catalogue.create # => true

[View source]
def define_rule(locale : String, value : Int32 | Int64 | Float64 -> String) #

Set pluralization rules for the given locale. See RubyI18n.define_rule for more information


[View source]
def localize(locale : String, time : Time, format : String) #

Localize a date object with correspondence to a specific format.

Raises LensExceptions::MissingTranslation when the selected format doesn't exist.

NOTE Default data is provided for the English locale.

date = Time.unix(1629520612)
catalogue.localize("en", date, format: "default") # => "2021-08-21"
catalogue.localize("en", date, format: "long")    # => "July 21, 2021"
catalogue.localize("en", date, format: "short")   # => "Jul 21"

# Raises when the given format isn't defined.
catalogue.localize("ru", date, format: "short") # LensExceptions::MissingTranslation

[View source]
def localize(locale : String, number : Int32 | Int64 | Float64, type : String = "humanize", format : String? = nil) #

Localize a number with correspondence to a specific type.

Raises LensExceptions::MissingTranslation when attributes required for formatting are missing. See usage docs for more information

Currently, Lens supports 3 localization types for numbers, within the ruby-i18n YAML format.

  • Humanize
  • Percentage
  • Currency

Two different formats are available in humanize.

  • Bytes
    • Provides humanized byte size. IE 100000 bytes -> 1 MB
  • Decimal
    • Provides humanized positive numbers.

NOTE Default data is provided for the English locale.

The most basic usage is humanizing a number. For instance:

catalogue.localize("en", 1000)           # => "1 Thousand"
catalogue.localize("en", 10_250_000_000) # => "10.2 Billion"

Humanized bytes:

catalogue.localize("en", 1000, type: "humanize", format: "storage_units" # => "1 KB"
catalogue.localize("en", 1500, type: "humanize", format: "storage") # => "1.5 KB"

catalogue.localize("en", 100_000, type: "humanize", format: "bytes") # => "100 KB"
catalogue.localize("en", 120_000, type: "humanize", format: "storage") # => "120 KB"
catalogue.localize("en", 102_000, type: "humanize", format: "storage") # => "102 KB"

Localized percentages:

catalogue.localize("en", 4.528, type: "percentage").should eq("4.53%")

Localized currency:

catalogue.localize("en", 4.528, type: "currency").should eq("$4.528")

For a more detailed explanation, please refer to the usage documentation.


[View source]
def plural_rules : Hash(String, Int32 | Int64 | Float64 -> String) #

Returns all defined CLDR plural rules.


[View source]
def select(locale) #

Selects a locale to use for translations

Raises a KeyError when the selected locale isn't found.

If your application is monolingual then this along with #translate(key, count, iter) is your friend. However, if you need to switch languages on the fly then this method should be ignored.

Instead, you should use the #translate(locale, key, count, iter) overload, which allows for fetching messages from any locales without changing the state of the instance.

catalogue = RubyI18n::Yaml.new("locales")

catalogue.select("en")
catalogue.translate("translation") # => "Translated Message"

catalogue.select("example")
catalogue.translate("translation") # => "Some message in another language"

catalogue.select("doesn't exist") # raises KeyError

[View source]
def translate(key : String, count : Int | Float? = nil, iter : Int? = nil, scope : Indexable(String) | String? = nil, **kwargs) #

Fetches a translation from the selected locale with the given path (key).

Functionality is the same as RubyI18n::Yaml.translate(locale : String, key : String, count : Int | Float? = nil, iter : Int? = nil) but with the first argument removed


[View source]
def translate(locale : String, key : String, count : Int | Float? = nil, iter : Int? = nil, scope : Indexable(String) | String? = nil, **kwargs) #

Fetches a translation from the given locale with the given path (key).

Basic usage is this:

catalogue = RubyI18n::Yaml.new("locales")
catalogue.translate("en", "translation") # => "Translated Message"

This method can also translate plural-forms through the count argument.

catalogue.translate("en", "possessions.fruits.apples", 50) # => "I have 50 apples"
catalogue.translate("en", "possessions.fruits.apples", 1)  # => "I have 1 apple"

Interpolation can be done through kwargs.

# message is 'Hello there, my name is %{name} and I'm a %{profession}`.
result = catalogue.translate("en", "introduction.messages", name: "Steve", profession: "programmer")
result # => "Hello there, my name is Steve and I'm a programmer"

If the value at the given path (key) turns out to be an array then you can pass in the iter argument to select a specific value at the given index

catalogue.translate("en", "items.foods", iter: 2) # => "Hamburger"

A scope, the area from which the key-path should traverse from, can also be specified. For instance, a scope of possessions.fruits would allow the key to just be apples.

catalogue.translate("en", "possessions", 1, scope : {"possessions", "fruits"})  # => "I have 1 apple"

# Strings also work!
catalogue.translate("en", "possessions", 1, scope : "possessions.fruits")  # => "I have 1 apple"

When a translation is not found LensExceptions::MissingTranslation would be raised.


[View source]