New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →

g11n-pipeline

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

g11n-pipeline

JavaScript (Node.js, etc) client for Bluemix Globalization Pipeline

2.0.3
Source
npm

Version published: 7 years ago

Weekly downloads: 11K; decreased by-7.17%

Maintainers: 1

Weekly downloads

Created: 9 years ago

Source

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
Web Browsers via Browserify

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

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 convention

APIs may take a callback OR return a promise, and use this general pattern

Promise mode

⚠ _please note that the apidocs haven’t been updated yet to note that the callback cb is optional and that Promises are returned by most functions.

    gpClient.function( { /* opts */ })
    .then( result => /* do something with result */)
    .catch( err => /* do something with err */ );

opts: an object containing input parameters, if needed.

Callback mode

Prior to v2.0, only the callback model was supported. This is still supported.

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

opts: an object containing input parameters, if needed.
callback: a callback with:
- err: if truthy, indicates an error has occured. -result: the operation’s result

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.

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

Bundle: Accessor object for a Globalization Pipeline bundle
Client: Client object for Globalization Pipeline
ResourceEntry: Globalization Pipeline individual resource entry accessor
TranslationRequest
User: Globalization Pipeline user access object

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.
exampleCredentialsString: Example credentials string
version: Current version

Functions

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

Typedefs

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

Bundle

Accessor object for a Globalization Pipeline bundle

Kind: global class
Properties

Name	Type	Description
updatedBy	`string`	userid that updated this bundle
updatedAt	`Date`	date when the bundle was last updated
sourceLanguage	`string`	bcp47 id of the source language
targetLanguages	`Array.<string>`	array of target langauge bcp47 ids
readOnly	`boolean`	true if this bundle can only be read
metadata	`Object.<string, string>`	array of user-editable metadata

Bundle
- new Bundle(gp, props)
- instance
- inner
  - ~getInfoCallback : function
  - ~listEntriesCallback : function

new Bundle(gp, props)

Note: this constructor is not usually called directly, use Client.bundle(id)

Param	Type	Description
gp	`Client`	parent g11n-pipeline client object
props	`Object`	properties to inherit

bundle.getInfoFields

List of fields usable with Bundle.getInfo()

Kind: instance property of Bundle

bundle.delete([opts], cb)

Delete this bundle.

Kind: instance method of Bundle

Param	Type	Default	Description
[opts]	`Object`	`{}`	options
cb	`basicCallback`

bundle.create(body, cb)

Create this bundle with the specified params. Note that on failure, such as an illegal language being specified, the bundle is not created.

Kind: instance method of Bundle

Param	Type	Description
body	`Object`
body.sourceLanguage	`string`	bcp47 id of source language such as 'en'
body.targetLanguages	`Array`	optional array of target languages
body.metadata	`Object`	optional metadata for the bundle
body.partner	`string`	optional ID of partner assigned to translate this bundle
body.notes	`Array.<string>`	optional note to translators
cb	`basicCallback`

bundle.getInfo([opts], cb)

Get bundle info. Returns a new Bundle object with additional fields populated.

Kind: instance method of Bundle

Param	Type	Default	Description
[opts]	`Object`	`{}`	Options object
opts.fields	`String`		Comma separated list of fields
opts.translationStatusMetricsByLanguage	`Boolean`		Optional field (false by default)
opts.reviewStatusMetricsByLanguage	`Boolean`		Optional field (false by default)
opts.partnerStatusMetricsByLanguage	`Boolean`		Optional field (false by default)
cb	`getInfoCallback`		callback (err, Bundle )

bundle.languages() ⇒ `Array.<String>`

Return all of the languages (source and target) for this bundle. The source language will be the first element. Will return undefined if this bundle was not returned by getInfo().

Kind: instance method of Bundle

bundle.getStrings(opts, cb)

Fetch one language's strings

Kind: instance method of Bundle

Param	Type	Default	Description
opts	`Object`		options
opts.languageId	`String`		language to fetch
[opts.fallback]	`boolean`	`false`	Whether if source language value is used if translated value is not available
[opts.fields]	`string`		Optional fields separated by comma
cb	`basicCallback`		callback (err, { resourceStrings: { strings… } })

bundle.entry(opts)

Create an entry object. Doesn't fetch data,

Kind: instance method of Bundle
See: ResourceEntry~getInfo

Param	Type	Description
opts	`Object`	options
opts.languageId	`String`	language
opts.resourceKey	`String`	resource key

bundle.entries(opts, cb)

List entries. Callback is called with a map of resourceKey to ResourceEntry objects.

Kind: instance method of Bundle

Param	Type	Description
opts	`Object`	options
opts.languageId	`String`	language to fetch
cb	`listEntriesCallback`	Callback with (err, map of resourceKey:ResourceEntry )

bundle.uploadStrings(opts, cb)

Upload resource strings, replacing all current contents for the language

Kind: instance method of Bundle

Param	Type	Description
opts	`Object`	options
opts.languageId	`String`	language to update
opts.strings	`Object.<string, string>`	strings to update
cb	`basicCallback`

bundle.update(opts, cb)

Kind: instance method of Bundle

Param	Type	Description
opts	`Object`	options
opts.targetLanguages	`array`	optional: list of target languages to update
opts.readOnly	`boolean`	optional: set this bundle to be readonly or not
opts.metadata	`object`	optional: metadata to update
opts.partner	`string`	optional: partner id to update
opts.notes	`Array.<string>`	optional notes to translator
cb	`basicCallback`	callback

bundle.updateStrings(opts, cb)

Update some strings in a language.

Kind: instance method of Bundle

Param	Type	Description
opts	`Object`	options
opts.strings	`Object.<string, string>`	strings to update.
opts.languageId	`String`	language to update
opts.resync	`Boolean`	optional: If true, resynchronize strings in the target language and resubmit previously-failing translation operations
cb	`basicCallback`

Bundle~getInfoCallback : `function`

Callback returned by Bundle~getInfo().

Kind: inner typedef of Bundle

Param	Type	Description
err	`object`	error, or null
bundle	`Bundle`	bundle object with additional data
bundle.updatedBy	`string`	userid that updated this bundle
bundle.updatedAt	`Date`	date when the bundle was last updated
bundle.sourceLanguage	`string`	bcp47 id of the source language
bundle.targetLanguages	`Array.<string>`	array of target langauge bcp47 ids
bundle.readOnly	`boolean`	true if this bundle can only be read
bundle.metadata	`Object.<string, string>`	array of user-editable metadata
bundle.translationStatusMetricsByLanguage	`Object`	additional metrics information
bundle.reviewStatusMetricsByLanguage	`Object`	additional metrics information

Bundle~listEntriesCallback : `function`

Called by entries()

Kind: inner typedef of Bundle

Param	Type	Description
err	`object`	error, or null
entries	`Object.<string, ResourceEntry>`	map from resource key to ResourceEntry object. The .value field will be filled in with the string value.

Client

Client object for Globalization Pipeline

Kind: global class

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

client.version

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

Kind: instance property of Client

client.url ⇒ `String`

Return the URL used for this client.

Kind: instance property of Client
Returns: String - - the URL

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.