Introduction
In this article, we will learn how to localize our application or format a text with culture specifics. The library bobril-g11n
was created for this purpose.
Background
Bobril globalization library is written by Boris Letocha (software architect and developer in GMC Software Technology).
It is inspired by Format.js and internally uses Moment.js.
Examples
At first, we need to have prepared bobril-build
on computer. Follow the steps in the first article to perform bobril-build
installation.
Now you can start a new project again or use a predefined skeleton simpleApp
from bobril-build github repository.
The following example will use it. To get the final code, download the full sample.
Add bobril-g11n to Application
Type to the command line:
npm i bobril-g11n --save
bb
Now change the app.ts file and change it to look like this:
import * as b from 'bobril';
import { mainPage } from './mainPage';
import { initGlobalization } from 'bobril-g11n';
initGlobalization({ defaultLocale: 'en-US' }).then(() => {
b.routes(
b.route({ handler: mainPage })
);
});
This code will import and call initGlobalization
function. Its argument IG11NConfig
defines the default locale and optionally the function for getting the path to the localized files. Bobril-build
is configured to generate the default localization file en-US.js directly to the root of the dist folder.
The initGlobalization
function returns a Promise
object. Initialization of the application by b.routes
has to be called in a fulfillment callback of this promise.
The next step is to import all necessary functions, for example, by adding the following lines to the mainPage.ts file:
import { t, f, getLocale, setLocale } from 'bobril-g11n';
Now, we have everything prepared for trying out the examples. You can remove the me.children
content in a render
function of the page component in mainPage.ts file and use it for trying out the examples.
Translation
Bobril-globalization
package contains a t
function with these arguments: message for input text/pattern and optional params
object defining the values for the message
pattern.
t('Hello World!');
Bobril-build
takes all usings of t('some string')
in code and replaces it by e.g. t(125)
where 125
is the index of 'some string' constant in the array of localized strings. This array is placed in every localization file and corresponds to the array in the generated en-US.js.
To add a new localization definition, just type the command:
bb t -a cs-CZ
bb b -u 1
bb
This first command creates a new translation file translations/cs-CZ.json. The second command adds the missing translations from the defaultly generated en-US.js to cs-CZ.json translation definition. The build with the b
parameter runs only once and then stops. Finally, the last command runs build of the application with tracking changes in the code and with an output to the local web server. The content of the created json can be, e.g.:
[
"cs-CZ",
[
"My name is {a}!",
null,
1
]
]
To add translations, it can be modified to the following:
[
"cs-CZ",
[
"My name is {a}!",
null,
1,
"Jmenuji se {a}!"
]
]
The specific parts of localization item represented as an array are:
- Message - "
Hello World
" - Translation help (third optional parameter of
t
function) - null
=not used in t
function - Indicator of parameters inside of message -
0
= no parameter - The translated message - "
Ahoj světe
"
Parts 1-3 compose the translation key. You can see the json definition example in the attached sample.
If you change the translation definition file, the bobril-build
(bb
command) has to be stopped and started again or some another change in the code has to be done to rebuild the application.
To see all possible build options, use the -h
parameter for bb
command.
To change the locale, we can use the following code:
setLocale('cs-CZ');
This code will change the locale and render the page with specific translations. To get the current locale, we can use a function getLocale
.
We can simply add placeholders to use variables in our text patterns:
t('My name is {a}!', { a: 'Tomas' });
Ordinal
To set localized ordinal, use the selectordinal
pattern:
t('you are in {floor, selectordinal,
=0{ground} one{#st} two{#nd} few{#rd} other{#th}} floor', { floor: 2 });
The #
character is replaced by the floor
property in the params
object.
Plural
The similiar plural pattern is used to define localized plurals:
t('here {floor, plural, =0{is no floor} =1{is # floor} other{are # floors}}', { floor: 2 });
Select
To select a specific value according to some input string
, we can use the select
pattern:
t('famous {gender, select, female {woman} male {man} other {person}}', { gender: 'female' });
Number
We can use a number
pattern to keep numbers in culture specific formatting or to define our own format:
t('{arg, number}', { arg: 1.234 });
t('{arg, number, custom, format:{0.0000}}', { arg: 1.234 });
Date and Time
The date
and time
patterns work the same way and can be used in the following way:
t('{a, date, lll}', { a: new Date(2000, 0, 2) });
t('{a, date, custom, format:{DD MM}}', { a: new Date(2000, 0, 2) });
t('{a, date, custom, format:{{myformat}} }',
{ a: new Date(2000, 0, 2), myformat: 'ddd' });
The specific format definitions can be found in the Moment.js documentation.
It can also be defined in a calendar format:
t('{a, time, calendar}', { a: Date.now() +
24 * 60 * 60 * 1000 });
or as a relative from now:
t('{a, time, relative}', { a: Date.now() - 100000 });
For more examples, download the full sample.
Just Formatting
If you only want to do the formatting of a text without a translation, just replace the t
function by the f
function. It will only take care of culture specific formatting.
History
- 2017-07-30: Revision (bobril-build@0.71.1, bobril@7.3.2, TS 2.4.2)
- 2017-02-01: Revision (bobril-build@0.59.2, bobril@5.2.1)
- 2016-11-04: Revision
- 2016-08-03: Updated to bobril-build@0.45.0
- 2015-12-16: Updated to bobril-build@0.10.0 with translation in interactive mode
- 2015-12-16: Changed to simpleApp based on bobril-build
- 2015-12-08: Updated for new bobril-g11n rules in v0.7.1
- 2015-11-21: Article created