Manage preferences and internationalization for multiple locales very easily in Javascript
Usage no npm install needed!
<script type="module">
import prefjs from 'https://cdn.skypack.dev/prefjs';
</script>
README
prefjs
This package is meant for internationalization. It helps you define a JSON structure for different locales, and getting the right value back. For example, it could be used for the internationalization of a blog post.
PrefJS can be used in NodeJS and in the browser, being compatible with all the frameworks, like: React, Angular, Vue, Ember, Next.js...
Dependencies
This package depends on printj. Please install it also :)
gt; npm install printj --save
Installing the package
gt; npm install prefjs --save
If you are using Typescript, you will see the types information that comes bundled with this package when you are coding :). Enjoy!
NOTE: This package weights only 2KB, and even less when gzipped
As you see, we have a blog post for english and spanish with the post title. Also, for english which is the default language we have a nested configuration to show an image.
Now, let's create a new object with the default locale set to en, and the current locale set to es assuming we are seeing that blog post in spanish.
const pref = new PrefJS({ defaultLocale: 'en', currentLocale: 'es' });
After this we are going to set the data that we will be querying with PrefJS for the blog post
pref.setGlobalData(blogPost);
Now, in order to get the title for the current locale (es), we would do:
const title = pref.get('title'); // Mi título
PrefJS is smart enough to know that it should bring the post title for the current locale you are in. But what happens when we try to access a property that does not exist in spanish? PrefJS will return the value from the default locale. Example:
And, what if the property does not exist in the current locale, nor in the default one? PrefJS can return a fallback value. Let's look at an example with the postURL, which is not set in any of the locales. Example:
The previous code snippet will first search in the currentLocale if postURL existed, or will try to find it in the defaultLocale, and as it does not exist, it will return the fallbackValue provided.
The library also provides support for a language fallback to another. In the example, both es and es_CO were configured.
Explanation:
es_CO will fallback to es if you try to do pref.get('description'). Please note that description is not set in es_CO.
es must be configured for es_CO to fall back to it. If it is not, it will default to defaultLocale
String formatting
Starting v1.0.0 you can use string formatting. For this we use the package printj (https://github.com/SheetJS/printj) so all its documentation applies.
For this feature, we created the function getF. Here is an example:
// Language data to use
const languageData = {
en: {
formattedString: 'This %s is formatted. Use it %s you need it'
}
}
// Create the instance
const pref = new PrefJS({ defaultLocale: 'en', currentLocale: 'en' });
// Get a formatted string
const s = pref.getF('formattedString', 'Fallback', 'string', 'whenever, and however');
// s = This string is formatted. Use it whenever, and however you need it
As you can see, the second parameter is "Fallback". This is a fallback string that can be used in the case in which the first argument given is not a value in the languageData you defined. This string is also formattable so you can expect the subsequent parameters to work fine. Example:
const s = pref.getF('i.dont.exist', 'Use this %s %s', 'string', 'as a fallback');
// s = Use this string as a fallback
Note: it also works with digits and it's possible to do other kinds of string manipulation. Please refer to the printj documentation for more.
Working with translations set in object keys
In this use case, you would have for example an object with the following format:
You may combine different keys in the same object:
const object2 = {
description: 'I am a product',
description_es: 'Yo soy un producto',
title: 'T-shirt - XL',
title_es: 'Camiseta - XL'
};
pref.getFromObject(object2, 'title'); // T-shirt - XL
pref.getFromObject(object2, 'description'); // I am a product
// And in spanish
pref.setCurrentLocale('es'); // change to spanish
pref.getFromObject(object2, 'title'); // Camiseta - XL
pref.getFromObject(object2, 'description'); // Yo soy un producto
// Get data in other locale although pref main
// locale is currently set to 'es'
pref.getFromObject(object2, 'description', { customLocale: 'en' }); // I am a product
If the value in a specific locale is not found, you will get the default language value. Example:
const object3 = {
description: 'I am a product',
title: 'T-shirt - XL',
title_es: 'Camiseta - XL'
};
pref.setCurrentLocale('es'); // change to spanish
pref.getFromObject(object, 'title'); // Camiseta - XL
pref.getFromObject(object, 'description'); // I am a product
As you can see, in this case the description_es key was not found in the object, so the value under the description key was returned.
IMPORTANT: You can use much more than just strings. In fact, any value from javascript is valid, including Dates, numbers, boolean values, objects... give it a try!
LICENSE
MIT.
Credits
Juan Camilo Guarín Peñaranda
Otherwise
Jamundí, Colombia
2021