gaas v1.0.1
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 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
- data
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
- value
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
###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~ResourceEntry Members
##class: gaas~Project Members
###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
- sourceLanguage
- 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
- newTargetLanguages
- cb
basicCallback
###project.getResourceData(args, cb) Get resourcedata for one language
Params
- args
object
- languageID
string
- which BCP47 language to get info for
- languageID
- 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
- languageID
- 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
- languageID
- 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
- languageID
- 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