@maeum/i18n-controller

i18n controller

The @maeum/i18n-controller is a package that helps developer to integreate node-polyglot. Developer can generate a i18n resource via json format file and then use as a singletone class in application(eg. fastify.js or express.js).

Why use @maeum/i18n-controller?

• Support i18n feature in your application with less work
• Front-end messages can be managed on server
  • For example, server redeployment allows message changes without front-end or iOS, Android app deployment
• Manage messages as resource file to separate them from source code
  • Separated resource file it can be used in non-HTTP request/response code as well

Table of Contents

• Getting Started
  • installation
  • Configuration
• How to work?
• Usage
• Option overview
• License

Getting Started

installation

npm install @maeum/i18n-controller --save

Configuration

// `localeRoot` is resource location
// `defaultLanguage` is fallback language
await I18nContainer.bootstrap({ localeRoot: './resource', defaultLanguge: 'en' }, true);

if (somethingError) {
  throw new Error(I18nContainer.it.t('en', 'common.error', { id: 'your pet id' }));
}

How to work?

The @maeum/i18n-controller implements i18n support using node-polyglot. You can use directories to create polyglot objects in multiple languages, and polyglot objects to manage and consume i18n messages.

flowchart LR
A01[<ul><li>resources</li><ul><li>en-gb<ul><li>common.json</li><li>pet.json</li></ul></li><li>en-us<ul><li>common.json</li><li>pet.json</li></ul></li><li>ko<ul><li>common.json</li><li>pet.json</li></ul></li></ul></ul>]
B01[<ul><li>Polyglot:en-gb</li><li>Polyglot:en-us</li><li>Polyglot:ko</li></ul>]
C01["Polyglot:en-gb.t('common.error')"]
C02["Polyglot:en-gb.t('pet.name.require')"]

A01-->B01
B01-->C01
B01-->C02

Each resource files, like common.json, use jsonc-parser to read in content, so you can add comments to the resource file.

{
  // korean common error message
  // you can add comments in resource file
  "error": "An error occurred, please try again later"
}

Usage

// synchronous bootstrap
I18nContainer.bootstrap({ localeRoot: './resources' }, false);

// asynchronous bootstrap
await I18nContainer.bootstrap({ localeRoot: './resources' }, true);

// custom polyglot function
// @see https://github.com/airbnb/polyglot.js#options-overview
await I18nContainer.bootstrap({ localeRoot: './resources', polyglot: { ...your custom option } }, true);

// translate function
I18nContainer.it.t('common.error', { id: 'petId' });

Option overview

Detail option can check here.

name	type	required	description
localeRoot	string	required	Specify the location of the resource file
defaultLanguage	string		Specify the default language. If no language is found when using t function (translate function), the default language translation function is used
polyglot.allowMissing	boolean		a boolean to control whether missing keys in a t call are allowed. If false, by default, a missing key is returned and a warning is issued
polyglot.interpolation	object		an object to change the substitution syntax for interpolation by setting the prefix and suffix fields
polyglot.onMissingKey	function		if allowMissing is true, and this option is a function, then it will be called instead of the default functionality. Arguments passed to it are key, options, and locale. The return of this function will be used as a translation fallback when polyglot.t('missing.key') is called (hint: return the key)
pluralRules	object		an object of pluralTypes and pluralTypeToLanguages to control pluralization logic

License

This software is licensed under the MIT.