@ladjs/i18n

@ladjs/i18n

i18n wrapper and Koa middleware for Lad

Table of Contents

• Install
• Usage
• API
  • i18n.translate(key, locale)
  • i18n.middleware(ctx, next)
  • i18n.redirect(ctx, next)
• Options
• Contributors
• License

Install

npm:

npm install @ladjs/i18n

yarn:

yarn add @ladjs/i18n

Usage

const I18N = require('@ladjs/i18n');
const phrases = { 'HELLO': 'Hello there!' };
const i18n = new I18N({ phrases });

// ...

app.use(i18n.middleware);
app.use(i18n.redirect);

// ... routes go here ...

app.listen();

API

i18n.translate(key, locale)

Returns translation for phrase key with the given locale.

i18n.middleware(ctx, next)

This middleware uses custom locale detection (in order of priority):

1. Check URL (e.g. if /de or /de/ then it's a de locale - as long as de is a supported locale)
2. Check the "locale" cookie value (or whatever the cookie option is defined as)
3. Check Accept-Language header

It also exposes the following:

• ctx.pathWithoutLocale - the ctx.path without the locale in it (this is used by koa-meta)
• ctx.request - with all of i18n API methods (e.g. ctx.request.t, ctx.request.tn, ...)
• ctx.locale - set to the value of ctx.request.locale (the current user's locale)
• ctx.state - with all of i18n API methods (e.g. ctx.request.t, ctx.request.tn, ...)
• ctx.state.l - a shorthand method that accepts a path and returns a localized path (e.g. ctx.state.l('/contact') will output /en/contact if the locale is "en")
• ctx.state.availableLanguages (Array) - which is useful for adding a dropdown to select from an available language
• ctx.state.currentLanguage (String) - the current locale's language in native language using country-language's getLanguage method.
• ctx.translate (Function) - a helper function for calling i18n.api.t to translate a given phrase by its property key name from the phrases object option (same as i18n.translate except it throws a ctx.throw error using Boom)

If the given locale was not available then it will redirect the user to the detected (or default/fallback) locale.

i18n.redirect(ctx, next)

Inspired by node's language support.

Redirects user with permanent 302 redirect to their detected locale if a valid language was not found for them.

It also sets the cookie locale for future requests to their detected locale.

This also stores the last_locale for a user via ctx.state.user.save().

Options

We use i18n options per https://github.com/mashpie/i18n-node#list-of-all-configuration-options

Default options are as follows and can be overridden:

const i18n = new I18N({
  phrases: {},
  logger: console,
  directory: resolve('locales'),
  locales: ['en', 'es', 'zh'],
  cookie: 'locale',
  indent: '  ',
  defaultLocale: 'en',
  // `process.env.I18N_SYNC_FILES`
  syncFiles: true,
  // `process.env.I18N_AUTO_RELOAD`
  autoReload: false,
  // `process.env.I18N_UPDATE_FILES`
  updateFiles: true,
  api: {
    __: 't',
    __n: 'tn',
    __l: 'tl',
    __h: 'th',
    __mf: 'tmf'
  },
  register: i18n.api
});

If you wish to bind logDebugFn, logWarnFn, and logErrorFn per i18n options:

const i18n = new I18N({
  logDebugFn: console.log,
  logWarnFn: console.log,
  logErrorFn: console.log
});

We recommend to use CabinJS for all your logging needs.

For a list of all available locales see i18n-locales.

Contributors

Name	Website
Nick Baugh	http://niftylettuce.com/

License

MIT © Nick Baugh