@sap/textbundle

@sap/textbundle
==========

Simple tool for text internationalization in Node.js. Based on the same concept as SAP UI5, this module works with UTF-8 encoded properties files.
Language defaulting is also borrowed from SAP UI5 with the idea the UI and server-side code
use the same text internationalization approach.

API documentation

Usage

Assuming you have these files in directory ./test/properties:

i18n_en_EN.properties
``
greeting = Hello {0}, you are {1} years old.
`

i18n_de.properties
`
greeting = Hallo {0}, Sie sind {1} Jahre alt.
`

Single quote inconsistency


When there is a single quote in a resource, then several cases must be kept in mind:
- whether there is one or more placeholders in the resources
- whether the textbundle user is passing an array for the placeholders to getText

The result is summarized in the following table, where N/A means that no parameters were provided (not even an empty array of parameters):

| Resource (example) | Parameters | getText() result | Counter intuitive |
|--------------------|---------------------|-------------------------|:-----------------:|
| It's me | N/A | It's me | |
| It's me | [] | Its me | :x: |
| It's {0} | N/A | It's {0} | |
| It's {0} | [] or ['Bryan'] | Its {0} | :x: :x: |
| It''s really {0} | N/A | It''s really {0} | :x: |
| It''s really {0} | [] | It's really undefined | |
| It''s really {0} | ['Bryan'] | It's really Bryan | |

$3


#### Old API
`js
var TextBundle = require('@sap/textbundle').TextBundle;

var bundle = new TextBundle({path: 'test/properties/i18n', locale: 'en_EN' } );
`

#### New API
`js
var TextBundle = require('@sap/textbundle').TextBundle;

var bundle = new TextBundle('test/properties/i18n', 'en_EN');
`

#### Constructing localized messages
`js
var TextBundle = require('@sap/textbundle').TextBundle;

var bundle = new TextBundle(path.resolve(__dirname, 'test/properties/i18n'), 'en_EN');

bundle.getText('greeting'); // will return 'Hello {0}, you are {1} years old.'
bundle.getText('greeting', ['Stefan']); // will return 'Hello Stefan, you are undefined years old.'
bundle.getText('greeting', ['Stefan', '21']); // will return 'Hello Stefan, you are 21 years old.'

// using DE locale
var bundle = new TextBundle(path.resolve(__dirname, 'test/properties/i18n'), 'de');
bundle.getText('greeting', ['Stefan', '21']); // will return 'Hallo Stefan, Sie sind 21 Jahre alt.'
`

$3

Bundles can be loaded by providing the absolute path to the resource bundle or relative path. If relative a path is used it will be resolved with respect to your JavaScript file. Absolute path to the resource bundle should be favored for TextBundles.

Default file extension is .properties. If your file has a different extension, you just need to append it to the path you provide.
The format of the file still has to be UTF-8, and the structure has to be properties-like.

`js
var TextBundle = require('@sap/textbundle');
var txtBundle = new TextBundle({path: './test/txt/i18n.txt'});
`

$3

Getting text is straight forward - shown on the examples above already.

Message retrieval from properties files is done using fall-back mechanism that searches for the provided key
in a hierarchical order and returns the text associated with this key from the first occurrence in some of the files.

Following order is applied when text is retrieved for specific locale:

`
language -> country -> en -> root -> 'not-found, return the key'
`


A simple example: locale is 'de_DE', bundle name is 'i18n', the order in which properties files are checked for key existence is following:

`
i18n_de_DE
i18n_de
i18n_en
i18n
// if not found, the key is returned back
`

$3


The static function TextBundle.fallbackLocale returns the fallback of a given locale (e.g. 'fr_FR' => 'fr' => 'en' => '').
This lets you set up a locale fallback chain for your own purpose.

`js
var TextBundle = require('@sap/textbundle').TextBundle;

var parent = TextBundle.fallbackLocale('en_US');
`

$3

ResourceManager class allows managing resources for your module by caching the various TextBundle in order to avoid repeatedly loading them.

`js
var ResourceManager = require('@sap/textbundle').ResourceManager;
var rm = new ResourceManager(path.resolve(__dirname, 'test/properties/i18n'));

var bundle = rm.getTextBundle('en_EN');
bundle.getText('greeting');
`

$3

In order to improve server scalability, resources should be loaded through asynchronous file system operations.

`js
var ResourceManager = require('@sap/textbundle').ResourceManager;
var rm = new ResourceManager(path.resolve(__dirname, 'test/properties/i18n'));

rm.loadTextBundle('en_EN')
.then(function (bundle) {
bundle.getText('greeting');
});
`

$3

`js
var ResourceManager = require('@sap/textbundle').ResourceManager;
var rm = new ResourceManager(path.resolve(__dirname, 'test/properties/i18n'));
var express = require('express');

var app = express();

function requestLocale(req) {
var locale = req.locale = req.acceptsLanguages(['en-US', 'en', 'de-DE', 'de', 'fr-FR', 'fr']) || 'en';
return locale;
}

app.use('/', rm.getMiddleware(requestLocale));

app.use('/myHandler', function (req, res, next) {
// resources for request locale have been loaded at this stage
var bundle = rm.getTextBundle(req.locale);
bundle.getText('greeting');
});
``