Globalization Pipeline CLI Tool User Guide

Overview

Globalization Pipeline CLI (Command Line Interface) Tool is designed for manipulating translation bundles hosted by Globalization Pipeline service on command line.

Prerequisites

Globalization Pipeline CLI Tool is distributed in a single jar package. You need Java SE Runtime Environment 8 or later version to run the tool.

Command Reference

Most of commands takes user credentials for a Globalization Pipeline service instance. The common command options for specifying user credentials are below.

For example, java -jar gp-cli.jar list-bundle -s https://g11n-pipeline-api.straker.global/translate/rest -i my-gp-instance -u 8492e8d7bc28d9dc34a31a6d0ec7384e -p DoRfuq1w1ohx8vKXoZHHMenxxpSyoF0u

Alternatively, you can store the credentials in a JSON file and use -j (--jsonCreds) option to specify the file. For example, you can create a JSON file `mycreds.json' with the contents below (Note: actual property values should match the actual service instance's credentials): { "url": "https://g11n-pipeline-api.straker.global/translate/rest", "userId": "8492e8d7bc28d9dc34a31a6d0ec7384e", "password": "DoRfuq1w1ohx8vKXoZHHMenxxpSyoF0u", "instanceId": "my-gp-instance" } With -j option, following command is equivalent to the above example. java -jar gp-cli.jar list-bundle -j mycreds.json

Common Options for Bundle and File Commands

The following command line options can be used in conjunction with the create commands for bundles for files or bundles:

The following command line option can be used in conjunction with the update commands for bundles for files or bundles:

Help Command

The help command prints out all commands and available options. java -jar gp-cli.jar help

Profile Commands

A profile is group of settings that define the ways your translations are to be handled and billed for your service instance. The most critical portion of a profile is the consumption metadata section, which defines the domain (UTL-20), product ID, and version for billing purposes. Also included is the ability to define custom machine translation engines (Watson), the human translation provider, ( i.e. the TEST provider for testing purposes, or STRAKER for billed human translation activities ), and a custom GRTS ( memory registration ) domain for memory matching features. A GP service instance can contain multiple profiles. The "default" profile is always used for machine translation activities, while any other profile can be specified when creating a translation request (TR).

create-profile

Creates or updates a profile. To update a profile that already exists, simply provide the new information like you would to create a new one. The existing profile will be overwritten in this case.

Options:

Profile data should be provided using a JSON file using the following example as a reference. Only the consumption metadata fields are required. Others are optional depending on your preference:

{ "consumptionMetadata": { "domain": "20B14", "productId": "694344W", "version": "11.0", "documentType": "PII", "requester": "requester@us.ibm.com", "surrogate": "surrogate@us.ibm.com" }, "grts": { "searchDomainCodes": [ "security", "others" ], "registerDomainCode": "security" } }

Example:

java -jar gp-cli.jar create-profile -r default -f profiledata.json -j mycreds.json

list-profiles

Lists the names of translation profiles that have been defined for this service instance:

java -jar gp-cli.jar list-profiles -j mycreds.json

show-profile

Shows detailed information about a defined translation profile

Options:

java -jar gp-cli.jar show-profile -r default -j mycreds.json

delete-profile

Deletes a translation profile. The "default" profile cannot be deleted.

Options:

java -jar gp-cli.jar delete-profile -r profile-01 -j mycreds.json

Bundle Commands

list (list-bundle)

Prints out a list of bundle IDs available in the service instance.

java -jar gp-cli.jar list -j mycreds.json

Below is an example output

["MyBundle1", "MyBundle2"]

show (show-bundle)

Prints out a bundle's summary information. The following example shows the information of bundle MyBundle1.

java -jar gp-cli.jar show -b MyBundle1 -j mycreds.json

Below is an example output.

{ "sourceLanguage": "en", "targetLanguages": [ "de", "es", "fr", "it", "ja", "ko", "pt", "zh-Hans", "zh-Hant" ], "readOnly": false, "updatedBy": "(dash+3f4bb9f12d6f5db965482811c81ca215)mike@acme.com", "updatedAt": "2016-07-07T12:02:34.788-04" }

create (create-bundle)

Creates a new bundle. This command creates an empty bundle with specified bundle ID and languages.

The following example creates a new bundle with ID MyNewBundle with English(en) as source language, and French(fr) and German(de) as target languages. The first language specified in -l option is the source language, and the rest of languages are the translation target languages.

java -jar gp-cli.jar create -b MyNewBundle -l en,fr,de -j mycreds.json

update (update-bundle)

Updates an existing bundle's configuration.

The following example sets French (fr), German (de) and Italian (it) as target languages and the translation instruction note "These are Java MessageFormat ...".

java -jar gp-cli.jar update -b MyBundle -l fr,de,it -n "These are Java MessageFormat pattern strings" -j mycreds.json

import

Imports resource data to a bundle. This command takes an input language. If the language does not exist in the bundle, the language will be automatically added to the bundle configuration.

There are several different resource types available:

When importing target language content to a bundle, you can also use the following flags to indicate the status of the target language strings.

As one would expect, you can't use -r and -R at the same time, nor can you use -v and -V at the same time.

For example, the followng example imports English (en) resource strings in Java properties file MyBundle.properties to the bundle MyBundle.

java -jar gp-cli.jar import -b MyBundle -l en -t JAVA -f MyBundle.properties -j mycreds.json

export

Exports the contents of bundle to a resource bundle file. The supported resource bundle types are same with the import command.

For example, the following example exports French (fr) resource strings from the bundle MyBundle to the Java property file MyBundle_fr.properties.

java -jar gp-cli.jar export -b MyBundle -l fr -t JAVA -f MyBundle_fr.properties -j mycreds.json

If you have the original (source) resource bundle file, and you want to keep the original format including the order of resource keys, comments and others, -o option might be used. This feature is not supported by some resoruce types such as JSON.

When translated resource string value is not available, the export command does not include the resource key in the output by default. If you want to include such resource key with the value from the source language, you can specify -k option.

Some resource filters support custom parameters to support optional behaviors. For example, Java properties filter (JAVA) supports following custom parameters.

To specify these custom parameters, you can use --filterParam option. This option only takes one key-value pair. To specify multiple parameters, use --filterParam multiple times, for example --filterParam COLMAX=120 --filterParam LOWERCASEHEX=true.

export-problematic-res-entries

Exports problematic source resource entries in the bundle(s) to a json file.

For example, exports problematic source resource entries in a bundle.

java -jar gp-cli.jar export-problematic-res-entries -b MyBundle -o entires.json -j mycreds.json

Exports problematic source resource entries in a list of bundles.

java -jar gp-cli.jar export-problematic-res-entries -bl MyBundle.lst -o entires.json -j mycreds.json

Below is an example in output file.

{ "MyBundle": { "key2": { "sourceValue": "Syntax error: Missing or mismatch element <% or %> at line <Variable formatSpec=\"{line}\">line</Variable>", "unit": "<unit id=\"key2\"><mda:metadata xmlns:mda=\"urn:oasis:names:tc:xliff:metadata:2.0\"><mda:metaGroup category=\"caits-prep\"><mda:meta type=\"process-format\">text/plain</mda:meta><mda:meta type=\"WARN_UNSUPPORTED_HTML\">Unable to process the content containing one or more document parts</mda:meta></mda:metaGroup></mda:metadata><segment id=\"s1\"><source xml:space=\"preserve\">Syntax error: Missing or mismatch element &lt;% or %&gt; at line &lt;Variable <mrk id=\"1\" type=\"caits:regex-no-translate\" translate=\"no\">formatSpec=\"{line</mrk>}\"&gt;line&lt;/Variable&gt;</source></segment></unit>", "sourceIssues": [ { "type": "WARN_UNSUPPORTED_HTML", "message": "Unable to process the content containing one or more document parts" } ] }, "key6": { "sourceValue": "Bad <span class-123>HTML", "unit": "<unit id=\"key6\"><mda:metadata xmlns:mda=\"urn:oasis:names:tc:xliff:metadata:2.0\"><mda:metaGroup category=\"caits-prep\"><mda:meta type=\"process-format\">text/plain</mda:meta><mda:meta type=\"ERROR_INVALID_HTML\">Invalid HTML fragment: ERROR: StartTag at (r1,c5,p4) missing required end tag\n</mda:meta></mda:metaGroup></mda:metadata><notes><note>this is a test</note></notes><segment id=\"s1\"><source xml:space=\"preserve\">Bad &lt;span <mrk id=\"1\" type=\"caits:regex-no-translate\" translate=\"no\">class-123&gt;HTML</mrk></source></segment></unit>", "sourceIssues": [ { "type": "ERROR_INVALID_HTML", "message": "Invalid HTML fragment: ERROR: StartTag at (r1,c5,p4) missing required end tag\n" } ] } } }

delete (delete-bundle)

Deletes a bundle. The following example deletes a bundle MyBundle from your service instance.

java -jar gp-cli.jar delete -b MyBundle -j mycreds.json

copy (copy-bundle)

Creates a copy of the specified bundle. This command allows you to duplicates a bundle in the same service instance, or another service instance. The following example copies the contents of exiting bundle MyBundle to a new bundle MyNewBundle in the same service instance.

java -jar gp-cli.jar copy -b MyBundle -d MyNewBundle -j mycreds.json

This command can be used to duplicate a bundle from a service instance to another service instance. In this case, you need to specify the destination instance's credentials with --dest-* options as below.

java -jar gp-cli.jar copy -b MyBundle -d MyBundle --dest-url https://api.pipeline.g11n.ibm.com/translate/rest --dest-instance-id 9146abf71bb94513504a0eaf76d57804 --dest-user-id 52858e19ae57ba6f2d2ea7e38e9ab457 --dest-password o75YXQCK2obQLOvedkSslBTAyeUq7/+t -j mycreds.json

If you need to copy multiple bundles (but not all), consider using the bulk copy arguments. -bl denotes your source bundle IDs, and -dbl denotes your destination bundle IDs. These arguments should point to some file with several bundle IDs on each line. The source and destination ID will be matched by line number. java -jar gp-cli.jar copy -bl sourceBundles.lst -dbl destBundles.lst --dest-url https://api.pipeline.g11n.ibm.com/translate/rest --dest-instance-id 9146abf71bb94513504a0eaf76d57804 --dest-user-id 52858e19ae57ba6f2d2ea7e38e9ab457 --dest-password o75YXQCK2obQLOvedkSslBTAyeUq7/+t -j mycreds.json

Note: This command does not copy service managed properties, such as updatedBy and updatedAt stored in each entity. The newly copied bundle and resource entries will have new timestamp in updatedAt property and the operator of this command will be set to updatedBy property.

copy-all-bundles

Copies all bundles from a service instance to another. This command invokes copy (copy-bundle) operation for all bundles in the specified service instance. This command is convenient for moving all bundle data to a newly created instance. The following example copies all bundles in the service instance to another instance specified by --dest-instance-id.

java -jar gp-cli.jar copy-all-bundles --dest-url https://api.pipeline.g11n.ibm.com/translate/rest --dest-instance-id 9146abf71bb94513504a0eaf76d57804 --dest-user-id 52858e19ae57ba6f2d2ea7e38e9ab457 --dest-password o75YXQCK2obQLOvedkSslBTAyeUq7/+t -j mycreds.json

Note: This command copies bundle data to the destination service instance, but user accounts and translation configurations are not transferred, because they are service instance specific.

update-res-entry (Previously mark)

Updates various fields for a given resource entry (strings). This command can be useful when the user needs to update the status of strings in the bundle, but does not need to import new strings. It requires a specific bundle (-b) and a specific language (-l) to be selected for each command run.

There are three ways to select which resource entry keys can be selected for marking:

  1. Use the -A option to select all keys in the bundle.
  2. Use the -k keyExp option to use a regular expression to select keys. All keys in the bundle that match the regular expression will be selected for marking.
  3. Use the -kl keyListFile option to specify a file containing a list of the keys ( one per line ) that will be marked.

Resource entries can be updated in the following ways:

There is also a feature -d (--dry-run) that allows you to see which strings would be marked, but does not actually mark them. This can be useful if you want to make sure that the proper strings have been selected for marking.

Example: If the bundle test1 has keys "blue,red,green,yellow,white", to mark the strings with keys "blue", "green", and "red" as unreviewed in German, run:

java -jar gp-cli.jar update-res-entry -b test1 -l de -k "(blue|red|green)" -R -j mycreds.json

Example: If the bundle test1 has keys "blue,red,green,yellow,white", to add two attachments (attachment01 and attachment02) to the strings with keys "blue", "green", and "red" in English, run:

java -jar gp-cli.jar update-res-entry -b test1 -l en -k "(blue|red|green)" -a attachment01,attachment02 -j mycreds.json

Example: If the bundle test1 has a key "blue", that needs a translation correction in Italian, run:

java -jar gp-cli.jar update-res-entry -b test1 -l it -k blue -tv "Ciao mondo!" -j mycreds.json

The command output would look like this:

Matching keys based on key expression: (blue|red|green) Preparing to update key 'blue' in bundle 'test1' for language 'de' Preparing to update key 'green' in bundle 'test1' for language 'de' Preparing to update key 'red' in bundle 'test1' for language 'de' Successfully updated 3 string(s) for bundle ['test1'] in language ['de']

update-res-entry-status

This command can help user import defect csv to change the resource entry status to verified=false or import readiness check csv to change the resource entry status to verified=true. Before this, user can update column "Selected?" to Y/N in defect or readiness check csv if user wants to select or not.

java -jar gp-cli.jar update-res-entry-status --defectReport defect.csv -j mycreds.json

java -jar gp-cli.jar update-res-entry-status --readinessCheckReport readiness.csv -j mycreds.json

sync-res-entries

This command can be used for inheriting translation and status of resource string in a new bundle from another bundle. For example, when multiple bundles in previous product release are meged into one, you may need to carry over these strings in a new bundle. This command scans each resource entry in the specified bundle and looks up a resource entry with the same source language (typically, English) value in the source bundle. When a math is found, update translation and status of the resource entry in the specified bundle.

Example below will synchronize translation and status of resource entries in MyBundle with another bundle MyOldBundle.

java -jar gp-cli.jar sync-res-entries -b MyBundle --source-bundle MyOldBundle -j mycreds.json

When the source bundle is in another GP service instance, you need to provide service credentials below.

File Commands

list-files

Prints out a list of file IDs available in the service instance.

java -jar gp-cli.jar list-files -j mycreds.json

Below is an example output

["MyFile1", "MyFile2"]

show-file

Prints out a file's summary information. Optionally, you can use the -m flag to also print summary information about translation/review/verify status of the file by language. The following example shows the information of file MyFile1.

java -jar gp-cli.jar show-file -f MyFile1 -m -j mycreds.json

Below is an example output.

{ "sourceLanguage": "en", "targetLanguages": [ "de", "fr", "it", "ja" ], "contentType": "text/markdown", "readOnly": false, "updatedBy": "(dash+emmo123)8092f080", "updatedAt": "2021-09-16T11:34:22.102-05", "translationStatusByLanguage": { "de": "TRANSLATED", "en": "SOURCE_LANGUAGE", "fr": "TRANSLATED", "it": "TRANSLATED", "ja": "TRANSLATED" }, "reviewStatusByLanguage": { "de": false, "fr": false, "it": false, "ja": false }, "verifyStatusByLanguage": { "de": false, "fr": false, "it": false, "ja": false } }

create-file

Creates a new file. This command creates an empty file with specified file ID and languages.

Use the -f flag to specify the name of the file to be created.

You must specify the MIME content type of the file using the -t flag.

For example, for HTML files, use the option -t text/html or for markdown files, use -t text/markdown.

Optionally you can specify a content flavor using the -v option. Content flavors are used to specify different file type variations that may use the same MIME content type. Do not use the -v flag unless necessary to specify the desired file type ( see the table below ).

The following table summarizes the currently supported file types:

File Type MIME type (-t) Flavor (-v) Machine Translation Supported
DITA application/dita+xml none yes
DITA map application/dita+xml ditamap yes
JSON application/json none yes
MS Word (doc) application/msword none no
Adobe Portable Document Format application/pdf none no
Adobe Illustrator application/pdf ai no
Rich Text application/rtf none no
MS Excel (xls) application/vnd.ms-excel none no
MS PowerPoint (ppt) application/vnd.ms-powerpoint none no
OpenDocument presentation document application/vnd.oasis.opendocument.presentation none no
OpenDocument spreadsheet document application/vnd.oasis.opendocument.spreadsheet none no
OpenDocument text document application/vnd.oasis.opendocument.text none no
MS PowerPoint (pptx) application/vnd.openxmlformats-officedocument.presentationml.presentation none yes
MS Excel (xlsx) application/vnd.openxmlformats-officedocument.spreadsheetml.sheet none yes
MS Word (docx) application/vnd.openxmlformats-officedocument.wordprocessingml.document none yes
XLIFF 2 application/xliff+xml none yes
XML application/xml none yes
Windows resource (resx) application/xml resx yes
Scalable Vector Graphics image/svg+xml none yes
Photoshop Document image/vnd.adobe.photoshop none no
HTML text/html none yes
Markdown text/markdown none yes
Plain text text/plain none yes

The following example creates a new markdown file with ID MyNewFile with English(en) as source language, and French(fr) and German(de) as target languages. The first language specified in -l option is the source language, and the rest of languages are the translation target languages.

java -jar gp-cli.jar create-file -f MyNewFile -t text/markdown -l en,fr,de -j mycreds.json

update-file

Updates an existing file's configuration.

The following example sets French (fr), German (de) and Italian (it) as target languages and the translation instruction note "This file is really important".

java -jar gp-cli.jar update-file -f MyFile -l fr,de,it -n "This file is really important" -j mycreds.json

import-file

Imports content to a file. This command takes an input language (-l). If the language does not exist in the file, the language will be automatically added to the file's configuration.

Use the -F flag to indicate the path name of the file on your system that will be imported. The file should match the type/flavor that was indicated (using the -t and/or -v flags) when the file object was created.

When importing target language content to a file, you can also use the following flags to indicate the status of the target language content.

As one would expect, you can't use -r and -R at the same time, nor can you use -v and -V at the same time.

When importing source language content (usually English) to a file, GP will automatically initiate machine translation (if available for the given file type) for all languages specified in the file configuration.

For example, the followng example imports an English (en) HTML file named MyFile.html to the file MyFile.

java -jar gp-cli.jar import-file -f MyFile -l en -F MyFile.html -j mycreds.json

export-file

Exports the contents of a GP file to your system.

Use the -F flag to indicate the path name where the file will downloaded to your system.

For example, the following example exports a French (fr) HTML file named MyHtmlFile to a file named MyFile-fr.html on your system

java -jar gp-cli.jar export-file -f MyHtmlFile -l fr -F MyFile-fr.html -j mycreds.json

delete-file

Deletes a file, including all source and target languages. The following example deletes a file MyFile from your service instance.

java -jar gp-cli.jar delete-file -f MyFile -j mycreds.json

Bulk create, delete and update

You may also supply the -bl (for bundles) or -fl (for files) parameter, which points to a list of bundle/file IDs. This allows for bulk creation, deletion and updates. Here's a sample of the ID list file, each bundle/file ID should be on a different line: com.ibm.bundle.tools.messages com.ibm.bundle.client.messages com.ibm.bundle.server.messages

User Commands

list-users

Prints out a list of users in the service instance. java -jar gp-cli.jar list-users -j mycreds.json

create-user

Creates a new user in the service instance.

The example below creates a new user account with read-only access to the bundles MyAppsBundle1 and MyAppsBundle2. java -jar gp-cli.jar create-user -t READER -b MyAppsBundle1,MyAppsBundle2 -j mycreds.json The output of above command looks like below. A new user was successfully created. User ID: 9b8b65c31cf56a8eac2bd4a1a1f09175 User password: IpBiOP0s4xXs3SRSgofYLLasU6/qEWFf Note: The password above cannot be retrieved from the service later. If you lost the password, you can only reset the password by reset-user-password command below.

The command option -t specifies a type of new user. There are following user types. * ADMINISTRATOR - Administrator of the service instance. * TRANSLATOR - Can read bundles and edit tranlations. This account type is designed for external tooling for translators. * READER - Can only read basic information of bundles and resource strings. This account type is designed for distributing credentials included in a client application accessing the translated strings dynamically.

reset-user-password

Resets a user's password. The example below resets the password of the user whose ID is 9b8b65c31cf56a8eac2bd4a1a1f09175. java -jar gp-cli.jar reset-user-password -d 9b8b65c31cf56a8eac2bd4a1a1f09175 -j mycreds.json The out of above command looks like below. New password: CD0ZPBvOoTCZbDCDssY/sMEjmTvW+rYs

delete-user

Deletes a user. The example below delets the user whose ID is 9b8b65c31cf56a8eac2bd4a1a1f09175. java -jar gp-cli.jar delete-user -d 9b8b65c31cf56a8eac2bd4a1a1f09175 -j mycreds.json

Translation Request Commands

submit-tr

Submits a set of bundles/files for human translation.

There are 3 ways to set a list of bundle IDs. - Save a list of bundle IDs you want to include a text file. Each line should specify a single bundle ID. You can pass the list to the tool by -B option. - Specify a list of bundle IDs delimited by comma using -b option. - Don't specify bundle ID option, which automatically includes all available bundle IDs.

There are 3 ways to set a list of file IDs. - Save a list of file IDs you want to include a text file. Each line should specify a single file ID. You can pass the list to the tool by -F option. - Specify a list of file IDs delimited by comma using -f option. - Don't specify file ID option, which automatically includes all available file IDs.

To exclude all the bundles (TR for just files), please add a flag `-xb` or `--noBundles`.
To exclude all the files (TR for just bundles), please add a flag `-xf` or `--noFiles`.

There are 2 ways to set a list of target languages. - Specify a list of target languages delimited by comma using -l option. - Otherwise, include all target languages available in each bundle.

There are 2 ways to add translation notes of target languages. - Specify a list of target languages delimited by comma using --translationNotesLanguage option and specify translation notes using --translationNotes option. Default to all language if not specified. - Specify a JSON file of translation notes for each languages using -tn option. Set "language id" to "*" means the notes applies to all languages. If you want to specify translator notes to specific language, you need to add "language id":"translator notes content" in json format. Take the following JSON format as an example. It specify the translation notes for Germany, French and notes for all languages.

{ "de": "Notes for Germany", "*": "notice all the translators.", "fr": "Notes for French" }

Additional flags and options: - -d to mark a translation request as a draft. - -n to specify translation request name. This is required. - -r to indicate a profile other than the default translation profile - -e to specify any additional e-mail addresses to be notified about status changes for the TR. - -P to specify the priority level (requested return time) for the TR. Priorities are defined as an integer value from 1 to 10 inclusive, with 1 being the lowest and 10 being the highest priority. The default priority is 5. - --notes to specify translation notes for a job. Notes for human translation job might be used for explaining special instructions or references to project managers in the human translation vendor. Use '--translationNotes' option instead if you want to send notes to translators...

To submit a verification test TR (also known as a TVT TR): - -v to specify that this translation request is for a verification test TR. Returned strings will have the verified flag set to "true" when merged. - -vj to specify the verification test job id (required) This is the translation job ID associated with a TVT project managed through WEP. - -vp to specify the verification test pass id (required)

TVT is only supported for bundles Examples:

Submitting a new TR including all bundles IDs and file IDs and all target languages.

java -jar gp-cli.jar submit-tr -n "My first shipment" -j mycreds.json

Submitting a new TR including bundle IDs specified by file bundle.lst for French and German and no file IDs, using the highest possible priority.

java -jar gp-cli.jar submit-tr -n "My second shipment" -B bundle.lst -l fr,de --noFiles -P 10 -j mycreds.json

list-trs

Prints out a summary list of human translation requests that exist in the service instance. For each TR, the following information is provided: - Translation request ID - Translation request name - Overall status of the translation request ( SUBMITTED, CANCELLED, MERGED, etc. ) - Date and time of the last relevant status update.

Example:

``` java -jar gp-cli.jar list-trs -j mycreds.json

