Cldr.Unit.Additional (Cldr Units v3.19.2)

View Source

Additional domain-specific units can be defined to suit application requirements. In the context of ex_cldr there are two parts of configuring additional units.

  1. Configure the unit, base unit and conversion in config.exs. This is a requirement since units are compiled into code.

  2. Configure the localizations for the additional unit in a CLDR backend module.

Once configured, additional units act and behave like any of the predefined units of measure defined by CLDR.

Configuring a unit in config.exs

Under the application :ex_cldr_units define a key :additional_units with the required unit definitions. For example:

config :ex_cldr_units, :additional_units,
  vehicle: [base_unit: :unit, factor: 1, offset: 0, sort_before: :all],
  person: [base_unit: :unit, factor: 1, offset: 0, sort_before: :all]

This example defines two additional units: :vehicle and :person. The keys :base_unit, and :factor are required. The key :offset is optional and defaults to 0. The key :sort_before is optional and defaults to :none.

Configuration keys

  • :base_unit is the common denominator that is used to support conversion between like units. It can be any atom value. For example :liter is the base unit for volume units, :meter is the base unit for length units.

  • :factor is used to convert a unit to its base unit in order to support conversion. When converting a unit to another compatible unit, the unit is first multiplied by this units factor then divided by the target units factor.

  • :offset is added to a unit after applying its base factor in order to convert to another unit.

  • :sort_before determines where in this base unit sorts relative to other base units. Typically this is set to :all in which case this base unit sorts before all other base units or:none in which case this base unit sorted after all other base units. The default is :none. If in doubt, leave this key to its default.

  • :systems is list of measurement systems to which this unit belongs. The known measurement systems are :metric, :uksystem and :ussystem. The default is [:metric, :ussystem, :uksystem].

Defining localizations

Localizations are defined in a backend module through adding use Cldr.Unit.Additional to the top of the backend module and invoking Cldr.Unit.Additional.unit_localization/4 for each localization.

See Cldr.Unit.Additional.unit_localization/4 for further information.

Note that one invocation of the macro is required for each combination of locale, style and unit. An exception will be raised at runtime is a localization is expected but is not found.

Summary

Functions

merge_base_units(core_base_units, additional_base_units, acc \\ [])
unit_localization(unit, locale, style, localizations)

Although defining a unit in config.exs is enough to create, operate on and serialize an additional unit, it cannot be localised without defining localizations in an ex_cldr backend module. For example

Functions

merge_base_units(core_base_units, additional_base_units, acc \\ [])

unit_localization(unit, locale, style, localizations)

(macro)

Although defining a unit in config.exs is enough to create, operate on and serialize an additional unit, it cannot be localised without defining localizations in an ex_cldr backend module. For example:

defmodule MyApp.Cldr do
  use Cldr.Unit.Additional

  use Cldr,
    locales: ["en", "fr", "de", "bs", "af", "af-NA", "se-SE"],
    default_locale: "en",
    providers: [Cldr.Number, Cldr.Unit, Cldr.List]

  unit_localization(:person, "en", :long,
    one: "{0} person",
    other: "{0} people",
    display_name: "people"
  )

  unit_localization(:person, "en", :short,
    one: "{0} per",
    other: "{0} pers",
    display_name: "people"
  )

  unit_localization(:person, "en", :narrow,
    one: "{0} p",
    other: "{0} p",
    display_name: "p"
  )
end

Note the additions to a typical ex_cldr backend module:

  • use Cldr.Unit.Additional is required to define additional units

  • use of the unit_localization/4 macro in order to define a localization.

One invocation of unit_localization should made for each combination of unit, locale and style.

Parameters to unit_localization/4

  • unit is the name of the additional unit as an atom.

  • locale is the locale name for this localization. It should be one of the locale configured in this backend although this cannot currently be confirmed at compile time.

  • style is one of :long, :short, or :narrow.

  • localizations is a keyword like of localization strings. Two keys - :display_name and :other are mandatory. They represent the localizations for a non-count display name and :other is the localization for a unit when no other pluralization is defined.

Localisations

Localization keyword list defines localizations that match the plural rules for a given locale. Plural rules for a given number in a given locale resolve to one of six keys:

  • :zero
  • :one (singular)
  • :two (dual)
  • :few (paucal)
  • :many (also used for fractions if they have a separate class)
  • :other (required—general plural form—also used if the language only has a single form)

Only the :other key is required. For english, providing keys for :one and :other is enough. Other languages have different grammatical requirements.

The key :display_name is used by the function Cldr.Unit.display_name/1 which is primarily used to support UI applications.