Express Rest i18n

Dead simple i18n middleware for Express REST APIs.
Easy usage, no dependencies, simple integration and well tested.

Getting Started

1. Add the dependency

npm install express-rest-i18n

2. Create the i18n instance.

You can also create a module that exports you instance, if you prefer.

const i18nCreate = require('express-rest-i18n');

const i18n = i18nCreate({
  defaultLocale: 'en',
  warn: false, // optional
  allowFallback: true, // optional
  messages: {
    'en': {
      hello: 'Hello',
      nested: {
        world: 'World'
      }
    },

    'pt-br': {
      hello: 'Olá',
      nested: {
        world: 'Mundo'
      }
    }
  },
});

4. Add the i18n Middeware on Express

const express = require('express');

const app = express();

app.use(i18n.middleware);

Attention: if are using body-parser, add the i18n middleware AFTER the body parser addition, so the i18n will recognize it.

5. Use it

app.get('*', (req, res) => {
  const helloWorld = `${res.i18n.t('hello')} ${res.i18n.t('nested.world')}`;

  res.status(200).send(helloWorld);  
});

The t() method

The i18n instance contains the t() method which does the translations for you. When you add the i18n.middleware to your express, the t() method is exposed on your req and res objects. This is the t() method signature

function t(keypath: string, locale?:string) : str | any

The t() instance method

When using the t() method on your i18n instance:

i18n.t('hello'); // will output "Hello"
i18n.t('hello', 'pt-br'); // will outout "Olá"

The t() middleware method

When inside the express (as a middleware), the t() method is exposed on your req and res objects. The locale is automatically infered from the request, or the defaultLocale will be used:

app.get('*', (req, res) => {
  /*
    if the request doesnt specify any locale, the const hello will be "Hello",
    if specify a locale, the result will be in the given local, for pt-br
    for example, would be "Olá", for a non-existent locale or if the given locale
    doesnt contains the "hello" key, it will be fallbacked to the defaultLocale
  */
  const hello = res.i18n.t('hello');

  res.status(200).send(hello); // will output hello  
});

You can also force a locale even using it as a middleware

app.get('*', (req, res) => {
  const hello = res.i18n.t('hello', 'pt-br'); // will return "Olá" no matter the request locale

  res.status(200).send(hello); 
});

Nesting

You can specify nested paths to translate from your messages

i18n.t('nested.world'); // will output "World"

Side cases

When a key is not found on the given or default locale, or the argument passed is not a string, the t() method will return the argument untouched:

i18n.t('non.existing.key'); // will output "non.existing.key"
i18n.t({ test: "test"});  // will output object { test: "test"}

Messages

Your messages are passed to the i18n instance using the messages key on options. A common approach is to put the messages in a separated file. In the messages object, the first key level is the locale, and the nested keys are the messages. Example:

// messages.js file
module.exports = {
  'en': { // locale
    hello: 'Hello',
    nested: {
      world: 'World'
    }
  },

  'pt-br': { // locale
    hello: 'Olá',
    nested: {
      world: 'Mundo'
    }
  }
}

Then on your instance creation:

const message = require('./messages.js');

const i18n = i18nCreate({
  messages: messages,
  defaultLocale: 'pt-br'
});

Locales

If you dont pass any locale, your defaultLocale will be used as the translation language. Anyway, you can specify a locale to your API in 3 different ways. When specifying the locale on your request you dont need to do anything server-side, the i18n.t() will automatically handle the response using the locale passed via request.

Headers

You can pass the API language (locale) from the request headers, just set the application-language on headers passing the desired locale, in the example below, we are saying that we want the results in "en" language:

fetch('http://api-address.com/', {
  headers: { 'application-language': 'en' }
})
  .then(response => { ... })
  .catch(err => { ... });

Query

You can pass the desired locale via address query. In the example below you will be setting the results to "en" language:

fetch('http://api-address.com/?locale=en')
  .then(response => { ... })
  .catch(err => { ... });

Body

You can also pass the desired locale on your request body. You must be using body-parser on your express to use this option:

fetch('http://api-address.com/', {
  method: 'post',
  body: JSON.stringify({ locale: 'en' })
})
  .then(response => { ... })
  .catch(err => { ... });

Locale fallback

The defaultLocale will be used as a fallback when you:

1. Doesn't specify any locale
2. Pass a locale that doesn't exists on your messages
3. Pass a key to be translated which doesn't exists on the current locale (not the default)

Options

You can pass the following options to the instance:

const i18n = i18nCreate({
  defaultLocale: 'pt-br', // required, set the default locale
  warn: false, // optional // show warns on fallbacks and errors
  allowFallback: true, // if no fallback
  messages: {}, // your locales and messages
});

Methods

t()

Ask for translations. Ex:

i18n.t('hello'); // will output "Hello"

locale()

Return the current locale being used on instance

i18n.locale(); // will output "en"

setOptions()

Overrides options on the fly. Example for change default locale and warn levels:

i18n.setOptions({
  warn: true,
  defaultLocale: 'pt-br',
});

Development

The sources are in src folder. Start with npm install, then:

Build

npm run build

Test

npm run test

---

Express Rest i18n by Felippe Regazio