Configuration and Operation
The CLAIRE translation service integration offers real-time translation flows to easily translate textual attributes and product descriptions into different target languages of your choice.
Installation
Extract the Claire accelerator zip
Unpack the file PIM_<Version>_Accelerators.zip to a temporary folder on the Product 360 environment. The folder PIM_<Version>_CLAIRE contains the following artifacts:
PIM_<Version>_Rev-xxxxx_client_ai.delta.zip
contains the PIM Desktop UI features and plugins (not needed for the translation feature specifically)
PIM_<Version>_Rev-xxxxx_resources_ai.delta.zip
contains export templates, flex UI template examples and the ai server (not needed for the translation feature specifically)
PIM_<Version>_Rev-xxxxx_server_ai.delta.zip
contains the feature and plugins to be put into the Product 360 server for translation API integration setups.
Installation of the Claire translation service
Unpack the PIM_<Version>_Rev-xxxxx_server_ai.delta.zip. The relevant plugins for the translation service are the following:
com.heiler.ppm.ai.server_1.0.0.<Revision>.jar
com.heiler.ppm.ai.translation.server.i18n_1.0.0.<Revision>.jar
com.heiler.ppm.ai.translation.server_1.0.0.<Revision>.jar
com.heiler.ppm.web.ai.translation_1.0.0.<Revision>.jar
com.heiler.ppm.web.ai_1.0.0.<Revision>.jar
We recommend to add all features into the folder ./server/features and all plugins in the folder ./server/plugins into your server environments. The translation service does not require any client plugins.
Configuration of Claire Translation Service
Option 1: Use the standard translation service configuration using Google Translate API
By default, and if no other translation service is contributed, the standard implementation uses Google Translate API.
When using the default translator, the setting used in the claire.properties file which is located in the conf folder of the Product 360 Server should be the following:
claire.translation.custom.used = falseGoogle Translate API setup
To use the Google Translate API, you must create an account and a project within Google Cloud Platform, enable billing and enable the Google Translate API for your Google Cloud project. Once this is done, you need to set up authentication and generate a Google Translate API key. The key will be used to configure Product 360 to run with Google Translate API.
The outlined setup steps are the following:
Create a Google Cloud Platform (GCP) account
Add your user account to your company's Google Cloud Project
Enable billing for your account
Enable the Cloud Translation API for your project
Generate an API Key to access the Google Translate API
More details about the setup process of Google Translate API can be found here https://cloud.google.com/translate/docs/setup.
Google Translate API key usage
To access the Google Translate API from Product 360, a corresponding API key is needed. API keys are useful for accessing public data anonymously and are used to associate API requests with your project for quota and billing.
Informatica MDM - Product 360 considers a "bring your own key" setup for the translation services providing full transparency and no extra charges from our end to make use of the capabilities.
Creating an API Key
You can use the Google Cloud Console to create and manage API keys. To create an API key:
Navigate to the APIs & Services→Credentials panel in the Cloud Console
At the top of the Credentials page, select Create credentials , then select API key from the dropdown menu
The API key created dialog box displays your newly created key.
Always ensure that API keys are kept secure during both storage and transmission.
Securing an API Key
API keys are unrestricted by default. Unrestricted keys can be used by anyone from anywhere. That's why it's highly recommended to set up application and API key restrictions. By adding restrictions, you can reduce the impact of a compromised API key.
Set application restrictions by restricting the API key to only work for calls from the IP address of the Product 360 server:
Navigate to the APIs & Services→Credentials panel in Cloud Console
Select the name of an existing API key
Under Application restrictions, select IP addresses (web servers, cron jobs, etc.) and enter the IP address of the Product 360 server
Set API restrictions and ensure that the API key can only be used for the Translation API.
In the API restrictions section, click Restrict key.
From the Dropdown menu, check Cloud Translation API
Click Save
For more details about Google Cloud API keys refer to https://cloud.google.com/docs/authentication/api-key
Using an API Key
Within the Product 360 navigate to the claire.properties file and set the value of the generated API key like the following:
claire.translation.apiKey = [_to_encrypt_]<API key value>[_to_encrypt_]We recommend to use the [_to_encrypt_] tag, to ensure that on the next restart of the Product 360 server, the API key will be encrypted and can no longer be read from the claire.properties file by others. More information about the encryption process can be found under Installation and Operation → Installation → Server Installation
When added to the claire.properties file, always keep the Claire Translation Service parameter name "claire.translation.apiKey". You may only want to remove or change the API key value.
If claire.translation.custom.used is "false" and claire.translation.apiKey is empty, the translation feature is considered to be inactive.
Option 2: Implement and contribute your own custom translation service
In case you want to create and contribute your own custom translation service API integration, set the value of claire.translation.custom.used in the claire.properties file to "true" and follow the steps below. As an addition to this documentation there is an example implementation in the SDK examples collection to get yu started, the plugin name is com.heiler.ppm.customizing.ai.server.
Using the SDK of Product 360 create a new plugin, which has dependencies to com.heiler.ppm.ai.server and com.heiler.ppm.ai.translation.server.
Create a class that implements the interface Translator.java which is located in the package com.heiler.ppm.ai.translation.server.service according to your own translation service design.
If you need settings to configure your translation service, you can store them in the claire.properties file, key encryption is also supported as described above.
Please have a look into the example implementation to learn more about the general approach and used objects.Register your translator implementation using the extension point com.heiler.ppm.ai.translation.server.translator
After restarting the Product 360 Server, it will use the contributed translator. Confirmation that your translation service has been loaded successfully can be found in the console log.
17:39:30,041 INFO [ServerInitializer 0] [STARTUP] Initialize claire translation server component17:41:32,310 INFO [ServerInitializer 0] [TranslatorRegistry] Using contributed translator for Claire Translation Panel: CustomTranslator17:41:46,354 INFO [ServerInitializer 0] [STARTUP] Initialize claire translation server component completed (Duration: 136313 ms)Configuration of Translation Flex UI
The CLAIRE panel can be integrated into any Flex UI with a component for translation. Below you see an example of how to configure a CLAIRE panel into your flex UI definition.
<group identifier="Claire info"> <layoutData> <parameter key="colSpan" value="1"/> <parameter key="rowSpan" value="1"/> </layoutData> <component i18NKey="Claire" identifier="claire full" type="claire"> <layoutData> <parameter key="collapsible" value="true"/> <parameter key="collapsed" value="false"/> </layoutData> <parameter key="context" value="translation"/> <parameter key="translationSourceFields" value="ArticleLang.DescriptionLong(en);ArticleLang.DescriptionShort(en);ArticleLang.Remarks(en);ArticleLang.Keyword(en)"/> <parameter key="translationTargetLanguages" value="es;fr;de"/> </component></group>|
Parameter name |
Description |
Valid values examples |
Default |
|
context |
The context or use case the CLAIRE panel will be used for. Only recommendations for this use case will be shown. If empty, the server will attempt to load all available CLAIRE Panels, for example classification, translation and brand extraction. |
translation |
<empty> |
|
translationSourceFields |
The source field(s) which will be used for translation. The field(s) have to be fully qualified and language-specific fields of datatype String. It is possible to setup a single field or multiple for translation within the same flex UI. When using multiple fields, separate them with semicolons. |
ArticleLang.DescriptionLong(en);ArticleLang.DescriptionShort(en);ArticleLang.Remarks(de);ArticleLang.Keyword(en) |
<empty> |
|
translationTargetLanguages |
The language(s) each of the source fields shall be translated into. When using multiple target languages, separate them with semicolons. Valid values include synonyms of any entry in the Enum.Language enumeration within the Product360 repository. |
es;fr;de |
<empty> |
You can make the example flex UI template available in Product 360 Web UI by using the Desktop UI through Management → Manage UI templates → Load UI templates from file. The example file can be found under CLAIRE_Services → Resources → Flex UI Templates. From this point onward, you can open the translation flex UI in the web UI by selecting one or multiple items and clicking on Actions → Open Flex UI → Translation with Claire (en).
Batch Translation
In order to provide the brand extraction in a batch process setup (for example after the import of data) the Claire accelerator comes with the following capabilities:
After installation and configuration of the accelerator there is a new data quality category named CLAIRE:
How to use the translation rule configuration
I t is highly recommended to clone one of the existing Translation rule configurations and then modify the input ports according to your needs. The "default" rule configuration is just a template and should not be used as is. Even if you delete this rule configuration, category or group, it will come up on next server start again.
After the data quality rule configuration has been cloned and the parameter adjusted, it can be used for triggers or direct execution just as every other data quality rule configuration to translate language specific values of product records. The parameters are mandatory and described here:
|
Parameter |
Description |
|
Source fields |
Language specific values of these fields will be translated. At least one source field needs to be configured for a successful rule execution and the selected fields must be string fields qualified with a language. Note: Only fully qualified fields are supported. Please don't select another data type for your rule configuration. |
|
Target languages |
Language(s) in which the source fields will be translated. Semicolon separated list of language identifiers (e.g. de;fr;es). Valid values include synonyms of any entry in the Enum.Language enumeration in the Product360 repository. |
|
Retain existing values |
If true, already existing values in the target language will not be overwritten and also won't be send to the translation service for translation to avoid unnecessary costs. |
In case no quality status entry is written for a product, variant or item after you triggered the execution of the rule, have a look into the process overview. There could be some reasons (like missing permissions) that might prevent the execution of a rule configuration for a product, variant or item.
Allowed value examples for target languages
|
Language |
Key synonyms |
|
German |
deu, ger, de, de_DE |
|
English |
eng, en, en_GB, en_EN, en_US |
|
Spanish |
esl, es, spa, es_ES |
|
Finnish |
fin, fi, fi_FI |
|
French |
fra, fre, fr, fr_FR |
|
Italian |
it, ita, it_IT |
|
Dutch |
dut, nl, nla, nl_NL |
|
Norwegian |
nor, no, no_NO, nb_NO, nn_NO |
|
Russian |
ru_RU, ru, rus |
|
Swedish |
sve, sv, sv_SE |
|
Portuguese (Brazil) |
por, pt_BR, por_BR, pt |
|
Japanese |
jpn, ja, ja_JP |
|
Chinese |
chi, zh, zh_CN |
|
Korean |
ko_KR, ko, kor |
Our internal tests on batch execution (based on two source fields: Long description (English) and short description (English) and 3 target languages) using real customer data have shown the following performance results:
|
Number of product records |
Duration |
|
100 |
3 seconds |
|
1,000 |
1 minute |
|
10,000 |
10 minutes 20 seconds |
The average number of characters per product record in our test data set (without counting white spaces) was 35 for the short description (English) and 926 characters for the long description (English).
Important:
Always mind the charges of the translation service provider!
Restrict access to rule configurations
You might want to ensure that not every user can execute the batch execution. You can do this by assigning the rule configurations to a channel and securing that channel with object rights which will inherit to the rule configuration.
Create a channel
Add rule configurations to channel (Double click on channel to open selection)
Set object rights
A user from an excluded user group won't see the rule configuration anymore in the 'Execute data quality rules' dialog.
Restrict number of items for DQ rule execution
In order to control budgets and cross charges with the translation service provider, it is possible to restrict the number of items that can be processed within a single DQ rule execution.
In the file claire.properties you will find the property claire.translation.dq.max.objects with a default of '100' records per batch call. This number can be adjusted to your needs.
# The used translation service may cause some costs. In order to restrict unintentional translations, here you # can limit the number of objects on which a translation dq rule is executed in one run.# An empty value means there is no restriction.claire.translation.dq.max.objects = 100If the DQ rule configuration is executed on more than 100 items, then the job will be canceled, and no translations will be done. You will find and entry in the process overview with a corresponding message.
If the property is left blank, there will be no restriction at all.
Before the check is done, all items for which the user does not have write object rights are pre-filtered. In case a user selected 105 items but is missing the write object right for 6 of them, the DQ rule configuration will be executed and the translations will be executed.
Attribute Support for Claire Translation
It is also possible to translate language dependent attribute values of datatype 'Character string' into defined target languages.
Configuration of attribute translations within a flex UI
Below is an example of a flex UI definition allowing for attribute values translation.
<group identifier="Claire info"> <layoutData> <parameter key="colSpan" value="1"/> <parameter key="rowSpan" value="1"/> </layoutData> <component i18NKey="Claire" identifier="claire full" type="claire"> <layoutData> <parameter key="collapsible" value="true"/> <parameter key="collapsed" value="false"/> </layoutData> <parameter key="context" value="translation"/> <parameter key="translationSourceFields" value="ArticleLang.DescriptionShort(en)"/> <parameter key="attributeTranslationSourceLanguage" value="en"/> <parameter key="attributeNamesInKeyLanguage" value="Size;Color"/> <parameter key="translationTargetLanguages" value="es;fr;de"/> </component></group>The additional parameters specific to attribute values translation are the following:
|
Parameter name |
Description |
Valid values examples |
Default |
|
attributeTranslationSourceLanguage |
The source language of the attributes that shall be translated. Valid values include synonyms of any entry in the Enum.Language enumeration within the Product360 repository. If no value is defined, no attribute will be displayed for translation on the UI. |
en |
<empty> |
|
attributeNamesInKeyLanguage |
The name(s) of the attribute(s) in the key language will be used for translation. If no value is defined, all existing attributes of data type 'Character string' will be displayed. When using multiple distinct attribute names, separate them with semicolons. If you want to use an attribute name that contains a semicolon, you have to escape it by '\'. Example: The attribute Length;Width;Height has to be configured as <parameter key="attributeNamesInKeyLanguage" value="Length\;Width\;Height"/> The flex UI definition is using XML syntax which means that you have to care about some special characters. Example: The attribute Length&Width has to be configured as <parameter key="attributeNamesInKeyLanguage" value="Length&Width"/> |
Size;Color |
<empty> |
The accelerator package provides a flex UI template specific for attribute translation which can be found under CLAIRE_Services → Resources → Flex UI Templates to get you started.
Excluded Attributes
If you are missing an attribute, it might be because some attributes are excluded from the translation. Check for the following:
Is the attribute of data type 'Character string'?
Are preset values available for the attribute?
The preset values have to originate from a mapping to a structure group feature in a maintenance structure. Since preset values are based on structure values, it makes sense to translate those directly instead.
Batch translation
You can use the existing translation data quality rule configuration to translate fully qualified attribute paths in batch mode. For details about the use of the translation rule configuration see the section Batch Translation from this chapter.
Characteristic Record Support for Claire Translation
It is also possible to translate language dependent characteristic record values of datatype 'Text' into defined target languages.
Configuration of characteristic record translation within a flex UI
Below is an example of a flex UI definition allowing for characteristic record values translation.
<group identifier="Claire info"> <layoutData> <parameter key="colSpan" value="1"/> <parameter key="rowSpan" value="1"/> </layoutData> <component i18NKey="Claire" identifier="claire full" type="claire"> <layoutData> <parameter key="collapsible" value="true"/> <parameter key="collapsed" value="false"/> </layoutData> <parameter key="context" value="translation"/> <parameter key="translationSourceFields" value="ArticleLang.DescriptionShort(en)"/> <parameter key="characteristicRecordTranslationSourceLanguage" value="en"/> <parameter key="characteristicCategories" value="Ingredients;Allergens"/> <parameter key="translationTargetLanguages" value="es;fr;de"/> </component></group>The additional parameters specific to characteristic record values translation are the following:
|
Parameter name |
Description |
Valid values examples |
Default |
|
characteristicRecordTranslationSourceLanguage |
The source language of the characteristic records that shall be translated. Valid values include synonyms of any entry in the Enum.Language enumeration within the Product360 repository. If no value is defined, no characteristic records will be displayed for translation on the UI. |
en |
<empty> |
|
characteristicCategories |
The code(s) of the lookup values that represent the characteristic categories that will be used for translation. If no value is defined, records of all existing characteristics will be displayed. When using multiple category codes, separate them with semicolons. If you want to use a category code that contains a semicolon, you have to escape it by '\'. Example: The code Length;Width;Height has to be configured as <parameter key="characteristicCategories" value="Length\;Width\;Height"/> The flex UI definition is using XML syntax which means that you have to care about some special characters. Example: The category code Length&Width has to be configured as <parameter key="characteristicCategories" value="Length&Width"/> |
Ingredients;Allergens |
<empty> |
The accelerator package provides a flex UI template specific for characteristic record translation which can be found under CLAIRE_Services → Resources → Flex UI Templates.
Excluded characteristic records
If you are missing a characteristic record, it might be because some records are excluded from the translation. Check for the following:
Is the corresponding characteristic of data type 'Text'?
Is the corresponding characteristic language specific?
Is the corresponding characteristic not read only?
Is there a value in the source language to translate?
Is the corresponding characteristic active?
Is the category of the corresponding characteristic active?
Is the product/variant/item assigned to a structure group that has an assignment to the category of the corresponding characteristic?
Does the user have sufficient read and/or write access rights?
Batch translation
You can use the existing translation data quality rule configuration to translate fully qualified paths of records of simple characteristics in a batch mode. For details about the use of the translation rule configuration see the section Batch Translation from this chapter.
