TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published


Minimalist i18n in TypeScript

GitHub CI npm version MIT License

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


npm install @giancosta86/hermes


yarn add @giancosta86/hermes

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


  • 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


npm i @giancosta86/hermes

DownloadsWeekly Downloads






Unpacked Size

19.7 kB

Total Files


Last publish


  • giancosta86