i18n wrapper and Koa middleware for Lad
npm:
npm install @ladjs/i18nconst 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();Returns translation for phrase key with the given locale. Optionally pass additional arguments, e.g. format specifier replacements for use in the phrase. For example if you have a phrase of "An error occurred %s" with a key of "ERROR_OCCURRED", and you use it as such i18n.translate('ERROR_OCCURRED', 'en', 'some error message') then it would return 'An error occurred some error message.
Returns the same string as i18n.translate, but wrapped with a new Error object with a property no_translate set to true.
This is an extremely useful method if you are using koa-better-error-handler package in the Lad framework – as it will prevent a double translation from occurring.
This middleware uses custom locale detection (in order of priority):
- Check URL (e.g. if
/deor/de/then it's adelocale - as long asdeis a supported locale) - Use the custom function (if provided by the
detectLocaleparameter) for locale detection - Check the
"locale"cookie value (or whatever thecookieoption is defined as) - Check
Accept-Languageheader
It also exposes the following:
ctx.pathWithoutLocale- thectx.pathwithout the locale in it (this is used by koa-meta)ctx.request- with all ofi18nAPI methods (e.g.ctx.request.t,ctx.request.tn, ...)ctx.locale- set to the value ofctx.request.locale(the current user's locale)ctx.state- with all ofi18nAPI 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/contactif the locale is "en")ctx.state.availableLanguages(Array) - which is useful for adding a dropdown to select from an available languagectx.state.currentLanguage(String) - the current locale's language in native language using country-language'sgetLanguagemethodctx.translate(Function) - a helper function for callingi18n.api.tori18n.tto translate a given phrase by its property key name from thephrasesobject option (same asi18n.translateexcept it throws actx.throwerror using Boom)ctx.translateError(Function) - same asctx.translateexcept it returns an Error object with a propertyno_translateset totrue(similar toi18n.translateError)
If the given locale was not available then it will redirect the user to the detected (or default/fallback) locale.
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.
NOTE: As of v1.2.2 we have added a ignoredRedirectGlobs option you can pass to new I18N({ ... }) which will ignore these paths for locale redirection. This is incredibly useful if you are using authentication providers and the passport library, e.g. you want to set /auth/github/ok as the callback URL for GitHub, but a redirect to /en/auth/github/ok would have occurred, thus causing authentication to fail due to a bad code. In this case, you would set { ignoredRedirectGlobs: [ '/auth/**/*' ] } or simply [ '/auth/google/ok' ]. This package uses multimatch internally which supports an Array, therefore you could negate certain paths if needed. See the documentation for multimatch for more insight.
It also sets the cookie locale for future requests to their detected locale.
This also stores the last_locale (or whatever you configure the property name to be in the config option lastLocaleField) for a user via ctx.state.user.save().
NOTE: As of v3.0.0 we have added a redirectIgnoresNonGetMethods (Boolean) option (defaults to true) which you can pass to new I18N({ ... }) which will ignore non-GET methods on redirection.
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',
cookieOptions: {
// Disable signed cookies in NODE_ENV=test
signed: process.env.NODE_ENV !== 'test'
},
expiryMs: 31556952000, // one year in ms
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,
lastLocaleField: 'last_locale',
ignoredRedirectGlobs: [],
redirectIgnoresNonGetMethods: true,
// <https://github.com/ljharb/qs>
stringify: {
addQueryPrefix: true,
format: 'RFC1738',
arrayFormat: 'indices'
},
redirectTLDS: true,
// function that allows using a custom logic for locale detection (can return promise)
detectLocale: null
});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.
If the path has an extension, then it is not redirected.
However if redirectTLDS option is true (which is true by default as of v4.0.0), then if the path basename ends with a valid TLD, then it is redirected.
We came across this missing feature and added it after our discovery through Forward Email.
| Name | Website |
|---|---|
| Nick Baugh | http://niftylettuce.com/ |
| shadowgate15 | https://github.com/shadowgate15 |