* [Architecture](#architecture)
* [Autonomous Message Loading](#autonomous-message-loading)
* [Language Config Customization](#language-config-customization)
* [Runtime Language Switching](#runtime-language-switching)
* [Pseudo Localization Support](#pseudo-localization-support)
* [Deep String Resource Extraction](#deep-string-resource-extraction)
* [HTML Template Globalization](#html-template-globalization)
* [JSON YAML File Globalization](#json-yaml-file-globalization)
* [Persistent Logging](#persistent-logging)
* [Demo](#demo)
* [Sample Code](#sample-code)
* [Other Resources](#other-resources)
* [CLI - extract, lint, and translate](#cli---extract-lint-and-translate)
* [API - Set system defaults](#api---set-system-defaults)
* [SG.SetDefaultLanguage](#sgsetdefaultlanguagelang)
* [SG.SetRootDir](#sgsetrootdirrootpath)
* [SG.SetHtmlRegex](#sgsethtmlregexregex-regexhead-regextail)
* [SG.SetPersistentLogging](#sgsetpersistentlogginglogcallback-disableconsole)
* [g.setLanguage](#gsetlanguagelang)
* [g.getLanguage](#ggetlanguage)
* [API - Formatters](#api---formatters)
* [g.formatMessage](#gformatmessagepath-variables)
* [g.t](#gtpath-variables)
* [g.m](#gmpath-variables)
* [g.formatCurrency](#gformatcurrencyvalue-currencysymbol-options)
* [g.c](#gcvalue-currencysymbol-options)
* [g.formatDate](#gformatdatevalue-options)
* [g.d](#gdvalue-options)
* [g.formatNumber](#gformatnumbervalue-options)
* [g.n](#gnvalue-options)
* [API - Wrappers](#api---wrappers)
* [g.Error](#gerrorpath-capital-error)
* [g.format](#gformatpath-)
* [g.f](#gfpath-)
* [g.ewrite](#gewritepath-)
* [g.owrite](#gowritepath-)
* [g.write](#gwritepath-)
* [API - RFC 5424 Syslog Message Severities](#wrappers-for-rfc-5424-syslog-message-severities)
* [g.emergency](#gemergencypath-)
* [g.alert](#galertpath-)
* [g.critical](#gcriticalpath-)
* [g.error](#gerrorpath-small-error)
* [g.warning](#gwarningpath-)
* [g.notice](#gnoticepath-)
* [g.informational](#ginformationalpath-)
* [g.debug](#gdebugpath-)
* [API - Node.js Console](#wrappers-for-nodejs-console)
* [g.warn](#ghelppath-)
* [g.info](#gdebugpath-)
* [g.log](#gdatapath-)
* [API - Misc Logging Levels](#wrappers-for-misc-logging-levels)
* [g.help](#ghelppath-)
* [g.debug](#gdebugpath-)
* [g.data](#gdatapath-)
* [g.prompt](#gpromptpath-)
* [g.verbose](#gverbosepath-)
* [g.input](#ginputpath-)
* [g.silly](#gsillypath-)
* [Usage Examples](#usage-examples)
* [use g.f for util.format](#use-gf-for-utilformat)
* [use g.write for process.stdout.write](#use-gwrite-for-processstdoutwrite)
* [place holders](#place-holders)
* [double curly braces not to translate](#double-curly-braces-not-to-translate)
* [help txt files](#help-txt-files)
* [help txt files and msg keys](#help-txt-files-and-msg-keys)
* [manually add message strings](#manually-add-message-strings)
# Architecture
`strong-globalize` is built on top of two foundation layers: Unicode CLDR and jquery/globalize. The Unicode CLDR provides key building blocks for software to support the world's languages, with the largest and most extensive standard repository of locale data available. jquery/globalize is a JavaScript library for internationalization and localization that leverages the Unicode CLDR JSON data. The library works both for the browser and as a Node.js module.
`strong-globalize` is a JavaScript library for internationalization and localization (globalization in one word) of a Node.js package. `strong-globalize` provides these features:
- [shorthands and wrappers](#api---formatters) for the format functions supported by Node.js console, jquery/globalize, and util.format,
- [automatic extraction](#cli---extract-lint-and-translate) of the strings from JS code and [HTML templates](#globalize-html-templates) and auto-creation of resource JSON,
- [machine translation](#cli---extract-lint-and-translate) of the resource JSON using [IBM Globalization Pipeline on Bluemix](#liblocal-credentialsjson),
- in [Node.js runtime](#api---set-system-defaults), loads not only the CLDR data sets but the localized string resources of your module as well as all the statically and dynamically dependent modules.
- [function hook for logging](#persistent-logging) localized user messages so that the client can log what is shown to the end user along with the original English message.
As shown in the [Demo section](#demo), the code written with `strong-globalize` is simpler, better structured, and easier to read than the original code written as an English-only product; and more importantly, you get all the features at no extra effort.
With `strong-globalize`, there will be no more 'English product first and worry about localization later'; there will be only one globalized codebase from day one. If you choose, you can still ship it with a few language resources (or English only) initially and incrementally add, remove, or update the resources and ship anytime as you go.
- node.js versions: 0.10, 0.12, 4, 5, 6
- cldr version: 29.0.1
- out-of-box languages - 31: de, en, es, fr, it, ja, ko, pt, ru, zh-Hans, zh-Hant',
ar', 'bn', 'cs', 'el', 'fi', 'hi', 'id', 'lt', 'nb', 'nl', 'pl', 'ro', 'sl', 'sv',
'ta', 'te', 'th', 'tr', 'uk', 'vi'
You can customize (add/remove) any languages supported by the Unicode CLDR in your `strong-globalize` installation.
## About Test
The line test coverage with and without core part of translation tests are currently `90%` and `80%` respectively.
With the out-of-box setting, `npm test` runs all tests but the core translation tests because it requires connection to the machine translation service. To enable the machine translation, please set the environment variables described in [this section](#liblocal-credentialsjson).
With custom setting such as customized language configuration, some tests may fail. You can edit target messages in the failing test modules to suit your custom setting. To do so, set DEBUG global variable of test/slt-test-helper.js and run the test, identify the actual error messages, then copy and paste the actual error messages to the failing test modules.
# Autonomous Message Loading
All packages are created equal. `Autonomous Message Loading` is the core concept of `strong-globalize` designed for globalization of modular and highly distributed Nodejs applications. Two key terminologies are `root directory` and `master root directory`:
`root directory` or simply `rootDir`: the package's current working directory where `intl` directory resides.
`master root directory`: the root directory of the package that called `SG.SetRootDir` first. Any package in the application can be the `master root directory`. It's determined solely by the loading order and once the master is chosen, it does not change in the application's life. Usually, the `master root directory` is the `root directory` of the package at the root of the application's dependency tree. `slt-globalize -d` must run under the `master root directory` so that all the string resources in the application are extracted and stored under the `master root directory's intl/en`.
Once all the string resource files are [deep-extracted](#deep-string-resource-extraction) and translated at the top level package, the original string resources in the dependencies should not be loaded. To disable loading the string resources in the dependencies, set `autonomousMsgLoading` to `none` in the `SetRootDir` call of the top level package. Since 'none' is the default, simply `SG.SetRootDir(rootDir)` does it.
In development phase, with regular extraction mode, `{autonomousMsgLoading: 'all'}` must be set so that string resource included in each dependent package will be used.
Third option is to set specific package names of which the string resources get loaded. One use case of the third option is that you have several dependent packages which you know are properly translated and the translation can be used as-is. For all the other packages, message strings will be deep-extracted and translated.
```js
var SG = require('strong-globalize');
SG.SetRootDir(__dirname, {autonomousMsgLoading: 'none'}); // same as SG.SetRootDir(__dirname);
var g = SG({language: 'en'}); // same as SG();
// use formatters and wrappers API
g.log('Welcome!');
```
For example, the following does not work as intended because the package sub calls `SG.SetRootDir` first:
```js
// main/index.js -- my root package
var SG = require('strong-globalize');
var request = require('request');
var sub = require('sub');
SG.SetRootDir(__dirname);
var g = SG();
...
```
```js
// sub/index.js -- my sub package
var SG = require('strong-globalize');
var request = require('request');
SG.SetRootDir(__dirname);
var g = SG();
...
```
The 'MUST' coding practice is to call `SG.SetRootDir` in the very first line of the main module in each package:
```js
// main/index.js -- my root package
var SG = require('strong-globalize');
SG.SetRootDir(__dirname);
var request = require('request');
var sub = require('sub');
var g = SG();
...
```
```js
// sub/index.js -- my sub package
var SG = require('strong-globalize');
SG.SetRootDir(__dirname);
var request = require('request');
var g = SG();
...
```
More concise coding is as follows:
```js
// main/index.js -- my root package
var g = require('strong-globalize')(__dirname);
var request = require('request');
var sub = require('sub');
...
```
```js
// sub/index.js -- my sub package
var g = require('strong-globalize')();
var request = require('request');
...
```
# Language Config Customization
Out of box, one CLDR file is included in `strong-globalize/cldr` directory. CLDR stands for Common Locale Data Repository. In the installation of `strong-globalize` for your production deployment, you can replace the out-of-box CLDR file entirely, or add extra CLDR data to the `cldr` directory. There are approximately 450 locales (language/culture variations) defined in the Unicode CLDR. Among them, there are 40+ variations of French and 100+ variations of English.
`strong-globalize` provides a utility tool under util directory. The tool assembles only the languages you need to support in your `strong-globalize` installation. For example, the out-of-box gz file for the 11 languages is 135KB. See README of the utility under util directory.
In runtime, `strong-globalize` dynamically loads to memory just the CLDR data required for the specific language by `setLanguage()`. First, it examines all the `gz` files under cldr directory in alphabetical order, then searches for the language. If the language is defined in two or more CLDR files, duplicate objects will be overwritten in the examination order.
## Message String Resource
English string resource files must exist under `intl/en` directory. Translated string resource files are stored on each language sub-directory under `intl` If a message is not found in the translated resource files, the corresponding English message is displayed.
CLDR data has no dependencies on string resources. For example, you can load 100 language CLDR data and no translated string resources but the English string resource. However, if there is a translated non-English string resource exists for language xx under `intl/xx` the CLDR data for `xx` must be loaded. `xx` is one of the languages defined in the CLDR file(s).
# Runtime Language Switching
There are two primary types of Node.js packages `strong-globalize` is targeting:
- Command line interface utility (short life; static language setting) such as [`slt-globalize` itself](#cli---extract-lint-and-translate),
- Web applications such as LoopBack apps (long life; dynamic language switching to respect browser language set in HTTP `Accept-Language` header. See `negotiator' on npmjs.com).
## Common part
```js
var SG = require('strong-globalize');
SG.SetRootDir(__dirname);
var g = SG(); // use the default
```
## Static language setting in CLI utility
```js
// the common part comes here.
// then, use formatters and wrappers API always in the same language
g.log('Welcome!');
```
## Dynamic language switching in Web application
Setting language to `strong-globalize` instance is pretty cheap. CLDR data set and translated messages are preloaded at the initial use.
```js
// the common part comes here.
// set language first, then, use formatters and wrappers API
// See 'negotiator' on Npmjs.com for 'getAcceptLanguage()'
g.setLanguage(getAcceptLanguage()); // once per session
g.log('Welcome!');
```
# Pseudo Localization Support
`strong-globalize` has a feature similar to traditional `pseudo localization.`
First, Machine Translation with `slt-globalize -t` can be used like the traditional `pseudo localization.` See [the CLI - extract, lint, and translate section](#cli---extract-lint-and-translate) for details of `slt-globalize -t` command.
Second, in runtime, set the environment variable `STRONG_GLOBALIZE_PSEUDO_LOC_PREAMBLE` and `strong-globalize` adds the string in front of every message processed by the message formatter. If you already have translated message files (by machine or human) and set the language, the string is added to every message in that language.
Third, `strong-globalize` reserves the language code `zz` as pseudo-language. `slt-globalize -e` generates `intl/zz/messages.json` and `intl/zz/messages_inverted.json` which show the location of each message extracted from JS files.
Note that `strong-globalize` does not use `intl/zz/*.json` in runtime. They are reference only. They are useful to detect globalization bugs usually called `hard-coded` strings. For example, intl/en/messages.json shows "Shipping cost is {0}." string is properly globalized and extracted to intl/en/messages.json with the auto-generated message key as "77decb50aa6360f0dc9c8ded9086b94e". intl/zz/messages.json shows the string is located at line#31 of `index.js` as the argument of function call `g.log`. intl/zz/messages_inverted.json shows that at the line#20 of `index.js` there is a string "%s Hello %s" as the first argument of `util.format` which looks like a globalization bug.
Also note that `slt-globalize -e` extracts the first argument of every function call if it's a literal string or concatenation of literal strings. Literal strings in other arguments of function calls are NOT extracted.
`intl/en/messages.json`:
```
{
"77decb50aa6360f0dc9c8ded9086b94e": "Shipping cost is {0}.",
"b5d4af08bf61e58d375923977290d67b": "Listening on {0} by {1}."
}
```
`intl/zz/messages.json`:
```
{
"77decb50aa6360f0dc9c8ded9086b94e": [
"g.log:index.js:31"
],
"b5d4af08bf61e58d375923977290d67b": [
"g.log:index.js:29"
],
"%s Hello %s": [
"util.format:index.js:20"
],
"http://localhost:": [
"request:index.js:35"
]
}
```
and, `intl/zz/messages_inverted.json`:
```
{
"index.js": {
"20": [
"util.format('%s Hello %s', ... )"
],
"29": [
"g.log('b5d4af08bf61e58d375923977290d67b')"
],
"31": [
"g.log('77decb50aa6360f0dc9c8ded9086b94e')"
],
"35": [
"request('http://localhost:')"
]
}
}
```
# Deep String Resource Extraction
`strong-globalize` CLI supports string resource auto-extraction in two modes: `regular extraction` mode and `deep extraction` mode. The regular extraction mode is invoked with `slt-globalize -e` and typically used in package development phase. The deep extraction mode `slt-globalzie -d` is designed to be used in globalization of enterprise-scale applications.
## Regular Extraction
Suppose you have a package named `gmain` which has two JS files: `index.js` and `lib/util.js` and the two JS files contain the same `g.log('user: %s', userName)` call in line# 8 and line# 12 respectively. Running `slt-globalize -e` under the application root directory, `/Users/user/gmain` will generate `intl/en/messages.json` and `intl/zz/messages.json` as shown in the [Pseudo Localization Support](#pseudo-localization-support) section. Note that `slt-globalize -e` extracts all strong-globalized literal strings as well as non-globalized literal string with positional information in to `intl/zz/messages.json`. It is useful to pin-point untranslated strings in the source code.
In the regular extraction mode, `strong-globalize` scans all JS and Html templates owned by the `gmain` package no matter how deep the directory structure goes -- for example, `gmain/lib/usa/california/sanfrancisco/util.js` is scanned. However, it does not examine dependent files under `node_modules` or `test` directory. All `strong-globalized` literal strings in JS and Html files of the target package will be extracted and stored in `intl/en/messages.json` along with the positional information stored in `intl/zz/messages.json`. All non-strong-globalized literal strings in the first argument of all JS function calls are extracted and stored in `intl/zz/messages.json` along with the positional information.
In runtime, the string resource JSON files under `intl` will be loaded on to memory as needed.
**Use Case**: Self-contained CLI utility package is typically code-globalized and distributed with or without translated messages.json. API library packages are typically code-globalized and distributed without translation. Such library packages are then downloaded and used as part of enterprise-scale applications.
```
/Users/user
└── gmain
├── index.js
├── intl
│ ├── de
│ ├── en
│ ├── es
│ ├── fr
│ ├── it
│ ├── ja
│ ├── ko
│ ├── pt
│ ├── ru
│ ├── zh-Hans
│ ├── zh-Hant
│ └── zz
├── lib
│ └── usa
│ └── california
│ └── sanfrancisco
│ └── util.js
├── node_modules
│ ├── express
│ ├── request
│ └── strong-globalize -> /usr/local/lib/node_modules/strong-globalize
└── package.json
```
## Deep Extraction
Enterprise-scale applications may depend on dozens of third party packages directly or indirectly. Such applications typically download dependent packages using `npm install` and can globalize them using the `Deep Extraction` mode.
For example, suppose `gmain` package has one dependent package `gsub` which is installed under `gmain/node_modules` as shown in the directory structure diagram below. `slt-globalize -d` traverses the `npm v3 style` dependency tree and extracts all the strong-globalized string literals into `gmain/intl/en/messages.json`. This way, all the literal strings in your package `gmain` as well as all the dependent modules are extracted and can be translated consistently at `gmain/intl` level. Note that the `package.json` dependency traversal is different from simple directory traversal.
Note that [string resource extraction from Html templates](#globalize-html-templates) is supported in the regular extraction mode only.
## `STRONGLOOP_GLOBALIZE_MAX_DEPTH` environment variable
As the size of your application grows, the number of dependent packages can grow exponentially. Since non-globalized literal strings are also recorded on `gmain/intl/zz/messages.json`, `gmain/intl/zz/messages.json` may also grow exponentially and cause `slt-globalize -d` to run out of resource on your computer.
To manage such situations, you can set `STRONGLOOP_GLOBALIZE_MAX_DEPTH` environment variable. `slt-globalize -d` stops traversing at the specified directory depth. Note that it works as directory depth although the traversal is controlled by dependencies defined in `package.json`.
For example, invoking `STRONGLOOP_GLOBALIZE_MAX_DEPTH=3 slt-globalize -d` under `/Users/user/gmain` works as follows. `gmain/index.js` is depth 1; thus examined. `gmain/lib/usa/california/sanfrancisco/util.js` is depth 5, not examined although it's part of your `gmain` package. `gmain/node_modules/gsub/index.js` is level 3, thus examined. Likewise, all the files directly under `gmain/node_modules/express` and `gmain/node_modules/request` will also be examined and literal strings are extracted to `gmain/intl/zz/messages.json`.
## `npm v3` dependency resolution
`npm v3` tries to install all dependent packages in the root `node_modules` directory, i.e., `gmain/node_modules` in the above example, which means that most dependent package directories are at depth level 2. Therefore, `STRONGLOOP_GLOBALIZE_MAX_DEPTH` does not help in `npm v3` installed applications. `slt-globalize -d [black list]` option can help to reduce the number of packages to scan.
```
/Users/user
└── gmain
├── index.js
├── intl
│ ├── de
│ ├── en
│ ├── es
│ ├── fr
│ ├── it
│ ├── ja
│ ├── ko
│ ├── pt
│ ├── ru
│ ├── zh-Hans
│ ├── zh-Hant
│ └── zz
├── lib
│ └── usa
│ └── california
│ └── sanfrancisco
│ └── util.js
├── node_modules
│ ├── express
│ ├── gsub
│ │ ├── index.js
│ │ ├── node_modules
│ │ │ └── strong-globalize -> /usr/local/lib/node_modules/strong-globalize
│ │ └── package.json
│ ├── request
│ └── strong-globalize -> /usr/local/lib/node_modules/strong-globalize
└── package.json
```
# HTML Template Globalization
Many UI strings are included in HTML templates. `slt-globalize -e` supports string extraction from the HTML templates as well as JS files. Once extracted, `slt-globalize -t` can be used to translate the resource JSON.
In the following example, the two strings `{{StrongLoop}} History Board` and `History board shows the access history to the e-commerce web site.` are extracted to JSON.
```html
{{ History board shows the access history to the e-commerce web site. | globalize }}