Globalizaton Pipeline Maven Plugin is designed for integrating Globalization Pipeline service with Maven build. The plugin can upload translatable resource bundles from local file system to an instance of Globalization Pipeline service and download translated resource bundles to local file system.
This plugin runs on Java Runtime Environment 8 or later versions. The minimum Apache Maven version is 3.0.
Goals available for this plugin are below.
| Goal | Description |
|---|---|
| gp:upload | Upload translatable resource bundle files from local file system to an instance of Globalization Pipeline service. |
| gp:download | Download translated resource bundles from an instance of Globalization Pipeline service to local file system. |
To integrate Globalization Pipeline plugin with a Maven build, add X.Y.Z with an actual plug-in version.
<project> [...] <repositories> <repository> <id>gp-central</id> <name>Straker External Artifactory</name> <url>https://straker.jfrog.io/artifactory/ext-strakerglobal-maven-local/</url> </repository> </repositories> [...] <build> [...] <plugins> <plugin> <groupId>com.ibm.g11n.pipeline</groupId> <artifactId>gp-maven-plugin</artifactId> <version>X.Y.Z</version> </plugin> [...] </plugins> </build> [...] </project>
Update Maven settings.xml with the Straker maven repository credentials. ```
```
Please see this document for the details about the Straker Maven repository.
The plugin requires service instance administrator credentials for a Globalization Pipeline service instance. There are two ways to specify the service credentials.
The plugin 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" } To use the credentials stored in a JSON file, specify a system property gp.credentials.json. For example, if the file name is gpcreds.json, add -Dgp.credentials.json=gpcreds.json to Maven command line.
The service credentials can be also embedded in pom.xml using <credentials> configuration as below.
<plugin> <groupId>com.ibm.g11n.pipeline</groupId> <artifactId>gp-maven-plugin</artifactId> <version>2.0</version> <configuration> <credentials> <url>https://g11n-pipeline-api.straker.global/translate/rest</url> <userId>f02d4de9f115cc8b6e8c75a6c995f075</userId> <password>YOfm4qhW8D4stazDL7cBOBB1YV+kf1qa</password> <instanceId>my-gp-instance</instanceId> </credentials> </configuration> </plugin>
By default, Globalization Pipeline plugin assumes all translatable English resource bundle files are in Java property resource bundle format (*.properties) and they are placed under the standard directory (src/main/resources). If your project follow this convention, you don't need any extra configurations other than adding the plugin and specifying Globalization Pipeline service credentials.
$ mvn gp:upload This goal does following tasks:
Scans files under src/main/resources and locates files with .properties extension (but excluding files with '_'(underscore) character in its file name, such as Messages_fr.properties).
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. English is used as the translation source language.
Extracts resource strings from each file, and uploads them to the matching Globalization Pipeline bundle as the translation source.
This operation 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 this goal when any changes were made in translatable resource bundle files, although it's not harmful to invoke the goal at any time.
$ mvn gp:download This goal does following tasks:
Scans files under src/main/resources and locates Java property resource bundle files. This is same as in the upload goal.
For each Java property resource bundle file, check if look up corresponding Globalization Pipeline bundle in the instance of Globalization Pipeline service.
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) with language suffix, such as Messages_fr.properties for French. This operation is done for all available target languages in the Globalization Pipeline bundle.
In many cases, you will likely want to execute the goal during package phase and include translated resource bundles downloaded from an instance of Globalization Pipeline service. To execute the goal automatically in process-resources lifecycle, you can add `
<plugin> <groupId>com.ibm.g11n.pipeline</groupId> <artifactId>gp-maven-plugin</artifactId> <version>X.Y.Z</version> <executions> <execution> <goals> <goal>download</goal> </goals> </execution> </executions> </plugin>
Globalization Pipeline Maven Plugin supports various configuration parameters to customize the behavior. This section provides some use cases with these configuration parameters. Please see Configuration Parameter Reference for further information about the configuration parameters.
When you have translatable resource files not in the default location, you can use <bundleSets> to specify the location. This configuration supports multiple different directories.
For example, you have translatable English *.properties files under src/nls1/resources/en and src/nls2/resources/en. If you want to include both sets, use the configuration below.
<configuration> <bundleSets> <bundleSet> <sourceFiles> <directory>src/nls1/resources/en</directory> <includes> <include>**/*.properties</include> </includes> </sourceFiles> </bundleSet> <bundleSet> <sourceFiles> <directory>src/nls2/resources/en</directory> <includes> <include>**/*.properties</include> </includes> </sourceFiles> </bundleSet> </bundleSets> <configuration>
Globalization Pipeline service uses language ID "pt-BR" for Brazilian Portuguese, "zh-Hans" for Simplified Chinese and "zh-Hant" for Traditional Chinese. You may want to use just "pt" for Brazilian Portuguese, or "zh" for Simplified Chinese, "zh_TW" for Traditional Chinese as a part of output file name (or path). The following example does such mapping.
<configuration> <bundleSets> <bundleSet> <sourceFiles> <directory>src/resources</directory> <includes> <include>**/*.properties</include> </includes> <excludes> <exclude>**/*_*.properties</exclude> </excludes> </sourceFiles> <languageMap> <pt-BR>pt</pt-BR> <zh-Hans>zh</zh-Hans> <zh-Hant>zh-TW</zh-Hant> </languageMap> </bundleSet> </bundleSets> <configuration>
If you have properties file src/resources/com/ibm/example/MyStrings.properties, download goal will generate Brazilian Portuguese translated file target/classes/com/ibm/example/MyStrings_pt.properties instead of target/classes/com/ibm/example/MyStrings_pt_BR.properties
Note: The language ID separator used in the mapping should be '-' (Hyphen) for both, even you want translated file name (or path) to use '_' for the language part. In the example above, do not specify <zh-Hant>zh_TW</zh-Hant> even you want MyStrings_zh_TW.properties as the output file name. The language ID style is configured by <languageIdStyle>.
Your project may need place localized JSON files in its own language directory. Following example supports all JSON files in directory "en" and produces translated versions in parallel language directories.
```
```
<resourceLayout> specifies file name/path mapping behavior. LANGUAGE_DIR specifies localized version will use the same file name with source, but placed in a directory for the language. <languageIdStyle> specifies the style of language ID used for file/path name. BCP47 specifies the BCP 47 language tag. In this case, '-' (Hyphen) is used for subtag separators, such as 'zh-Hans'.
With this example, if you have English JSON resource file at src/main/webapp/res/en/MyStrings.json, French version is generated at target/MyApp/res/fr/MyStrings.json, and Simplified Chinese version is generated at target/MyApp/res/zh-Hans/MyStrings.json.
<credentials>Specifies Globalization Pipeline service credentials. There are 4 nested elements below.
<url> REST service URL, for example, https://g11n-pipeline-api.straker.global/translate/rest<userId> User ID<password> Password<instanceId> Service instance IDSee Specifying Globalization Pipeline Service Credentials for further information.
<outputDir>Specifies the output base directory used by download goal. This configuration parameter is also available in <bundleSet> element (see the section below), which overrides this configuration for the specified subset.
The default value is the standard Java class file output directory (target/classes).
<overwrite>Specifies a boolean value to control whether download goal overwrites translated resource bundle files already in the output directory or not. The default value "true"
<bundleSets><bundleSets> specifies sets of resource bundle files to be used as translation source bundles. Each set is defined by <bundleSet> elements. The next example illustrates how multiple <bundleSet> elements can be used.
<bundleSets> <bundleSet> <sourceFiles> <directory>src/main/resources</directory> <includes> <include>**/*.properties</include> </includes> </sourceFiles> <type>JAVA</type> [...] </bundleSet> <bundleSet> <sourceFiles> <directory>src/resources/jsonres</directory> <includes> <include>**/nls.json</include> </includes> </sourceFiles> <type>JSON</type> <resourceLayout></resourceLayout> [...] </bundleSet> [...] </bundleSets>
For each <bundleSet>, you can use following configuration parameters.
<sourceFiles> (required)Specifies a set of source bundle files.
<directory> (required) Base directory<includes> Sets for inclusion rules specified by nested <include> elements<include> Specifies a single rule for inclusion<excludes> Sets for exclusion rules specified by nested <exclude> elements<exclude> Specifies a single rule for exclusionThe inclusion/exclusion rules use the standard ant/maven fileset syntax. For example,
<sourceFiles> <directory>src/MyResources</directory> <includes> <include>**/*.json</include> </includes> <excludes> <exclude>**/config.json</exclude> </excludes> </sourceFiles> Above example includes all *.json files under src/MyResources directory, but excludes all files with file name config.json.
<type>Specifies a resource type. Available options are
The default value is JAVA.
<sourceLanguage>Specifies BCP 47 language tag for the language used in the source bundles. The default value is "en" (English).
<targetLanguages>Specifies a list of translation target languages by BCP 47 language tags. Each target language must be enclosed by <param> element. For example, if you want to set French ("fr"), German ("de") and Italian ("it") as target languages, the parameter should be specified as below:
<targetLanguages> <param>fr</param> <param>de</param> <param>it</param> </targetLanguages>
If this parameter is not specified, upload goal creates a new Globalization Pipeline bundle with all available machine translation target languages, and download goal exports all target languages currently available in the Globalization Pipeline bundle.
<pathToResourceIdMapper>Specifies a mapping rule for converting source bundle file path to Globalization Pipeline bundle 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 (<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 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 ID for the resource file.
<pathToResourceIdMapper> <regexMapper> <pattern>(.+).properties</pattern> <replacement>$1</replacement> </regexMapper> <regexMapper> <pattern>/</pattern> <replacement>\.</replacement> </regexMapper> </pathToResourceIdMapper>
<languageMap>Specifies custom language mappings. Each nested element name is a BCP 47 language tag used by Globalization Pipeline service instance, and the element value is a language ID used for output resource file or path name. For example, Globalization Pipeline service uses language ID "pt-BR" for Brazilian Portuguese. If you want to use just "pt" for output file or path name, you can specify the mapping as below.
<languageMap> <pt-BR>pt</pt-BR> </languageMap>
There are no custom language ID mappings by default.
<languageIdStyle>Specifies one of following keywords to configure the rule for composing language ID used for output resource bundle file or path name.
The default value is BCP47_UNDERSCORE.
<outputDir>Specifies the output base directory for this <bundleSet>. If not specified, <outputDir> just under <configuration> for this plugin will be used.
<outputSourceLanguage>Specifies a boolean value to control whether download goal also produces resource bundle files for a source language. The default value is "false".
<outputContentOption>Specifies one of following keywords to control how download goal generates the contents of translated resource bundle files.
The default value is MERGE_TO_SOURCE.
<resourceLayout>Specifies one of following keywords to control output file name or path in download goal.
com/ibm/g11n/MyMessages.properties, then the French version will be com/ibm/g11n/MyMessages_fr.properties.res/en.json, then the French version will be res/fr.json.res/MyMessages.json, then the French version will be res/fr/MyMessages.json.com/ibm/g11n/en/MyMessages.properties, then the French version will be com/ibm/g11n/fr/MyMessages.properties.The default value is LANGUAGE_SUFFIX.
Note: This element is ignored when <sourcePathToTargetMapper> is specified.
<sourcePathToTargetMapper>Specifies mapping rule(s) to control output file path in download goal. 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>).
<sourcePathToTargetMapper> <regexMapper> <pattern>(.+)/en/([^/]+).json</pattern> <replacement>$1/%LANG%/$2.json</replacement> </regexMapper> </sourcePathToTargetMapper>
The configuration below is used when <configuration> element is not explicitly specified in pom.xml
<configuration> <bundleSets> <bundleSet> <sourceFiles> <directory>src/main/resources</directory> <includes> <include>**/*.properties</include> </includes> <excludes> <exclude>**/*_*.properties</exclude> </excludes> </sourceFiles> <type>JAVA</type> <sourceLanguage>en</sourceLanguage> <languageIdStyle>BCP47_UNDERSCORE</languageIdStyle> <outputSourceLanguage>false</outputSourceLanguage> <outputContentOption>MERGE_TO_SOURCE</outputContentOption> <resourceLayout>LANGUAGE_SUFFIX</resourceLayout> </bundleSet> </bundleSets> <outputDir>target/classes</outputDir> <overwrite>true</overwrite> </configuration>
<fileSets>This is similar to <bundleSets> above, but for PII files in GP.
There are <fileSet> elements under <fileSets>. Please add an additional config of <resourceType>file</resourceType> to process these.
An example of this feature is :
<fileSets> <fileSet> <resourceType>file</resourceType> <sourceFiles> <directory>src/main</directory> <includes> <include>**/html/*.html</include> </includes> </sourceFiles> <outputDir>src/main</outputDir> <targetLanguages> <param>fr</param> <param>ja</param> </targetLanguages> <resourceLayout>LANGUAGE_DIR</resourceLayout> </fileSet> </fileSets>
<codePattern>A code pattern can now be supplied through maven configuration. This is available for both files and bundles, and supplied as an element to a <fileSet> or <bundleSet> during upload like so:
<fileSets> <fileSet> <codePattern>(.+)</codePattern> ....
<dntTerms>A list of "do not translate" terms can now be supplied through maven configuration. This is available for both files and bundles, and supplied as an element to a <fileSet> or <bundleSet> during upload like so:
<fileSets> <fileSet> <codePattern>term1,term2,term3</codePattern> ....