g11n-pipeline

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.

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!',
        …
    }

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( { /*params*/ } ,  function callback(err, ...))

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

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.

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

Functions

getClient(params) ⇒ Client

Construct a g11n-pipeline client. params.credentials is required unless params.appEnv is supplied.

isMissingField(obj, fields) ⇒

Return a list of missing fields. Special cases the instanceId field.

Typedefs

basicCallback : function

Basic Callback used throughout the SDK

Client

Kind: global class

• Client
  • new Client()
  • instance
    • .version
    • .ping
    • .supportedTranslations(args, cb)
    • .getServiceInfo(args, cb)
    • .createUser(args, cb)
    • .bundle(opts) ⇒ Bundle
    • .user(id) ⇒ User
    • .users(opts, cb)
    • .bundles(opts, cb)
  • inner
    • ~supportedTranslationsCallback : function
    • ~serviceInfoCallback : 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(args, 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.

Kind: instance method of Client

Param	Type	Description
args	object
cb	supportedTranslationsCallback	(err, map-of-languages)

client.getServiceInfo(args, cb)

Get information about this service. At present, no information is returned beyond that expressed by supportedTranslations().

Kind: instance method of Client

Param	Type
args	object
cb	serviceInfoCallback

client.createUser(args, cb)

Create a user

Kind: instance method of Client

Param	Type	Description
args	object
args.type	string	User type (ADMINISTRATOR, TRANSLATOR, or READER)
args.displayName	string	Optional display name for the user. This can be any string and is displayed in the service dashboard.
args.comment	string	Optional comment
args.bundles	Array	set of accessible bundle ids. Use ['*'] for “all bundles”
args.metadata	Object.<string, string>	optional key/value pairs for user metadata
args.externalId	string	optional external user ID for your application’s use
cb	getUserCallback	passed a new User object

client.bundle(opts) ⇒ Bundle

Create a bundle access object. This doesn’t create the bundle itself, just a handle object. Call create() on the bundle to create it.

Kind: instance method of Client

Param	Type	Description
opts	Object	String (id) or map {id: bundleId, serviceInstance: serviceInstanceId}

client.user(id) ⇒ User

Create a user access object. This doesn’t create the user itself, nor query the server, but is just a handle object. Use createUser() to create a user.

Kind: instance method of Client

Param	Type	Description
id	Object	String (id) or map {id: bundleId, serviceInstance: serviceInstanceId}

client.users(opts, cb)

List users. Callback is called with an array of user access objects.

Kind: instance method of Client

Param	Type	Description
opts	Object	ignored
cb	listUsersCallback	callback

client.bundles(opts, cb)

List bundles. Callback is called with an map of bundle access objects.

Kind: instance method of Client

Param	Type	Description
opts	Object	ignored
cb	listBundlesCallback	given a map of Bundle objects

Client~supportedTranslationsCallback : function

Callback returned by supportedTranslations()

Kind: inner typedef of Client

Param	Type	Description
err	object	error, or null
languages	Object.<string, Array.<string>>	map from source language to array of target languages Example: { en: ['de', 'ja']} meaning English translates to German and Japanese.

Client~serviceInfoCallback : function

Callback used by getServiceInfo()

Kind: inner typedef of Client

Param	Type	Description
err	object	error, or null
info	Object	detailed information about the service
info.supportedTranslation	Object.<string, Array.<string>>	map from source language to array of target languages Example: { en: ['de', 'ja']} meaning English translates to German and Japanese.

Client~listUsersCallback : function

Called by users()

Kind: inner typedef of Client
See: User

Param	Type	Description
err	object	error, or null
users	Object.<string, User>	map from user ID to User object

Client~listBundlesCallback : function

Bundle list callback

Kind: inner typedef of Client

Param	Type	Description
err	object	error, or null
bundles	Object.<string, Bundle>	map from bundle ID to Bundle object

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
    • .getInfoFields
    • .delete(opts, cb)
    • .create(body, cb)
    • .getInfo(opts, cb)
    • .getStrings(opts, cb)
    • .entry(opts)
    • .uploadStrings(opts, cb)
    • .update(opts, cb)
    • .updateStrings(opts, cb)
  • inner
    • ~getInfoCallback : 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
opts	Object
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
cb	basicCallback

bundle.getInfo(opts, cb)

Get bundle info

Kind: instance method of Bundle

Param	Type	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, { updatedBy, updatedAt, sourceLanguage, targetLanguages, readOnly, metadata, partner} )

bundle.getStrings(opts, cb)

Fetch one language's strings

Kind: instance method of Bundle

Param	Type	Description
opts	Object	options
opts.languageId	String	language to fetch
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.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
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.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(). NOTE: this will be changed to be an actual Bundle object - see https://github.com/IBM-Bluemix/gp-js-client/issues/19

Kind: inner typedef of Bundle

Param	Type	Description
err	object	error, or null
bundle	Object	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

User

Kind: global class
Properties

