JavaScript/Node.js client for Globalization Pipeline
JavaScript HTML
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin CLI for gp-js-client Jul 7, 2018
lib
test cli: un/flatten test cases Jul 13, 2018
util more doc/doc-tr update May 27, 2018
.editorconfig eslint everything. fix whitespace. Sep 8, 2017
.eslintrc.js
.gitignore more doc/doc-tr update May 27, 2018
.travis.yml start to add doc api May 27, 2018
API.md CLI for gp-js-client Jul 7, 2018
CLI.md
CONTRIBUTING.md add CONTRIBUTING.md Jan 20, 2016
LICENSE.txt
README.md CLI for gp-js-client Jul 7, 2018
TESTING.md eslint everything. fix whitespace. Sep 8, 2017
package-lock.json 3.2.1-0 Jul 13, 2018
package.json 3.2.1-0 Jul 13, 2018
template.md
test.properties Rename, Update to Beta Nov 20, 2015

README.md

Globalization Pipeline Client for JavaScript

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

npm version Build Status Coverage Status Coverity Status

News

  • ⚠ Please note that at present, the 3.x version of the SDK requires Node 8 or later (async/await yes). See the Node.js LTS schedule. Use 2.x if you need to use Node versions back to 4. We may try to support prior Node versions in 3.x later if needed. Please comment on this issue if you have feedback.
  • New APIs will not support the callback model, but only return promises. Existing APIs that used to take a callback should continue to do so.

Sample

For a working IBM Cloud 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 IBM Cloud, 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:

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

Then, call the getStrings function:

    const {resourceStrings} = await mybundle.getStrings({ languageId: 'es'});
    console.dir(resourceStrings);

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

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

Translation Requests

To create a Translation request:

    const tr = await 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();
    console.log('TR submitted with ID:', tr.id);
    console.log('Estimated completion:', 
        tr.estimatedCompletion.toLocaleString());

To then check on the status of that request:

    const {status} = await gpClient.tr('333cfaecabdedbd8fa16a24b626848d6')
        .getInfo();

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

Async

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

var bundle = client.bundle('someBundle');
bundle.create().then(…);
bundle.uploadStrings().then(…);

…will fail, because the bundle someBundle hasn’t been created by the time the uploadStrings call is made. Instead, make sure create is called before uploadStrings:

var bundle = client.bundle('someBundle');
await bundle.create();
await bundle.uploadStrings();

Testing

See TESTING.md

Browserify

The gp-js-client can be used in a web browser via browserify.

You can call the g11n-pipeline API just as from Node.js:

// mycode.js
const gp = require('g11n-pipeline');
gp.getClient({/*...*/}) // do some great stuff here

And then, package up the code for the browser:

npm i --save g11n-pipeline
npm i -g browserify
browserify mycode.js > bundle.js

Finally, include the bundle in your HTML:

<script src="./bundle.js"></script>

API

See API.md for more details.

CLI

You can use the GP CLI to perform some operations from the commandline.

$ npm install -g g11n-pipeline
$ g11n-pipeline -j gpconfig.json ping
true

Using npx you do not even need to install g11n-pipeline to run a one-off command.

$ npx g11n-pipeline -j gpconfig.json ping
true

See CLI.md for more details.

Community

Contributing

See CONTRIBUTING.md.

License

Apache 2.0. See LICENSE.txt

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.