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 - Bluemix

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 ). You can store a copy of the credentials in local-credentials.json for local operation.

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
);

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
- 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 IBM-Cloud#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
- 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 Client~~createUser() and User~~getInfo()

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

Support

You can post questions about using this service to StackOverflow using the tag "globalization-pipeline".

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.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
lib		lib
test		test
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
README.md		README.md
TESTING.md		TESTING.md
gen-html.js		gen-html.js
index.js		index.js
package.json		package.json
template-README.md		template-README.md
test.properties		test.properties

License

srl295/gp-js-client

Folders and files

Latest commit

History

Repository files navigation

Globalization Pipeline Client for JavaScript

Sample

Quickstart - Bluemix

Using

Async

Testing

API convention

API reference

Classes

Members

Functions

Typedefs

Client

new Client()

client.version

client.ping

client.supportedTranslations(args, cb)

client.getServiceInfo(args, cb)

client.createUser(args, cb)

client.bundle(opts) ⇒ Bundle

client.user(id) ⇒ User

client.users(opts, cb)

client.bundles(opts, cb)

Client~supportedTranslationsCallback : function

Client~serviceInfoCallback : function

Client~listUsersCallback : function

Client~listBundlesCallback : function

Bundle

new Bundle(gp, props)

bundle.getInfoFields

bundle.delete(opts, cb)

bundle.create(body, cb)

bundle.getInfo(opts, cb)

bundle.getStrings(opts, cb)

bundle.entry(opts)

bundle.uploadStrings(opts, cb)

bundle.update(opts, cb)

bundle.updateStrings(opts, cb)

Bundle~getInfoCallback : function

User

new User(gp, props)

user.update(opts, cb)

user.delete(cb)

user.getInfo(opts, cb)

User~getUserCallback : function

ResourceEntry

new ResourceEntry(bundle, props)

resourceEntry.getInfo(opts, cb)

resourceEntry.update()

ResourceEntry~getInfoCallback : function

serviceRegex

exampleCredentials

getClient(params) ⇒ Client

isMissingField(obj, fields) ⇒

basicCallback : function

Support

LICENSE

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

client.bundle(opts) ⇒ `Bundle`

client.user(id) ⇒ `User`

Client~supportedTranslationsCallback : `function`

Client~serviceInfoCallback : `function`

Client~listUsersCallback : `function`

Client~listBundlesCallback : `function`

Bundle~getInfoCallback : `function`

User~getUserCallback : `function`

ResourceEntry~getInfoCallback : `function`

getClient(params) ⇒ `Client`

basicCallback : `function`

Packages