Globalization Pipeline Client for JavaScript

This is the JavaScript SDK for the Globalization Pipeline Bluemix service. The Globalization Pipeline service makes it easy for you to provide your global customers with Bluemix applications translated into the languages in which they work. This SDK currently supports Node.js.

News

⚠ Please note that support for Node v0.12 has been dropped in version 2.0 of this SDK. See the Node.js LTS schedule.

Sample

For a working Bluemix application sample, see gp-nodejs-sample.

Quickstart

You should familiarize yourself with the service itself. A good place to begin is by reading the Quick Start Guide and the official Getting Started with IBM Globalization documentation. The documentation explains how to find the service on Bluemix, create a new service instance, create a new bundle, and access the translated messages.
Next, add g11n-pipeline to your project, as well as cfenv and optional.

npm install --save g11n-pipeline cfenv optional
Load the client object as follows (using cfenv ).

var optional = require('optional');
var appEnv = require('cfenv').getAppEnv();
var gpClient = require('g11n-pipeline').getClient(
  optional('./local-credentials.json')   // if it exists, use local-credentials.json
    || {appEnv: appEnv}                  // otherwise, the appEnv
);

For local testing, create a local-credentials.json file with the credentials as given in the bound service:

{
  "credentials": {
    "url": "https://…",
    "userId": "…",
    "password": "……",
    "instanceId": "………"
  }
}

Using

To fetch the strings for a bundle named "hello", first create a bundle accessor:

    var mybundle = gpClient.bundle('hello');

Then, call the getStrings function with a callback:

    mybundle.getStrings({ languageId: 'es'}, function (err, result) {
        if (err) {
            // handle err..
            console.error(err);
        } else {
            var myStrings = result.resourceStrings;
            console.dir(myStrings);
        }
    });

This code snippet will output the translated strings such as the following:

    {
        hello:   '¡Hola!',
        goodbye: '¡Adiós!',
        …
    }

Translation Requests

To create a Translation request:

    gpClient.tr({
      name: 'My first TR',
      domains: [ 'HEALTHC' ],

      emails: ['my_real_email@me.example.com'],
      partner: 'IBM',
      targetLanguagesByBundle: {
          bundle1: [ 'es', 'fr', 'de' ], // review bundle1’s Spanish, etc… 
          bundle2: [ 'zh-Hans' ]   // review bundle2’s Simplified Chinese…
      },
      notes: [ 'This is a mobile health advice application.' ],
      status: 'SUBMITTED' // request to submit it right away.
    })
    .create((err, tr) => {
        if(err) { … handle err … }

        console.log('TR submitted with ID:', tr.id);
        console.log('Estimated completion:', 
            tr.estimatedCompletion.toLocaleString());
    });

To then check on the status of that request:

    gpClient.tr('333cfaecabdedbd8fa16a24b626848d6')
    .getInfo((err, tr) => {
        if(err) { … handle err … }

        console.log('Current status:', tr.status);
    });

Async

Note that all calls that take a callback are asynchronous. For example, the following code:

var bundle = client.bundle('someBundle');
bundle.create({…}, function(…){…});
bundle.uploadStrings({…}, function(…){…});

…will fail, because the bundle someBundle hasn’t been created by the time the uploadStrings call is made. Instead, make the uploadStrings call within a callback:

var bundle = client.bundle('someBundle');
bundle.create({…}, function(…){
    …
    bundle.uploadStrings({…}, function(…){…});
});

Testing

See TESTING.md

API convention

APIs take a callback and use this general pattern:

    gpClient.function( { /*opts*/ } ,  function callback(err, ...))

opts: an object containing input parameters, if needed.
err: if truthy, indicates an error has occured.
...: other parameters (optional)

Sometimes the opts object is optional. If this is the case, the API doc will indicate it with this notation: [opts] For example, bundle.getInfo(cb) and bundle.getInfo({}, cb) are equivalent.

These APIs may be promisified easily using a library such as Q's nfcall:

    return Q.ninvoke(bundle, "delete", {});
    return Q.ninvoke(gpClient, "getBundleList", {});

Also, note that there are aliases from the swagger doc function names to the convenience name. For example, bundle.uploadResourceStrings can be used in place of bundle.uploadStrings.

All language identifiers are IETF BCP47 codes.

API reference

Classes

Client
Bundle
User
ResourceEntry: ResourceEntry Creating this object does not modify any data.
TranslationRequest

Members

serviceRegex: a Regex for matching the service. Usage: var credentials = require('cfEnv') .getAppEnv().getServiceCreds(gp.serviceRegex); (except that it needs to match by label)
exampleCredentials: Example credentials such as for documentation.

Functions

getClient(params) ⇒ Client: Construct a g11n-pipeline client. params.credentials is required unless params.appEnv is supplied.

Typedefs

basicCallback : function: Basic Callback used throughout the SDK
ExternalService : Object: info about external services available
WordCountsInfo : object

Client

Kind: global class

Client
- new Client()
- instance
- inner
  - ~supportedTranslationsCallback : function
  - ~serviceInfoCallback : function
  - ~serviceInstanceInfoCallback : function
  - ~listUsersCallback : function
  - ~listBundlesCallback : function

new Client()

Client object for Globalization Pipeline

client.version

Version number of the REST service used. Currently ‘V2’.

Kind: instance property of Client

client.ping

Verify that there is access to the server. An error result will be returned if there is a problem. On success, the data returned can be ignored. (Note: this is a synonym for getServiceInfo())

Kind: instance property of Client

Param	Type	Description
args	`object`	(ignored)
cb	`basicCallback`

client.supportedTranslations([opts], cb)

This function returns a map from source language(s) to target language(s). Example: { en: ['de', 'ja']} meaning English translates to German and Japanese.