0c4480b81a7bf267d1e875f29353931b : test1217b_ja1 : STARTED Dec 17, 2021, 12:07:03 PM 0c4480b81a7bf267d1e875f2935d8a12 : test1217d_ja1 : MERGED Dec 17, 2021, 12:30:09 PM 9d9f3c44ae43f4eb3288b20971789727 : test0303all : PARTIALLY_MERGED Mar 3, 2022, 12:27:04 PM a2d29921e66eaadde727538620ec15e4 : test0307all : MERGED Mar 7, 2022, 11:03:16 AM b8121888e5e3e8bf32cf4c2525addca7 : test-fr-1 : MERGED Feb 25, 2022, 11:41:11 AM bf420da7e72ebdc8b7ad6c0ac83d83f0 : test0303 : MERGED Mar 3, 2022, 12:21:41 PM c0bc0590dc824a86ff734336b6153d7d : test tr : MERGED Mar 15, 2022, 2:54:42 PM c79fbb05a01b4911730d84b5281908b1 : test1216 : STARTED Dec 16, 2021, 3:07:41 PM c79fbb05a01b4911730d84b52831cc13 : test1216_ja2 : STARTED Dec 16, 2021, 3:44:04 PM de0b406e1d4b9cc3b43535593cafc6f6 : test-2a : MERGED Aug 18, 2021, 5:03:50 PM eb97ddb6e6e6eab014c997c87336c7e7 : test0307all : MERGED Mar 7, 2022, 11:06:54 AM f399eae87a24ed08d7d64416f2119bdf : testc : CANCELLED Mar 9, 2022, 11:26:23 AM ```

show-tr

Prints out a detailed information about the status of a human translation request. For each TR, the following information is provided: - Translation request ID - Translation request name - Overall status of the translation request ( SUBMITTED, CANCELLED, MERGED, etc. ) - Date and time of the last relevant status update. - For each file/bundle in the TR, detailed information about which languages are included, the CAITS job ID that was used to process the request, its status, such as MERGED or STUCK or IN_PROGRESS, and the TJ number.

Example:

``` java -jar gp-cli.jar show-tr -t 9d9f3c44ae43f4eb3288b20971789727 -j mycreds.json

