Click here to Skip to main content
13,763,464 members
Click here to Skip to main content
Add your own
alternative version

Stats

18K views
120 downloads
3 bookmarked
Posted 22 Nov 2015
Licenced CPOL

Bobril - III - Localizations and Formatting

, 13 Aug 2017
Rate this:
Please Sign up or sign in to vote.
Explanation of features for localizations and formating by bobril-g11n library

Download sample

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 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.

Following example will use it. To get 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!'); // 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:

  1. Message - "Hello World"
  2. Translation help (third optional parameter of t function) - null =not used in t function
  3. Indicator of parameters inside of message - 0 = no parameter
  4. 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.

Basics

We can simply add placeholders to use variables in our text patterns:

t('My name is {a}!', { a: 'Tomas' }); // My name is 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 });
// you are in 2nd floor

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 });
// here are 2 floors

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' });
// famous woman

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 }); // 1.234 in en
t('{arg, number, custom, format:{0.0000}}', { arg: 1.234 }); // 1.2340 - in en

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) }); // Jan 2, 2000 12:00 AM - in en
t('{a, date, custom, format:{DD MM}}', { a: new Date(2000, 0, 2) }); // 02 01 - in en
t('{a, date, custom, format:{{myformat}} }', 
{ a: new Date(2000, 0, 2), myformat: 'ddd' }); // Sun - in en

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 }); // Tomorrow at 4:27 PM - in en

or as a relative from now:

t('{a, time, relative}', { a: Date.now() - 100000 }); // 2 minutes ago - in en

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

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Tomáš Růt
Team Leader Quadient
Czech Republic Czech Republic
No Biography provided

You may also be interested in...

Comments and Discussions

 
-- There are no messages in this forum --
Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web05-2016 | 2.8.181112.3 | Last Updated 13 Aug 2017
Article Copyright 2015 by Tomáš Růt
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid