This is a Java client SDK for Globalization Pipeline. This SDK provides Java APIs for accessing Globalization Pipeline's REST endpoints.
Globalization Pipeline provides REST APIs for creating translation bundles, fetching translated strings, managing user accounts used for accessing the service and various other operations. This SDK provides Java APIs for these REST endpoints, so you can develop Java applciation managing end to end translation process.
This library requires Java 8 or later version of Java Runtime Environment.
Globalization Pipeline SDK binaries are published in Straker Maven repository. For setting up the repository access, please see this document.
The information about the latest SDK release is found in this document.
Instead of using environment vars, you may also choose to get your credentials from a JSON file. An example of this is shown below, with the GSON parser.
```java import java.io.FileInputStream; import java.io.IOException; import java.io.InputStreamReader; import java.nio.charset.StandardCharsets; import com.google.gson.Gson; import com.ibm.g11n.pipeline.client.ServiceAccount; import com.ibm.g11n.pipeline.client.ServiceClient;
public class getClientExample {
static class JsonCredentials {
String url;
String instanceId;
String userId;
String password;
}
public ServiceClient getClientFromJSONCredentials(String jsonCredsFile) {
JsonCredentials creds;
try (InputStreamReader reader = new InputStreamReader(
new FileInputStream(jsonCredsFile), StandardCharsets.UTF_8)) {
Gson gson = new Gson();
creds = gson.fromJson(reader, JsonCredentials.class);
} catch (IOException e) {
throw new RuntimeException(e);
}
gpUrl = creds.url;
instanceId = creds.instanceId;
userId = creds.userId;
password = creds.password;
ServiceAccount account = ServiceAccount.getInstance(
gpUrl, instanceId, userId, password);
return ServiceClient.getInstance(account);
}
} ```
Once you have your service client set up, you can perform an action on your gp instance. For example you can list your available bundles. ```java public class gpInstanceUsageExample {
private ServiceClient client = getClientFromJSONCredentials("/path/to/credentials.json");
public void printAllBundles() {
Set<String> bundleIds = client.getBundleIds();
for (String id : bundleIds) {
System.out.println(id);
}
}
} ```
Here's an example of finding which keys in all bundles have not yet been translated, for a specific language. In this case, we're using Italian. ```java public class gpInstanceUsageExample { private ServiceClient client = getClientFromJSONCredentials("/path/to/credentials.json");
public void getUntranslatedKeys() {
String language = "it";
Set<String> bundleIds = client.getBundleIds();
Map<String, ResourceEntryData> resourceEntries;
for (String id : bundleIds) {
resourceEntries = client.getResourceEntries(id, language);
for (Entry<String, ResourceEntryData> entry : resourceEntries.entrySet()) {
String key = entry.getKey();
ResourceEntryData resEntry = entry.getValue();
// If we find an untranslatable value, treat this as "done"
boolean resourceTranslated = !resEntry.isUntranslated() ||
(resEntry.getTranslationStatus() == TranslationStatus.TRANSLATED);
System.out.printf("Resource entry %s translated to [%s]: %s%n",
key, language, resourceTranslated);
}
}
}
} ```
In this example, we'll be modifying resource entries. Specifically, we'll unset the reviewed flag from any resource entries, including a word "IBM". ```java public class gpInstanceUsageExample { private ServiceClient client = getClientFromJSONCredentials("/path/to/credentials.json");
public void unsetReviewed() {
String language = "it";
Set<String> bundleIds = client.getBundleIds();
Map<String, ResourceEntryData> resourceEntries;
for (String id : bundleIds) {
resourceEntries = client.getResourceEntries(id, language);
for (Entry<String, ResourceEntryData> entry : resourceEntries.entrySet()) {
String key = entry.getKey();
ResourceEntryData resEntry = entry.getValue();
if (resEntry.getSourceValue().contains("IBM") || resEntry.getValue().contains("IBM")) {
ResourceEntryDataChangeSet changeSet = new ResourceEntryDataChangeSet();
changeSet.setReviewed(false);
client.updateResourceEntryData(id, language, key, changeSet);
}
}
}
}
} ``` This example shows updating individual entries, you can also update in bulk. In order to do this, you would need to build a map like so Map<String, ResourceEntryDataChangeSet> and use SeviceClient#updateResourceEntries().
In order to update a field on a bundle object for example, you must specify which field you'd like to be changed. Otherwise, the field will not be modified. In order to delete the value, you must specify an empty object "".
For example this operation will update ONLY the codePattern of the bundle: java BundleDataChangeSet changes = new BundleDataChangeSet(); changes.setCodePattern("foobar"); client.updateBundleData("someBundleId", changes);
This operation will DELETE all notes in the bundle: java BundleDataChangeSet changes = new BundleDataChangeSet(); changes.setNotes(Collecitons.emptyList()); client.updateBundleData("someBundleId", changes);
In a Java applications, localized UI strings are usually stored in Java resource bundle class files or in Java properties files. These localized strings are accessed through java.util.ResourceBundle class. The ResourceBundle class provides a way to support custom resource bundle formats by specifying a custom instance of ResourceBundle.Control. This SDK contains an implementation of ResourceBundle.Control which looks up and load resource strings from an instance of Globalization Pipeline service.
Once a new bundle is created, and the contents in the source language is uploaded, your Java application can use the translated results through Java's standard ResourceBundle class.
Your original code may look like below:
...
Locale locale; // the target language
...
ResourceBundle rb = ResourceBundle.getBundle("com.ibm.app.MyMessages", locale);
String msg = rb.getString("msg1");
If your application is running on JRE 8 or you want to limit the use of Globalization Pipeline service to specific bundles, then you can use the custom ResourceBundle.Control implementation included in this SDK.
If the application is running on Cloud, the source code should be changed to:
import com.ibm.g11n.pipeline.client.rb.CloudResourceBundleControl;
...
Locale locale; // the target language
...
// ResourceBundle is created with the custom control
ResourceBundle rb = ResourceBundle.getBundle("com.ibm.app.MyMessages", locale,
CloudResourceBundleControl.getInstance());
String msg = rb.getString("msg1");
With the code above, your application will retrieve a translated resource string from your translation bundle stored in the Globalization Pipeline service instance. If the specified language (Locale) is not available in the translation bundle, the custom control will automatically fallback to local resources (.class or .properties included in your application).
When the application is not running on Cloud, you need to supply credentials manually to create the custom control, instead of calling the no-arg factory method CloudResourceBundleControl.getInstance(). For example,
import com.ibm.g11n.pipeline.client.ServiceAccount;
import com.ibm.g11n.pipeline.client.rb.CloudResourceBundleControl;
...
Locale locale; // the target language
...
ServiceAccount account = ServiceAccount.getInstance(
"https://g11n-pipeline-api.straker.global/translate/rest", // service URL
"my-gp-instance", // instance ID
"e92a1282a0e4f97bec93aa9f56fdb838", // user ID
"zg5SlD+ftXYRIZDblLgEA/ILkkCNqE1y"); // user password
// ResourceBundle is created with the custom control
ResourceBundle rb = ResourceBundle.getBundle("com.ibm.app.MyMessages", locale,
CloudResourceBundleControl.getInstance(account));
String msg = rb.getString("msg1");
This SDK implements ResourceBundelControlProvider introduced in Java 8. With the provider implementation, you can retrieve translated resource strings stored in a Globalization Pipeline project without any code changes.
To enable this feature, you can put the SDK jar file(s) into Java's extension directory. The SDK is distributed in two different formats - gp-java-client-X.X.X.jar and gp-java-client-X.X.X-jar-with-dependencies.jar. If you use the one wihout dependencies, you also need to put the dependencies (for now, Gson and Guava) in the same directory.
If the application is running on Cloud, then what you need is to package the SDK jar file (and the dependencies) in your application to the JRE overlay directory corresponding to the JRE's extension directory 'resources/.java-overlay/.java/jre/lib/ext'.
If the application is not running on Cloud, then you need to supply credentials used for accessing the Globalization Pipeline service instance.
Irrespective of which you choose the following common credentials can be specified by following environment variables:
The Globalization Service Authentication specific credentials can be specified by following environment variables:
Please also refer Java Tutorials article Installing a Custom Resource Bundle as an Extension about the service provider interface and configuration in general.