Globalization Pipeline Ant Task User Guide

``` Note: You might place Globalization Pipeline Ant Task jar file in your Ant installations library directory ($ANT_HOME/lib). In this case, Ant will automatically find the task definitions without <taskdef> declaration.

Tasks

Following Ant tasks are currently available.

Specifying Globalization Pipeline Service Credentials

The ant task requires service instance administrator credentials for a Globalization Pipeline service instance.

There are two ways to specify the service credentials.

JSON file

The ant task can read service credentials from a JSON file. The JSON file must contain "url", "userId", "password" and "instanceId" fields as below.

{ "url": "https://g11n-pipeline-api.straker.global/translate/rest", "userId": "f02d4de9f115cc8b6e8c75a6c995f075", "password": "YOfm4qhW8D4stazDL7cBOBB1YV+kf1qa", "instanceId": "my-gp-instance" } Note: This is an example. You must replace field values with actual values used by your Globalization Pipeline service instance.

In your Ant build.xml, specify the JSON file in credentialsJson attribute in each Globalization Pipeline Ant task as below:

xml <target name="upload-resources"> <gp:upload credentialsJson= "gpcreds.json" sourceDir="src/main/resources"/> </target>

Specifying credentials in build.xml

The service credentials can be also embedded in build.xml using <credentials> tag as below.

xml <target name="upload-resources"> <gp:upload sourceDir="src/main/resources"> <credentials url="https://g11n-pipeline-api.straker.global/translate/rest" userId="f02d4de9f115cc8b6e8c75a6c995f075" password="YOfm4qhW8D4stazDL7cBOBB1YV+kf1qa" instanceId="my-gp-instance"/> </gp:upload> </target> Note: This is an example. You must replace attribute values with actual values used by Globalization Pipeline service instance.

Basic Use Case

build.xml below illustrates basic use cases of the ant tasks: ```xml

The ant target upload-resources in the example above does following operations:

1. Scans files under src/main/resources (sourceDir attribute) and locates files with .properties extension (but excluding files with '_'(underscore) character in its file name, such as Messages_fr.properties).

2. For each Java property resource bundle file, checks if corresponding Globalization Pipeline bundle already exists or not. If it's not available, creates a new bundle with all translation target languages currently configured in Machine Translation. English is used as the translation source language.

3. Extracts resource strings from each file, and uploads them to the matching Globalization Pipeline bundle as the translation source.

This task will synchronize the contents of a Globalization Pipeline bundle with the contents of local file. When a resource key was deleted from local file, it will be also deleted from the corresponding Globalization Pipeline bundle. If a resource string value was changed, this operation refreshes the corresponding resource string's value, which eventually triggers re-translation. When the contents is not changed since last invocation, this operation does not make any changes in the Globalization Pipeline bundles.

So the best practice would be invoking the task when any changes were made in translatable resource bundle files, although it's not harmful to invoke the goal at any time.

This ant target download-translations above does following operations:

1. Scans files under src/main/resources(sourceDir attribute) and locates Java property resource bundle files. This is same as in the upload goal.

2. For each Java property resource bundle file, looks up corresponding Globalization Pipeline bundle in the instance of Globalization Pipeline service.

3. If matching Globalization Pipeline bundle is found, copies the contents of source bundle file in local system, extracts resource strings from the Globalization Pipeline bundle, then replaces resource string values with ones extracted from the Globalization Pipeline bundle. The result file is generated under the standard build output directory (target/classes) (outputDir attribute) with language suffix, such as Messages_fr.properties for French. This operation is done for all available target languages in the Globalization Pipeline bundle.

Task Parameters

Upload task

The upload task should be configured using gp:upload task definition. The attributes and nested elements of gp:upload are described below:

Nested elements for upload task

credentials (optional, can be omitted if credentialsJson is specified.)

targetLanguage (optional)

bundleSet (optional)

fileSet (optional)

targetLanguage (nested within bundleSet, optional too)

files (nested within bundleSet/fileSet, required if bundleSet is used)

pathToResourceIdMapper (nested within bundleSet/fileSet, optional)

• See download task for element description

Download task

The download task should be configured using gp:download task definition. The attributes and nested elements of gp:download are described below:

Nested elements for download task

credentials (optional, can be omitted if credentialsJson is specified.)

targetLanguage (optional)

bundleSet (optional)

fileSet (optional)

targetLanguage (nested within bundleSet/fileSet, optional too)

languageMap (nested within bundleSet/fileSet, optional)

files (nested within bundleSet/fileSet, required if bundleSet is used)

pathToReourceIdMapper (nested within bundleSet/fileSet, optional)

Specifies a mapping rule for converting source bundle or source file path to Globalization Pipeline bundle or file ID. To specify a mapping rule, use one or more <regexMapper> elements with pattern and replacement. A source resource file path relative to the base source directory is used as the input of target path conversion specified by this setting. For each <regexMapper> element, substring matching a Java regular expression pattern specified by pattern value will be replaced with the value specified by replacement value.

The example below will remove .properties from a given path, then replace / with .. For example, an input path com/ibm/g11n/example/MyStrings.properties will produce a fully qualified Java class name com.ibm.g11n.example.MyStrings, which will be used as the Globalization Pipeline bundle or file ID for the resource file.

xml <pathToBundleMapper> <regexMapper pattern="(.+).properties" replacement="$1" /> <regexMapper pattern="/" replacement="\." /> </pathToBundleMapper>

sourcePathToTargetMapper (nested within bundleSet/fileSet, optional)

Specifies mapping rule(s) to control output file path in download task. To specify a mapping rule, use one or more <regexMapper> elements with pattern and replacement. A source resource file path relative to the base source directory (<directory> value in <sourceFiles> element) is used as the input of target path conversion specified by this setting. For each <regexMapper> element, substring matching a Java regular expression pattern specified by <pattern> value will be replaced with the value specified by <replacement> value. The final output path must contain a special place holder token %LANG%, which will be replaced with a target language code.

The example below will replace a folder en with %LANG%. For example, when a source file path is nls/comp1/en/Help.json, the path will be converted to nls/comp1/%LANG%/Help.json. Then, %LANG% will be replaced with language ID (configured by <languageIdStyle> and <languageMap>).

xml <sourcePathToTargetMapper> <regexMapper pattern="(.+)/en/([^/]+).json" replacement="$1/%LANG%/$2.json" /> </sourcePathToTargetMapper>

regexMapper (nested within pathToResourceIdMapper and sourcePathToTargetMapper)

Filter options

Filter options can be applied in any upload or download task by simply providing a filter option attribute. The attribute should look something like this: <filterOption key="JavaUTF8.colmax" value="50"/> and should be at the top nesting level under upload or download.