@giancosta86/hermes

hermes

Minimalist i18n in TypeScript

hermes is a TypeScript library tackling the issues of internationalization (i18n) with minimalist and elegant tools.

Installation

npm install @giancosta86/hermes

or

yarn add @giancosta86/hermes

The public API entirely resides in the root package index, so one shouldn't reference specific modules.

Usage

• IsoDateFormat: formats IsoDate objects - as defined in time-utils. It can be constructed with the same options as DateTimeFormat - also supporting reasonable defaults

• Noun: defines a noun - which can have a singular and a plural form. Case-based declension is not supported at present, but one can use case-keyed maps of Noun values

• MeasureUnit takes a Noun and provides a get() method, which returns:

  • the singular form if the value is +1 or -1

  • the plural form otherwise

• Language is a semantically useful type alias for string

• LocaleLike - can be either a BCP47 language tag string or an Ìntl.Locale object

• localeNuances is an array containing the i18n-related properties of an Intl.Locale instance except the language attribute

• ensureLocale() takes a LocaleLike and always returns an Intl.Locale

• ensureLanguageTag() takes a LocaleLike and returns its BCP47 language tag

• getLocaleDistance() takes two LocaleLike, converts them to Intl.Locale and returns:

  • Number.POSITIVE_INFINITY if the two language attributes are different

  • 0 if all the other i18n-related attributes (localeNuances) are equal, otherwise +1 is added for every non-matching attribute

• BilingualLibrary is a library of BilingualDictionary instances and can be built via static methods; additionally, Phrase is just a type alias for string that identifies each side of a dictionary translation.

  Each dictionary can be retrieved from a library via a LocaleLike - not necessarily via an exact match, but by proximity: the dictionary registered with the most matching locale (shorter or longer) is returned; the proximity is computed with getLocaleDistance(), as described above.

  If a library is requested an unregistered locale, an empty dictionary is returned; if a dictionary is requested a phrase it does not contain, the original phrase itself is returned.

Further references

• IETF BCP 47 - Standardized codes that are used to identify human languages

• time-utils - Time-related utilities

• Rimbu - Immutable collections and tools for TypeScript