AngularJS for the Globalization Pipeline on IBM’s Bluemix
npm install angular-g11n-pipelineAngularJS for the Globalization Pipeline on IBM's Bluemix
===
gp-translate directive or service functions to handle the dynamic globalization needs of your app.
translate(key, lang)] function and a function to obtain a list of the available languages [getAvailableLanguages()]. A general purpose custom directive [gp-translation] is supplied to handle simple cases of calling the translation service. The translation service function can be incorporated into more complex user defined directives should your application require more extensive directives.
translate & getAvailableLanguages functions, other useful functions exposed from the service are:
setBundleId(newBundleId) - enables switching of the default bundle ID used for translations.
getBundleId() - returns the currently configured default bundle ID.
getLoadingText() - obtain the configured loading text value.
setTargetLang(newLang) - enables the application to override the browser default target language for translations.
removeTargetLang() - enables clearing of a configured targetLang.
bundleId]. For more granular control, the configured bundleId can be dynamically set in controllers by calling setBundleId(newBundleId) for a particular view. This allows a complex application to split up it's G11n application data into smaller more manageable bundles.
javascript
.controller('View1Ctrl', ['$routeParams', 'GlobalizationPipelineService', function($routeParams, gp) {
gp.setBundleId("oneOfYourBundleIds");
`
#### - _handling options for awaiting text translation_
While your application is waiting on the promise from the rest API, this SDK provides 2 facilities to handle the not yet available text. Support of ng-show or the specification of loading text.
##### -- _loading text_
The optional configuration parameter of loadingText provides a means to display some form of text to indicate that the app is waiting for something to complete. For example, if loadingText is set to loading... then text elements waiting on the translation will display loading... until the promise is resolved. Otherwise the elements will be blank.
##### -- _ng-show support_
ng-show is an AngularJS convention used to hold off on making elements visible until such time as everything is ready. This SDK supports ng-show thru the global var gpTranslationComplete.
Example:
`html
`
#### - _target language specification_
NOTE: While it is assumed that typical usage will be to use the language the user has set in the browser and not have a need to configure or change the targetLang configuration parameter, setTargetLang(newLang) & removeTargetLang() are provided to control overriding the browser setting should that be desirable. Along with being able to specify it on the function/directive.
The target language for the translation is determined in 1 of 3 ways (in order of precedence).
1. It can be supplied on the translation function call (or on the custom directive).
2. A target language can be set in the configuration (targetLang:) to eliminate the need to override it on each translation call.
3. Or use the language configured in the browser.
language override on the directive example:
`html
`
$3
This SDK provides a custom directive that handles straightforward use of translations and can be specified in two ways.
Example:
`html
`
In addition to specifying the key to be translated the directive also supports overriding the target language and/or the bundleId.
Example:
`html
`
$3
The gp-translate directive supports an optional values attribute that allows passing of custom data to it. This is used to inject
variables into the returned translation string. See https://docs.angularjs.org/api/ng/service/$interpolate for more details.
Example translation string:
"DATA-KEY-WITH-VARIABLE" : "Welcome {{user}}"
Example controller:
`
angular.module("TestModule", []).controller("TestController", ['$scope', function($scope) {
var ctrl = this;
ctrl.userName = { user : "John Doe" };
$scope.userNameInScope = "John Doe";
}]);
`
Example usage:
`html
`
Configuration
This service needs to be configured in order to talk to the GP server. On Bluemix you will need to configure the IBM Globalization Pipeline service, define bundle(s), and define a bundle reader. Once that is completed you can take that information and fill in your AngularJS config data to talk to the service.
bundleId is required to be present at the time of translation but does NOT have to be present at .config time.
Optional configuration for target language (targetLang) & text to display while waiting for the results from the rest call (loadingText) can be configure here as well.
Example of configuration
`javascript
.config(['GlobalizationPipelineServiceProvider', function(GlobalizationPipelineService) {
GlobalizationPipelineServiceProvider.setGpConfig({
bundleId: "YOUR-BUNDLE-NAME", // recommended unless dynamically set
targetLang: "es", // optional default language
loadingText: "loading...", // optional text displayed while waiting on a GP promise
credentials: {
url: "https://YOUR-SERVICE-INSTANCE-URL", // required
instanceId: "YOUR-INSTANCE-ID", // required
userId: "YOUR-BUNDLES-READER-ID", // required
password: "YOUR-BUNDLES-READER-PASSWORD" // required
}});
}])
``