Locale
Locale is a very tiny and super skinny library (less than 1kb) to use as a translation mechanism for any Javascript application.
The concept is very simple, you must handle your JSON file with your keys and translation yourself, that means, you probably want to have a assets
folder with en-us.json
or something like that.
Let's take a look how to set it up and using it.
Install
yarn add @tipy/locale
How to use
This example we're using a react base spa to show how to use it.
In you entry file (index or App) before initialising your components, import init
and your resources
and call init
as in the example below.
import { init } from '@tipy/locale';
import enUS from 'your-assets-folder/en-us.json';
import ptBR from 'your-assets-folder/pt-br.json';
init({ resources: [enUS, ptBR] });
Now let's get to the part where you use it in your components to translate your keys.
Assuming your en-us.json
file has the following structure:
{
"person": {
"name": "Gus"
}
}
import { t } from '@tipy/locale';
const Button = () => (
<button>{t('person.name')}</button>
)
Why use it
You can opt for a more robust library such as i18n, but if your application doesn't require interpolation and thousands of other handlings, then tipy/locale
was made for you.
so, Why use it?
tipy/locale
has only 1 goal, load resources and get the translations from them, exactly! from them!
fallbacks
tipy/locale
automatically fallback to the next resource passed in the array, let's put this in an example.
Assuming you have 2 resources but the key you're looking for is not present in the first locale, tipy/locale
will automatically search for the key in the other locales, from left to right in the array of resources.
import { init, t } from '@tipy/locale';
const enUS = { "person": { "name": "Gus" } };
const ptBR = { "person": { "age": "34" } };
init({ resources: [enUS, ptBR] });
t('person.name'); // Gus
t('person.age'); // 34
In the situation above, tipy/locale
did not find person.age
in the first resource, then it fallback to ptBR
resource.
Same key, different resource
What happens if you have the same key in different resources? the most left in the array will be taken, because if tipy/locale
finds the key in the first resource it will return the value and will not continue the search, because it obviously already found one. let's see this in an example.
import { init, t } from '@tipy/locale';
const enUS = { "person": { "name": "Gus" } };
const ptBR = { "person": { "name": "Ted" } };
init({ resources: [enUS, ptBR] });
t('person.name'); // Gus
t('person.name'); // Gus
Update the resources
In case you are switching the language from en-us
to pt-br
but you already initialised the application, no worries, we have an update
function for you. let's see the example.
import { init, update, t } from '@tipy/locale';
const enUS = { "person": { "name": "Gus" } };
const ptBR = { "person": { "name": "Ted" } };
init({ resources: [enUS, ptBR] });
t('person.name'); // Gus
update({ resources: [ptBR, enUS] });
t('person.name'); // Ted
Using a different separator
If .
isn't something you like to separate your keys, no worries, init
function currently has 2 arguments, resources
and separator
, basically you can pass any string you love to separate the keys. let's see this in an example.
import { init, update, t } from '@tipy/locale';
const enUS = { "person": { "name": "Gus" } };
init({ resources: [enUS], separator: '#' });
t('person#name'); // Gus
update({ resources: [enUS], separator: '+' });
t('person+name'); // Gus
API
Function name | Parameters | Description |
---|---|---|
init |
{ resources: Array of JSON, separator: string } |
it initialise the tipy/locale lib, must be called before using t
|
update |
{ resources: Array of JSON, separator: string } |
it updates the resources and separator in case you need to update later after your application is running |
t |
key: string |
it search for the key passed, in the resources initialised |