Introduction
There are many packages that are out for translation, either dedicated for certain frameworks or for general usage, but honestly, they are all harder than what i see how localization would be, so i created Mongez Localization package, a package that can be used with literally any javascript environment with easy configurations.
Installation
Using npm
npm i @mongez/localization
Using Yarn
yarn add @mongez/localization
Once the installation is done, create a localization-config.ts
file in your project (or .js, typescript is recommended though) so we can set our configurations.
import the file in an early stage of your project, at the start of the
src/index.ts
for example or in your main project file entry.
Let's define our config file.
// localization-config.ts
import {
TranslationsList,
setLocalizationConfigurations,
} from "@mongez/localization";
setLocalizationConfigurations({
/**
* Default locale code
*/
defaultLocaleCode: "ar",
/**
* Fall back locale code
*/
fallback: "en",
});
Here we defined our current default locale code, fallback locale code, let's add some translation keywords.
Defining Translation Keywords
This can be done through multiple way, suit yourself with your favorite one, i personally prefer the grouped translations so i don't miss any keyword, let's have a look.
extend method
The basic and primary way to set translation keywords is by importing extend
method
import { extend } from '@mongez/localization';
// let's add some keywords for English translations
extend('en', {
home: 'Home Page',
welcomeUser: 'Hello User, Welcome Home!',
login: 'Login',
createAccount: 'Create Account'
});
// now let's add same keywords but for Arabic
extend('en', {
home: 'الصفحة الرئيسية',
welcomeUser: 'مرحبا بك!',
login: 'تسجيل الدخلو',
createAccount: 'إنشاء حساب جديد'
});
Easy Peasy, we defined the locale code as first argument, the second one is an object with our keywords, the object keys are the keywords that will be used to get the proper translation text and its value obviously will be the translation text.
trans method
We'll see the other ways of translation in a bit, but let's see our result in action, so we want to start using the translation, we can use trans
method for getting the translation text.
// later in your application html|views for example
import { trans } from '@mongez/localization';
console.log(trans('home')); // as default locale code is `ar` so it will return الصفحة الرئيسية
So we just pass the keyword to the method and the proper translation will be returned for the current locale code.
Grouped Translations
Let's head back again to the translation definition section, another and this is my preferred way to define translations is by using the grouped translation method groupedTranslation
import { extend, groupedTranslation } from '@mongez/localization';
groupedTranslation({
home: {
en: 'Home Page',
ar: 'الصفحة الرئيسية'
},
welcomeUser: {
en: 'Hello User, Welcome Home!',
ar: 'مرحبا بك!',
},
login: {
en: 'Login',
ar: 'تسجيل الدخلو',
},
createAccount: {
en: 'Create Account',
ar: 'إنشاء حساب جديد'
}
})
This is more convenient to work with translations as we make sure every keyword is translated to all locale codes so we don't miss any language, however the extend
method is quite useful if we're working with dynamic translations either if we're getting it from backend api or from json files.
Changing current locale code
We can change the current locale code in the runtime by using setCurrentLocaleCode
method, it will update the current locale code.
import { trans, setCurrentLocaleCode } from '@mongez/localization';
// let's log the translation before and after we change the locale code
console.log(trans('home')); // الصفحة الرئيسية
setCurrentLocaleCode('en');
// now let's log it again
console.log(trans('home')); // Home Page
Fallback Translation
Earlier, we defined in the configurations section the fallback locale code, this is useful if the translation key is missing form current locale code, let's it in action
import { trans, groupedTranslation } from '@mongez/localization';
groupedTranslation({
otherUnknownKeyword: {
en: 'Welcome Unknown keyword'
}
});
// Remember the current locale code is `ar` so when we call `trans` method with `otherUnknownKeyword`
// the keyword does not have any translation in `ar`, the fallback locale code will be returned instead
console.log(trans('otherUnknownKeyword')); // Welcome Unknown keyword
Unknown keyword
If the given keyword is not listed in the current or fallback locale code, then the keyword will be returned.
import { trans } from '@mongez/localization';
console.log(trans('missingKeyword')); // will output missingKeyword as the key is missing in all our locale codes
Translate from certain locale code
In some edge cases, we might need to make the translation from certain locale code regardless the current locale code, transFrom
can be handy for this situation.
import { transFrom } from '@mongez/localization';
// current locale code is ar
console.log(transFrom('en', 'home')); // Home Page
We just pass the locale code as first argument, the second argument receives the translation keyword.
Nested keywords
Another good feature that can be used is to group your translations, this pattern is used in Mongez Validator as we can group the translation keywords under one keyword.
import { extend, groupedTranslation } from '@mongez/localization';
// using extend
extend('en', {
validation: {
required: 'This field is required',
email: 'Invalid Email Address',
}
});
// using groupedTranslation
groupedTranslation('validator', {
required: {
en: 'This field is required',
},
email: {
en: 'Invalid Email Address',
}
});
The keyword now can be stored as validator.required
and validator.email
directly in trans method.
import { trans } from '@mongez/localization';
console.log(trans('validator.required')); // This field is required
Dynamic translation
That was great with static keywords, but what if we want to have a translation that can have a dynamic content for example Create new %s
where %s can be changed so we don't have to create dozens of translations, let's see it in action.
import { trans, extend } from '@mongez/localization';
extend('en', {
createItem: 'Create new %s',
});
console.log(trans('createItem', 'User')); // Create New User
console.log(trans('createItem', 'Order')); // Create New Order
console.log(trans('createItem', 'Category')); // Create New Category
console.log(trans('createItem', 'Product')); // Create New Product
That would be much better than creating 4 translations keywords, or even worse if the application has dozens of modules to be created, updated or deleted.
This is done under the hood using Sprintf-js.
Probably your most used placeholders are %s
for strings like User
and %d
for digits like any number.
import { trans, extend } from '@mongez/localization';
extend('en', {
orderTotal: 'Total Order: %d',
});
console.log(trans('orderTotal', 125.25)); // Total Order: 125.25
extend('en', {
userOrderTotal: 'Total Order for %s is %d USD',
});
console.log(trans('userOrderTotal', 'Hasan', 125.25)); // Total Order for Hasan is 125.25 USD
Don't forget order matters here
Conclusion
For more detailed documentation about the package, feel free to visit the Github repository.
There are more features that i didn't cover in this article that can be found in the repository docs like events
updating fallbacks
and so on.
I'll start working on version 2.0
where the placeholders will be enhanced, and also to support JSX for placeholders as well.
I hope you enjoy the package and any feedback is appreciated.
Enjoy and happy coding.
Top comments (0)