Name	Type	Description
id	String	the userid
updatedBy	String	gives information about which user updated this user last
updatedAt	Date	the date when the item was updated
type	String	ADMINISTRATOR, TRANSLATOR, or READER
displayName	String	optional human friendly name
metadata	Object.<string, string>	optional user-defined data
serviceManaged	Boolean	if true, the GP service is managing this user
password	String	user password
comment	String	optional user comment
externalId	String	optional User ID used by another system associated with this user
bundles	Array.<string>	list of bundles managed by this user

• User
  • new User(gp, props)
  • instance
    • .update(opts, cb)
    • .delete(cb)
    • .getInfo(opts, cb)
  • inner
    • ~getUserCallback : function

new User(gp, props)

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

Param	Type	Description
gp	Client	parent Client object
props	Object	properties to inherit

user.update(opts, cb)

Update this user. All fields of opts are optional. For strings, falsy = no change, empty string '' = deletion.

Kind: instance method of User

Param	Type	Description
opts	object	options
opts.displayName	string	User's display name - falsy = no change, empty string '' = deletion.
opts.comment	string	optional comment - falsy = no change, empty string '' = deletion.
opts.bundles	Array.<string>	Accessible bundle IDs.
opts.metadata	object.<string, string>	User defined user metadata containg key/value pairs. Data will be merged in. Pass in {} to erase all metadata.
opts.externalId	string	User ID used by another system associated with this user - falsy = no change, empty string '' = deletion.
cb	basicCallback	callback with success or failure

user.delete(cb)

Delete this user. Note that the service managed user (the initial users created by the service) may not be deleted.

Kind: instance method of User

Param	Type	Description
cb	basicCallback	callback with success or failure

user.getInfo(opts, cb)

Fetch user info. The callback is given a new User instance, with all properties filled in.

Kind: instance method of User

Param	Type	Description
opts	Object	optional, ignored
cb	getUserCallback	called with updated info

User~getUserCallback : function

Callback called by ClientcreateUser() and UsergetInfo()

Kind: inner typedef of User

Param	Type	Description
err	object	error, or null
user	User	On success, the new or updated User object.

ResourceEntry

ResourceEntry Creating this object does not modify any data.

Kind: global class
See: Bundle~entries
Properties

Name	Type	Description
resourceKey	String	key for the resource
updatedBy	string	the user which last updated this entry
updatedAt	Date	when this entry was updated
value	string	the translated value of this entry
sourceValue	string	the source value of this entry
reviewed	boolean	indicator of whether this entry has been reviewed
translationStatus	string	status of this translation: source_language, translated, in_progress, or failed
entry.metadata	Object.<string, string>	user metadata for this entry
partnerStatus	string	status of partner integration

• ResourceEntry
  • new ResourceEntry(bundle, props)
  • instance
    • .getInfo(opts, cb)
    • .update()
  • inner
    • ~getInfoCallback : function

new ResourceEntry(bundle, props)

Note: this constructor is not usually called directly, use Bundle.entry(...)

Param	Type	Description
bundle	Bundle	parent Bundle object
props	Object	properties to inherit

resourceEntry.getInfo(opts, cb)

Load this entry's information. Callback is given another ResourceEntry but one with all current data filled in.

Kind: instance method of ResourceEntry

Param	Type	Description
opts	Object	options (currently ignored)
cb	getInfoCallback	callback (err, ResourceEntry)

resourceEntry.update()

Update this resource entry's fields.

Kind: instance method of ResourceEntry

Param	Type	Description
opts.value	string	string value to update
opts.reviewed	boolean	optional boolean indicating if value was reviewed
opts.metadata	object	optional metadata to update
opts.partnerStatus	string	translation status maintained by partner

ResourceEntry~getInfoCallback : function

Callback called by ResourceEntry~getInfo()

Kind: inner typedef of ResourceEntry

Param	Type	Description
err	object	error, or null
entry	ResourceEntry	On success, the new or updated ResourceEntry object.

serviceRegex

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

Kind: global variable
Properties

Name
serviceRegex

exampleCredentials

Example credentials

Kind: global variable
Properties

Name
exampleCredentials

getClient(params) ⇒ Client

Construct a g11n-pipeline client. params.credentials is required unless params.appEnv is supplied.

Kind: global function

Param	Type	Description
params	Object	configuration params
params.appEnv	Object	pass the result of cfEnv.getAppEnv(). Ignored if params.credentials is supplied.
params.credentials	Object.<string, string>	Bound credentials as from the CF service broker (overrides appEnv)
params.credentials.url	string	service URL. (should end in '/translate')
params.credentials.userId	string	service API key.
params.credentials.password	string	service API key.
params.credentials.instanceId	string	instance ID

isMissingField(obj, fields) ⇒

Return a list of missing fields. Special cases the instanceId field.

Kind: global function
Returns: array of which fields are missing

Param	Description
obj	obj containing fields
fields	array of fields to require

basicCallback : function

Basic Callback used throughout the SDK

Kind: global typedef

Param	Type	Description
err	Object	error, or null
data	Object	Returned data

docs autogenerated via jsdoc2md

Community

• View or file GitHub Issues
• Connect with the open source community on developerWorks Open

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.