Reactive simplifed multi language locale module that works with Angular, React, Vue or any nodejs based front-end app. The module allows you to have different langauges dictionaries, control styles direction according to selected language, sync the user language with browser localStorage, it also allows your components to listen to language change event.
These instructions will guide you to install and integrate the insta-locale module in your app.
install the module through npm
npm install --save insta-localeGo the the main file in your app and initialize the locale service, the main file will be main.ts in Angular for example, or index.jsx or index.tsx in React, its required to initialize the store before any of your components starts. In your main file import the getLocaleService function, if you are in typescript also import the LangaugeModel
import { getLocaleService, LangaugeModel } from 'insta-locale';
use the function to get a new reference to locale service
const localeService = getLocaleService();
define languages array
const languagesList: LangaugeModel[] = [
{
key: 'en',
dir: 'ltr',
dictionary: {
'appTitle': 'My App',
}
},
{
key: 'ar',
dir: 'rtl',
dictionary: {
'appTitle': 'تطبيقي',
}
},
{
key: 'fr',
dir: 'ltr',
dictionary: {
'appTitle': 'mon application',
}
},
];
each language consists of three parameters
| Parameter | Discription |
|---|---|
| key | the language unique id, can by any string of your preference |
| dir | the language direction, can be ltr for left direction based languages or rtl for right direction based languages |
| dictionary | a json object with pairs of key/value the holds all labels of your app localised according to the language. Dictionaries of all langauges should have the same keys with localised values for each langauge |
init the locale service with the following parameters
localeService.init({
languages: languagesList,
defaultLangaugeKey: 'en',
saveToBrowser: true,
productionMode: false
});
the config consists of four parameters
| Parameter | Discription | Required | Default Value |
|---|---|---|---|
| languages | array of all your languages objects | Yes | |
| defaultLangaugeKey | the key of your app default language | Yes | |
| saveToBrowser | if true , language will be synced to browser localStorage |
No | true |
| productionMode | if true , the app will not write any console warnings |
No | false |
The service by default will set the app language to the default language you specified in the config, unless the user has pre-saved language in the browser, it will take the browser saved one. To set the language manually from a component, go to the component where it needs to set the app language, and get instance of the service
import { getLocaleService } from 'insta-locale';
const localeService = getLocaleService();
then use the setLanguage function to set the desired language from your languages list
localeService.setLanguage('en');
if saveToBrowser is set to true, you should find the language saved in browser localStorage
to get the current active language, simple get instance of the service
import { getLocaleService } from 'insta-locale';
const localeService = getLocaleService();
then call the currentLanguage getter
const language = localeService.currentLanguage;
console.log(language);
it returns an object of {key: string, dir: string};
if a component needs to listen to language change, go the component and get instance of the service
import { getLocaleService } from 'insta-locale';
const localeService = getLocaleService();
subscribe to languageChanged observable
localeService.languageChanged.subscribe((lang)=> {
console.log(lang);
})
it emits an object of {key: string, dir: string} whenever language changes
to render the app labels in your template, go to the component that needs to render labels and get instance of the service
import { getLocaleService } from 'insta-locale';
const localeService = getLocaleService();
then get the label value using the i18n function, for example
const myApplicationName = localeService.118n('appTitle');
console.log(myApplicationName);
the argument of the i18n is any key defined in your dictionary, the above example will return these values in each language according the config we set earlier
| Language | Value |
|---|---|
| English (en) | "My App" |
| Arabic (ar) | "تطبيقي" |
| French (fr) | "mon application" |
in case you passed a key that doesn't exists, it will return the key itself, for example
const myText = localeService.118n('appBodyName');
console.log(myText);
it will always return appBodyName, and it wil throw a console warning if the you are not in production mode
alot of times you need to add a dynamic value inside your app labels, to do that simply add your variable name in the label surrounded by curly braces, for example:
const languagesList: LangaugeModel[] = [
{
key: 'en',
dir: 'ltr',
dictionary: {
'appTitle': 'My App',
'welcomeMessage: 'Hi {username}, welcome back'
}
},
here, the module expects a variable named username to be passed dynamically to the string, to pass the value pass it inside the vars object in the i18n function
const welcomeText = localeService.118n('welcomeMessage',{ username: 'Walid'});
console.log(myText);
it will return Hi Walid, welcome back;
in case you didn't pass the { username: 'Walid'} argument to i18n it will return the string without the variables and throw a console warning, for example
const welcomeText = localeService.118n('welcomeMessage');
it will return Hi , welcome back;
You can add as much variables as you want to every label in the dictionary.
To handle multi app direction its prefered to use a module that allows css nesting like SASS or LESS. The locale module set the class of the app body tag to the language direction, so if you are in rtl language, inspect your body tag in browser and it should be <body class='rtl'>, now in your main style sheets add these rules
body {
&.rtl {
direction: rtl;
}
&.ltr {
direction: ltr;
}
}
and you can add any extra rules required for your app.
To add specified styling for a component according to app directiom, go to the component styles .rtl & or .ltr &, rules, for example:
.errorMessage {
color: red;
.ltr &{
border-left: 5px solid red;
}
.rtl &{
border-right: 5px solid red;
}
}
and your app will be running in multi directions styles.
We use SemVer for versioning. For the versions available, see the tags on this repository.
- Walid Abou Ali - Initial work - walid1992d
This project is licensed under the MIT License - see the LICENSE.md file for details