gaas

JavaScript Client for IBM Bluemix Globalization-as-a-Service

What is this?

This is a JavaScript client and sample code for the IBM Globalization Bluemix service. The IBM Globalization service makes it easy for you to provide your global customers with Bluemix applications translated into the languages in which they work.

Using the client code in this project, either from node.js, or from any browser using the jQuery sample code, your application can dynamically request translations of your application content from the IBM Globalization service.

jQuery Sample

There is an experimental sample showing use of the use in the jquery-sample directory. See the Readme in that directory for more details.

Node.js

The rest of this document explains how to use the Globalization service with the node.js client.

For a working Bluemix application sample, see gaas-nodejs-hello.

Quickstart - Bluemix

Add gaas to your project, as well as cfenv.

npm install --save gaas cfenv

Load the gaas client object as follows (using cfenv ). Note that /IBM Globalization.*/ will match any service named with something starting with IBM Globalization (the default).

var appEnv = require('cfenv').getAppEnv();
var gaasClient = require('gaas').getClient({
   credentials:  appEnv.getService(/IBM Globalization.*/).credentials
});

Or, if you are providing credentials manually:

var gaasClient = require('gaas').getClient({
 credentials: {
    uri: 'https://<GaaS server URL>',
    api_key: '<your API key>'
 }
});

Note that api_key can be from the bound service credentials, or else a "reader key" as visible in the IBM Globalization service dashboard.

To load the key "hello" in Spanish from the project named "world" you can use this code:

var myProject = gaasClient.project('world');

myProject.getResourceEntry({
      resKey: 'hello',
      languageID: 'es'
    },
    function(err, entry) {
        if(err) {
            console.error(err); return;
        } else if(entry.value) {
            console.log( entry.value ); // Print out the value!
        } else {
            console.error('Status is ' + entry.translationStatus); // may be: 'inProgress' or 'failed'
        }
});

API convention

APIs which take a callback use this pattern:

obj.function( { /*params*/ } , function callback(err, ...))

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

All language identifiers are IETF BCP47 codes.

API reference

#gaas Author: Steven R. Loomis
Members

• gaas
  • callback: gaas~basicCallback
  • callback: gaas~supportedTranslationsCallback
  • callback: gaas~projectInfoCallback
  • callback: gaas~resourceCallback
  • callback: gaas~resourceCallback
  • callback: gaas~listCallback
  • class: gaas~Client
    • client.supportedTranslations(args, cb)
    • client.ping(args, cb)
    • client.project(projectID, props)
    • client.listProjects(args)
  • class: gaas~ResourceData
  • class: gaas~ResourceEntry
  • class: gaas~Project
    • project.create(args, cb)
    • project.remove(args, cb)
    • project.getInfo()
    • project.addTargetLanguages(args, cb)
    • project.getResourceData(args, cb)
    • project.updateResourceData(args, cb)
    • project.deleteLanguage(args, cb)
    • project.getResourceEntry(args, cb)

##callback: gaas~basicCallback Params

• err object - if(err), error
• result object - any result data

Scope: inner typedef of gaas
Type: function
##callback: gaas~supportedTranslationsCallback Params

• err object - if(err), error
• translations Object.<string, Array.<string>> - source : [target...] languages

Scope: inner typedef of gaas
Type: function
##callback: gaas~projectInfoCallback Params

• err object - if(err), error
• project Project - the updated Project object with the latest data

Scope: inner typedef of gaas
Type: function
##callback: gaas~resourceCallback Params

• err object - if(err), error
• resource ResourceData - the specified resource data
  • data Object.<string, string> - the translated key/value pairs
  • inProgress Array.<string> - a list of the keys that are still in progress
  • failed Array.<string> - a list of the keys that failed to translate

Scope: inner typedef of gaas
Type: function
##callback: gaas~resourceCallback Params

• err object - if(err), error
• entry ResourceEntry - the specified resource entry
  • value string - the entry's string value
  • translationStatus string - the entry's translation status

Scope: inner typedef of gaas
Type: function
##callback: gaas~listCallback Params

• err object - if(err), error
• projects Object.<string, Project> - map from project ID to project object

Scope: inner typedef of gaas
Type: function
##class: gaas~Client Members

• class: gaas~Client
  • client.supportedTranslations(args, cb)
  • client.ping(args, cb)
  • client.project(projectID, props)
  • client.listProjects(args)

###client.supportedTranslations(args, cb) This function returns a map from source language(s) to target language(s).

Params

• args object
• cb supportedTranslationsCallback

###client.ping(args, cb) Do we have access to the server?

Params

• args object - (ignored)
• cb callback

###client.project(projectID, props) Create a new Project object for further access. Note that this function doesn't create the project or fetch any information.

Params

• projectID string
• props object - optional properties to set on the object

###client.listProjects(args) List the projects available

Params

• args object - currently not used

##class: gaas~ResourceData Members

• class: gaas~ResourceData

##class: gaas~ResourceEntry Members

• class: gaas~ResourceEntry

##class: gaas~Project Members

• class: gaas~Project
  • project.create(args, cb)
  • project.remove(args, cb)
  • project.getInfo()
  • project.addTargetLanguages(args, cb)
  • project.getResourceData(args, cb)
  • project.updateResourceData(args, cb)
  • project.deleteLanguage(args, cb)
  • project.getResourceEntry(args, cb)

###project.create(args, cb) Create the project

Params

• args object - parameters for creation
  • sourceLanguage string - BCP47 langauge tag of translation source
  • targetLanguages Array.<string> - optional array of BCP47 language tags for translation target
• cb basicCallback

###project.remove(args, cb) Remove the project

Params

• args object - (ignored)
• cb basicCallback

###project.getInfo() Fetch project information. The callback is given a new Project object with updated information.

###project.addTargetLanguages(args, cb) Add target languages to the project

Params

• args object
  • newTargetLanguages Array.<string> - array of 1 or more languages to add
• cb basicCallback

###project.getResourceData(args, cb) Get resourcedata for one language

Params

• args object
  • languageID string - which BCP47 language to get info for
• cb resourceCallback

###project.updateResourceData(args, cb) Update resource data and/or retry translation

Params

• args object
  • languageID string - language to update (source or target)
  • body object
  • replace boolean - if true, replace ALL resource keys instead of just appending
  • retry boolean - if true, retry translation
  • data Object.<string, string> - key/value pairs to update
• cb basicCallback

###project.deleteLanguage(args, cb) Delete a target language from the project. (Source languages cannot be deleted)

Params

• args object
  • languageID string - BCP47 id of language to delete
• cb basicCallback

###project.getResourceEntry(args, cb) Get a single ResourceEntry

Params

• args object
  • languageID string - langauge name to fetch
  • resKey string - key name to fetch
• cb entryCallback

docs autogenerated via jsdoc2md

Support

You can post questions about using this service in the developerWorks Answers site using the tag "Globalization".

LICENSE

Apache 2.0. See LICENSE.txt