flitter-i18n

Flitter-i18n provides localization and internationalization services for Flitter.

Installation

flitter-i18n ships with Flitter by default, but you can install it manually on existing Flitter applications:

yarn add flitter-i18n

Edit the Units.flitter.js file to add the LocaleUnit under the "Pre-Routing Custom Units" section.

'Locale'        : require('flitter-i18n/src/LocaleUnit'),

Now, deploy the default locales, configs, and middleware:

./flitter deploy locale

Basic Usage

Defining locales

Locales are defined in .locale.js files under the locale/{locale name} directory. Each locale name subdirectory should should have identical files for resolving translations.

Here's an example of the structure:

• locale
  • en_US
    • common.locale.js
    • dash.locale.js
  • es_MX
    • common.locale.js
    • dash.locale.js
  • default
    • brand.locale.js

The default locale is resolved by ALL locales, so it can be used to define translations that are language agnostic.

The translation containers resolve the phrases from the appropriate locale's sub-directory.

Locale Files

Locale files are similar to normal config files that should export an object that maps some translation key that is common across files to a translation.

Here's an example of a hypothetical auth.locale.js:

en_US/auth.locale.js:

module.exports = exports = {
    // Basic translations can map name -> string
    log_in: 'Log in',
    log_out: 'Log out',

    // You can also define them as objects
    user: { one: 'User' },

    // If you need to customize the plural version
    // flitter-i18n supports automatic pluralization
    account: { one: 'Account', many: 'Accounts' },
}

flitter-i18n uses Pluralize under the hood to automatically pluralize translations when possible, but if you find it's getting one wrong, you can override it manually in the config file.

es_MX/auth.locale.js:

module.exports = exports = {
    log_in: 'Iniciar sesión',
    log_out: 'Cerrar sesión',
    user: { one: 'Usuario' },
    account: { one: 'Cuenta', many: 'Cuentas' },
}

default/auth.locale.js:

module.exports = exports = {
    provider_coreid: 'Starship CoreID',
}

Translation Containers

A translation container is a specialized function that points to a particular locale and resolves the translation keys to the translations. You can manually get a translation container for a particular locale using the locale service:

(flitter) ➤ T = _services.locale.get_T('es_MX')
[Function (anonymous)]
(flitter) ➤ T('auth.log_in')
'Iniciar sesión'
(flitter) ➤ T('auth.provider_coreid')
'Starship CoreID'

Scopes

To make translation more palatable to developers, you can set the scope of a translation container to make it easier to access translations. For example:

(flitter) ➤ T = _services.locale.get_T('en_US:auth')
[Function (anonymous)]
(flitter) ➤ T('log_in')
'Log in'
(flitter) ➤ T('provider_coreid')
'Starship CoreID'

Pluralization

The translation container will automatically pluralize the translation, where possible. You can invoke this by passing a number of items to the container call:

(flitter) ➤ T = _services.locale.get_T('en_US:auth')
[Function (anonymous)]
(flitter) ➤ T('user', true)
'Users'
(flitter) ➤ T('user', 5)
'Users'
(flitter) ➤ T('user', 1)
'User'
(flitter) ➤ T(5, 'user')
'Users'

Request-specific localization

A global translation container is not particularly useful on its own, however. Rather, every request that comes into the system will have a RequestLocalizationHelper injected into it by the i18n:Localize middleware. You can access this instance as req.i18n.

One particular benefit of this is that the locale of the user is stored in the session, so a translation container is automatically created for you when the request is made. For example:

// SomeAuth.controller.js
class SomeAuth extends Controller {
    login_page(req, res, next) {
        return res.page('auth:login', {
            title: req.T('auth:log_in'),
        })
    }
}

Changing the locale

You can change the locale from code by storing it in request.session.i18n.locale. However, flitter-i18n provides a clean mechanism for changing the locale.

If any request is made to the server with a locale parameter in the query string, the value of that string will be set as the locale in the session.

This means that the query string only needs to be set once, then the server will remember the locale from the session:

https://your.app/home?locale=es_MX

Setting scopes

You can also specify scopes for the request-specific translation container using the i18n:Scope middleware. For example:

routing/routers/auth.routes.js:

module.exports = exports = {
    prefix: '/auth',

    middleware: [
        ['i18n:Scope', { scope: 'auth'}],
    ],

    get: {
        '/login': ['controller::SomeAuth.login_page'],
    },
}

Now, the translation container will be automatically scoped:

// SomeAuth.controller.js
class SomeAuth extends Controller {
    login_page(req, res, next) {
        return res.page('auth:login', {
            title: req.T('log_in'),
        })
    }
}