Nutritious Pumpkin Masses

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

    4.3.2 • Public • Published

    npm package License Build Status Coverage Status Issues

    intl-ts - Type safe internationalization library

    intl-ts is an i18n (internationalization) library for TypeScript. The package is compiled in ES2015 and so can also be used by JavaScript applications, but may require a Babel translation to be used with browsers. Its main features are:

    • Type safe: using a wrong message name or the wrong type for the parameters will be checked at compile time. If your IDE allow it, you may even have completion for message names.
    • Mutable or immutable: the library can be used in an immutable way (good for most state-aware framework, like React/Redux), or in a mutable way (for better performance).
    • MobX integration: if you are using MobX, the $preferences property of the Intl object will automatically become observable, allowing, for example, React components to automatically refresh when chosen language changes.
    • Agnostic: can be used both at server (NodeJS) or browser side.

    If you were using a previous version of the library, you may be interested by the migration guide


    Documents, messages, code (including variable names and comments), are in English.

    Anyway, because Slune is French firm, all documents and important messages must also be provided in French. Other translations are welcome.

    🇫🇷 Une version française de ce document se trouve ici.


    Installation is done using npm install command:

    $ npm install --save intl-ts


    • Create your language strings (messages):
    // English version — default
    const en = createMessages({
      $: 'English',
      welcome: 'Welcome here!',
      hello: (name: string) => `Hello ${name}`,
      showElementCount: (count: number) => {
        switch (count) {
          case 0: {
            return 'There are no elements'
          case 1: {
            return 'There is one element'
          default: {
            return `There are ${count} elements`
    // Type describing messages
    type langType = typeof en
    // French version — full
    const fr = createMessages<langType>({
      $: 'Français',
      welcome: 'Bienvenue ici !',
      hello: (name: string) => `Bonjour ${name}`,
      showElementCount: (count: number) => {
        switch (count) {
          case 0: {
            return 'Il n’y a pas d’éléments'
          case 1: {
            return 'Il y a un élément'
          default: {
            return `Il y a ${count} elements`
    // Canada french version — partial
    const fr_ca = createMessages<PartialMessages<langType>>({
      $: 'Français (Canada)',
      welcome: 'Bienvenue icitte !',
    // Esperanto version — partial
    const eo = createMessages<PartialMessages<langType>>({
      $: 'Esperanto',
      welcome: 'Bonvenon ĉi-tie!',
      hello: (name: string) => `Saluton ${name}`,

    The function createMessages is actually an identity function and is therefore not mandatory. Its sole purpose is to allow TypeScript to check the type of the given messages.

    Note that the message names must not contain one of the keyword of the Intl API.

    • Create the corresponding language map:
    // Direct creation
    const languageMap = new LanguageMap({
      default: en,
      en: 'default',
    // Dynamic creation
    const languageMap = new LanguageMap(en, 'en').merge({ fr, fr_ca }).merge({ eo })

    Note that you should only use lowercase letters, digits and underscores as keys in language maps, because language codes will be formatted this way by the Intl class.

    • Create the internationalization object, and use it!
    const lang = new Intl<langType>(languageMap, ['eo', 'fr-CA'])
    lang.welcome() // 'Bonvenon ĉi-tie!'
    lang.showElementCount(0) // 'Il n’y a pas d’éléments' — Compilation check that 0 is of type number


    Object states will never change except:

    • Internal string representation of the LanguageMap (because of lazy initialization),
    • if you choose to update the language preferences with Intl.$changePreferences, but you can choose to update them by cloning initial object using the copy constructor.

    A new object is created when calling LanguageMap.merge().



    Even though we cannot guarantee a response time, please feel free to file an issue if you have any question or problem using the package.

    Pull Requests are welcome. You can, of course, submit corrections or improvements for code, but do not hesitate to also improve documentation, even for small spell or grammar errors.


    npm i intl-ts

    DownloadsWeekly Downloads






    Unpacked Size

    27 kB

    Total Files


    Last publish


    • sveyret