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

3.1.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.


The package on NPM is:


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 in its defaultOptions 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 of Noun values

  • MeasureUnit takes a Noun and provides a declineFor() 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; its namespace provides:

    • languageFacets: an array containing the i18n-related attribute names of an Intl.Locale instance except the language attribute

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

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

    • getDistance() 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 (languageFacets) are equal, otherwise +1 is added for every non-matching attribute

    • createProximityContext(): creates a context for a ProximityMap 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 is RawTranslations

    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 illimited Dictionary 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 with LocaleLike.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

Package Sidebar


npm i @giancosta86/hermes

Weekly Downloads






Unpacked Size

24.9 kB

Total Files


Last publish


  • giancosta86