hermes
Minimalist i18n in TypeScript
hermes is a TypeScript library tackling the issues of internationalization (i18n) with minimalist and elegant tools.
Installation
The package on NPM is:
@giancosta86/hermes
The public API entirely resides in the root package index, so one shouldn't reference specific modules.
Usage
-
IsoDateFormat
: formatsIsoDate
objects - as defined in time-utils. It can be constructed with the same options asDateTimeFormat
- also supporting reasonable defaults in itsdefaultOptions
static property -
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 ofNoun
values -
MeasureUnit
takes aNoun
and provides adeclineFor()
method, which returns:-
the
singular
form if the value is +1 or -1 -
the
plural
form otherwise
-
-
Language
is a semantically useful type alias forstring
-
LocaleLike
- can be either a BCP47 language tag string or anÌntl.Locale
object; its namespace provides:-
languageFacets
: an array containing the i18n-related attribute names of anIntl.Locale
instance except thelanguage
attribute -
toLocale()
takes aLocaleLike
and always returns anIntl.Locale
-
toLanguageTag()
takes aLocaleLike
and returns its BCP47 language tag -
getDistance()
takes twoLocaleLike
, converts them toIntl.Locale
and returns:-
Number.POSITIVE_INFINITY
if the twolanguage
attributes are different -
0
if all the other i18n-related attributes (languageFacets
) are equal, otherwise+1
is added for every non-matching attribute
-
-
createProximityContext()
: creates a context for aProximityMap
based
-
-
The
Dictionary
class provides:-
translate(<phrase string>)
: to return the translation registered for the given phrase; if a translation is not registered, the original phrase itself is returned -
toRawTranslations()
: returns an object whose keys are the registered phrases, with the related translations as values; the returned type isRawTranslations
A dictionary can be built via:
-
the constructor, expecting a Rimbu
RMap
-
the static
fromRawTranslations
method, expecting a plain object whose entries are the translations
-
-
DictionaryLibrary
is a container of virtually illimitedDictionary
instances - and can only be built via static methods.Each dictionary can be retrieved from a library via
getDictionary(LocaleLike)
- not necessarily via an exact match, but by proximity: the dictionary registered with the most matching locale (shorter or longer) is returned; proximity is computed withLocaleLike.getDistance()
, as described above.The registered locales are returned by the
streamLocales()
method; if a library is requested an unregistered locale, an empty dictionary is returned - so translations will always return the requested phrase itself.
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