Locale for Javascript
Features
- Multiple target languages (translate to)
- Any base language (translate from)
- Plural forms for any language
- Simultaneous support of multiple languages
- Flexible placeholders
- Deferred translation
It's simple
// Translatevar who = 'world';; // Translate plural;
Installation
Install node.js library:
npm install locale-js
or download minified library i18n.min.js (for browser apps).
Tools
See locale-tools project.
API
- Library import
- Configuration
- Creating i18n object
- Translation target
- Translation
- Strings format
- Deferred translation
Library import
For node.js:
var locale = ;
For browser:
Configuration
Library initialization (browser):
locale
, where:
- base (string) - id of application's base language;
- rule (string) - plural rule for base language.
You should use locale.add() to add translation for each used language.
Library initialization (node.js):
locale
, where path is the path to the translation files.
This function searches for and loads all translations automatically.
Example:
// In browser:locale;// You can skip parameters if your base language is Englishlocale;// In node.js app:locale;
Add translation:
locale
, where:
- lang (string) - language id;
- translation (object) - translation JSON.
Creating i18n object
Create translation object for the given target:
target
, where target (string or null) - 1) id of the target language, 2) empty string or 3) null.
Sets target language to base language if target is '' (empty string).
Enables deferred translation mode if target is null.
Example:
// Create translation object for Russian languagevar i18n = 'ru';// Create translation object for base language (no translation)var i18n = '';// Create translation object for deferred translationvar i18n = null;// And pull up __() function to the local scopevar __ = i18n__;
Translation target
This methods are accessible for locale and i18n objects.
Get current target:
Returns (string or null) current translation target.
Set target:
, where target (string or null) - 1) id of target language, 2) empty string or 3) null.
Sets target language to base language if target is '' (empty string).
Switches i18n object to deferred translation mode if target is null.
Example:
// Set target language for library to Germanlocale;// Create i18n object and set its target language to Russianvar i18n = ;i18n;// Enable deferred translation modei18n;
Translation
This methods are accessible for locale and i18n objects.
For simple form:
, where:
- phrase (string) - string for translation (can contains placeholders);
- ... (mixed) - any number of additional args;
- array (Array) - array of args;
- object (object) - map of args.
Returns translated string or deferred translation data (in case of deferred translation target).
For plural form:
, where:
- phrase (array) - array of strings each of them is a plural form for translation (can contains placeholders);
- n (numeric) - base number of plural form;
- ... (mixed) - any number of additional args;
- array (Array) - array of args;
- object (object) - map of args.
Returns translated string or deferred translation data (in case of deferred translation target).
Example:
// Simple: // Hello!;// Hello, anonymous!;// Hello, John Smith!;// Hello, Foo (bar)!; // Plural: // Inbox: 1 unreaded message.;// Inbox: 7 unreaded messages.;// Anonymous, you have 365 unreaded messages in the "Spam" folder.;// The second way; // Deferred: // { __i18n: true, phrase: 'Hello!', n: undefined, args: {} };
See also: Deferred translation.
Strings format
Phrase, id and comment
Each string consists of phrase, id and comment. Both id and comment are optional, id separates from phrase by '#' sign, comment separates from id by space.
<phrase>[#[<id>][ <comment>]]
phrase + id is unique key for translation dictionary. You can create several variants of translation of the same phrase using different ids.
Also you can place any useful info for translator to comment.
Example:
// No id, no comment;// Both id and comment;// Only id;// Only comment;
Placeholders
Phrase can contains placeholders.
Placeholder's format is:
%[(<name>)][<flag>][<width>][.<precision>]<type>
, where:
- <name> - argument name or number;
- <flag> - one or more special flags;
- <width> - field width;
- <precision> - precision for numeric or max string length for string;
- <type> - conversion specifier.
The name
Argument number for additional arguments and array arguments, argument name for map arguments.
The flag characters
- '-' - The converted value is to be left adjusted on the field boundary (the default is right).
- ' ' - A space should be left before a positive number or empty string.
- '+' - A plus sign should always be placed before a non-negative number. Overrides a space if both are used.
The field width
An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces (on the left by default or on the rigth if '-' flag has been given).
The precision
An optional precision, in the form of a period ('.') followed by an optional decimal digit string. This gives the number of digits to appear after the radix character for numeric conversions or the maximum number of characters for string conversions.
The conversion specifier
A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are:
- s - string;
- d - decimal number;
- e - decimal number in scientific notation;
- b - binary number with 'b' suffix;
- h - hex number with 'h' suffix and lowercased 'a-f' digits;
- x - hex number with '0x' prefix and lowercased 'a-f' digits;
- X - hex number with '0x' prefix and uppercased 'A-F' digits;
- n - same as 'd' but with value from n parameter;
- % - A '%' is written. No argument is converted. The complete conversion specification is '%%'.
Example:
; // ' +13.00'; // 'Hello, wor !'; // 'value is 1101b (Dh)'
See also: Translation example.
Special characters
Special characters are '#' and '%'. If you need it in your string you should type it twice.
// 40%;// It's # not a comment!
Deferred translation
Search for deferred translation data in the obj and replace it by translated string:
i18n
, where obj (object) - object for translation.
Deferred translation data structure:
{
__i18n: true,
phrase: <phrase>,
n: <number>,
args: <arguments>
}
See also: Creating i18n object.
Example:
// Server: // Create i18n object for the deferred modevar i18n = null;var __ = i18n__;; // Client: var i18n = 'ru';var msg = ;i18n;/* { id: 832367, errno: 404, error: 'Путь не найден!' } */