{ "id": "9d9f3c44ae43f4eb3288b20971789727", "name": "test0303all", "requestType": "REGULAR_TRANSLATION", "status": "PARTIALLY_MERGED", "updatedAt": "2022-03-03T12:27:04", "jobStatusByBundleTargetLanguage": { "test1": { "nb": { "jobId": "emmo123_20220303T182613-4", "jobStatus": "MERGED", "tjNumber": "TJ275868" }, "sv": { "jobId": "emmo123_20220303T182613-5", "jobStatus": "IN_PROGRESS", "tjNumber": "TJ773840" }, "zh-Hant": { "jobId": "emmo123_20220303T182613-7", "jobStatus": "MERGED", "tjNumber": "TJ232364" } } }, "jobStatusByFileTargetLanguage": { "test1112": { "es": { "jobId": "emmo123_20220303T182612-2", "jobStatus": "STUCK", "tjNumber": "TJ801415" }, "fr": { "jobId": "emmo123_20220303T182613-6", "jobStatus": "MERGED", "tjNumber": "TJ101784" } } } } ```

delete-tr

Deletes a translation request. The following example deletes a TR from your service instance.

java -jar gp-cli.jar delete-tr -t 9d9f3c44ae43f4eb3288b20971789727 -j mycreds.json

export-tr-attachments

Export TR attachments as a zip file.

Options:

java -jar gp-cli.jar export-tr-attachment -t 9d9f3c44ae43f4eb3288b20971789727 -o test.zip -j mycreds.json

ICT Translation Request Commands

ICT Workflow

ICT (In context testing) is an automated workflow that allows the translation testers to test the quality of their translations by using the associated attachments ( in both English and translated languages ) to validate the product. To use the ICT features, a special type of TR is submitted for this purpose, called simply an ICT TR. Using an ICT TR has the following process.

  1. The user creates an ICT TR for those translations that need to be validated. Strings should be in the "reviewed" but not "verified" state. An ICT TR is always created in the DRAFT state, and is not immediately submitted. ( create-ict-tr command )
  2. The user then triggers an "ICT Readiness Check" operation, ( check-ict-tr command ), that determines whether the ICT TR is ready to be submitted. The readiness check verifies that all strings in the TR have associated screenshots (i.e. "attachments" ), in both the source and target languages. Additional checks may be added in the future. If there are any errors in the check, the TR is marked as BLOCKED and the readiness check report can be viewed in order to correct any issues that were found. ( export-ict-readiness-report command )
  3. If the readiness check is successful, the TR will be marked as READY and can then be submitted for testing ( submit-ict-tr command ) .

create-ict-tr

Creates in ICT translation request. ICT translation requests always start in the DRAFT state until readiness check is successfully completed.

The options and parameters for create-ict-tr are the same as those for submit-tr that is used for regular translation requests, with the following additions:

Parameters associated with the older TVT process, such as -v, -vj, and -vt are not allowed in an ICT TR.

list-issue-tracking-ids

Lists the issue tracking IDs associated with the current service instance.

java -jar gp-cli.jar list-issue-tracking-ids -j mycreds.json

check-ict-tr

Triggers an ICT TR readiness ( that is performed in the background ) on an ICT TR. For an ICT TR, the readiness status is shown in the output when the show-tr command is used. In order for readiness check to be successful, certain criteria must be met, such as all strings having an associated attachment ( screenshot ) in both the source and target languages, so that the tester can verify the product in context.

java -jar gp-cli.jar check-ict-tr -t 9d9f3c44ae43f4eb3288b20971789727 -j mycreds.json

Options:

export-ict-readiness-report

Exports issues from the readiness report into a CSV file that can be used for issue tracking.

Options:

Example:

java -jar gp-cli.jar export-ict-readiness-report -t 555f267f4f08eba96b0b994e2dbc202f -o "report.csv" -j mycreds.json

Might produce a report in the following format:

level,bundleId,resourceKey,language,attachmentId,messageCode,message ERROR,,,fr,test2.png,SCR0003,There is no screenshot image uploaded for target language for this attachment.

submit-ict-tr

Submits an ICT TR for testing once the readiness status is successful.

java -jar gp-cli.jar submit-ict-tr -t 9d9f3c44ae43f4eb3288b20971789727 -j mycreds.json

export-defects

Export ICT defect information associated with a particular issue tracking ID.

Options:

There are two possible report formats:

Attachment commands

bulk operations

For all commands, you may also specify -al in place of -a. The usage is as follows:

create-attachment

Creates an attachment object in your instance.

Options:

The following example creates a normal image/jpg attachment with id attachment01:

java -jar gp-cli.jar create-attachment -a attachment01 -t image/jpg -d "some description of the attachment" -j creds.json

You may also create an external reference attachment (-e) with this command like so, NOTE content type is not required for external attachments:

java -jar gp-cli.jar create-attachment -a attachment02 -e -j creds.json

list-attachments

Lists the attachment objects in your instance.

Options:

java -jar gp-cli.jar list-attachments -G tag1,tag2 -S Completed,InProgress -j creds.json

show-attachment

Gives detailed information about a specific attachment objects in your instance, such as the attachment content type, or which languages have downloaded content.

Options:

java -jar gp-cli.jar show-attachment -a attachment01 -j creds.json

Gives detailed information about a specific tags of attachments:

java -jar gp-cli.jar show-attachment -G tag1 -j creds.json

import-attachment

Imports attachment content or a link to the attachment into an attachment object. The command for content is like so:

java -jar gp-cli.jar import-attachment -a attachment01 -F path/to/source/image.jpg -l en -j creds.json

For an external reference you need to set the URL that points to the external reference.

java -jar gp-cli.jar import-attachment -a attachment01 -ln https://it.docs.ibm.com/myreference.html -l it -j creds.json

export-attachment

Exports (downloads) attachment content the attachment into a file.

Options:

Example for downloading the attachment content in Spanish for attachment01:

java -jar gp-cli.jar export-attachment -a attachment01 -F path/to/spanish/image.jpg -l es -j creds.json

update-attachment

Update allows you to update your attachment object. Currently, only the description and attachmentTags can be modified.

Options: - -a <attachmentID> The attachment ID to update. - -al <attachmentList> See the "bulk operations" section above. - -d <description> Brief description of the attachment. - -g <attachmentTags> Specify a comma separated list of tags for grouping this attachment.

java -jar gp-cli.jar udpate-attachment -a attachment01 -d "some new description" -j creds.json

delete-attachment

Deletes an attachment

Options: - -a <attachmentID> The attachment ID to delete. - -al <attachmentList> See the "bulk operations" section above. - -G Specify the tag to filter attachments to perform the given operation. Provide an empty string ("") to filter by attachments with no tags.

java -jar gp-cli.jar delete-attachment -a attachment01 -j creds.json

Other Commands

list-mt-languages

Prints out machince translation languages currently enabled in the service instance. For example, the following example prints out an array of machine translation target languages from English (en).

java -jar gp-cli.jar list-mt-languages -f en -j mycreds.json

The output of above command looks like below.

["de","es","fr","it","ja","ko","pt","zh-Hans","zh-Hant"]

How-To

Import Existing Bundle Translations

You may already have resource bundles translated from English to several different languages. If you want to import the already translated contents to a Globalization Pipeline service bundle, then you can follow the steps below.

  1. Create a new bundle with English as the source language. In this example, we use com.ibm.example.MyBundle as the bundle ID.

java -jar gp-cli.jar create -b com.ibm.example.MyBundle -l en -j mycreds.json

  1. Import the English(en) resource bundle contents to MyBundle. The resource bundle file in this example is a Java properties file - MyBundle.properties

java -jar gp-cli.jar import -b com.ibm.example.MyBundle -l en -t JAVA -f MyBundle.properties -j mycreds.json At this point, the bundle com.ibm.example.MyBundle in the Globalization Pipeline service instance contains only English resource strings.

  1. Import the corresponding translated version. In this example, the operation below imports French(fr) translation from MyBundle_fr.properties and marks resource strings as already reviewed (-r).

java -jar gp-cli.jar import -b com.ibm.example.MyBundle -l fr -t JAVA -f MyBundle_fr.properties -j mycreds.json -r

This operation automatically adds French to the bundle com.ibm.example.MyBundle.

  1. Repeat step 3 above for other translated versions.

Import Existing File Translations

A similar process can be followed for files as for bundles above.

  1. Create a new file with English as the source language using create-file
  2. Import the English file content to the file using import-file. At this point, the file contains only English, and no machine translation will occur.
  3. Import the corresponding translation using import-file. The target language you specify will be added to the file's configuration, and no machine translation will occur.

If you subsequently change the contents of the English file, then machine translation of the file content will occur for all languages that have been previously imported.

Associate Attachments with Bundles or Files

To associate an attachment with a bundle or file, you can specify the -a or -al command during a bundle/file create or update. - -a is a string of attachment ids separated by commas. e.g. -a attachment01,attachment02,attachment03. - -al is a the path to a file with one attachment id per line. e.g. -al ~/path/to/attachmentIdsList.txt. This command is meant for providing a large number of attachments that will not fit well on the commandline