Skip to content

tsaiyl/gp-js-client

BranchesTags
 
 

Repository files navigation

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.

npm version Build Status Coverage Status Coverity Status

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( { /*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.

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

ExternalService : Object

info about external services available

Client

Kind: global class

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.

Kind: instance method of Client

Param Type Default Description
[opts] object {} ignored
cb supportedTranslationsCallback (err, map-of-languages)

client.getServiceInfo([opts], cb)

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

Kind: instance method of Client

Param Type Default Description
[opts] object {} ignored argument
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 Default Description
[opts] Object {} options
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 Default Description
[opts] Object {} options
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.
info.externalServices Array.<ExternalService> info about external services available

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

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
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 {}
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 Default 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
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.

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

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([opts], 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 Default Description
[opts] Object {} options
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
sequenceNumber number relative sequence of this entry

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 Default Description
[opts] Object {} options
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
opts.sequenceNumber string sequence number of the entry (only for the source language)

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

ExternalService : Object

info about external services available

Kind: global typedef
Properties

Name Type Description
type string The type of the service, such as MT for Machine Translation
name string The name of the service
id string The id of the service
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.

docs autogenerated via jsdoc2md

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.

About

JavaScript/Node.js client for Globalization Pipeline

developer.ibm.com/open/ibm-bluemix-globalization-pipeline-service/node-js-sdk/

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

19 tags

Packages

No packages published

Languages

  • JavaScript 100.0%