Cloudwords Connector provides an interface between Adobe Experience Manager(AEM) and Cloudwords products. The connector functionality enables adding the content required for translation from AEM. The content can be pages, assets, assets metadata, tags, tags metadata and i18n dictionaries. These all content are present under an AEM project. Connector enables sending the project containing source content into Cloudwords. As soon as user logs into Cloudwords account the project is already created and the source files are uploaded into the project. Once the entire vendor selection and bidding process is completed, the translations are available in Cloudwords for review. The translated files are then imported into AEM and are available for review at AEM side.
The scope of the document is to provide details on how to install Cloudwords Connector and complete all the required configurations.
- Cloudwords Account (Access to URL and API key)
- Adobe Experience Manager 6.3 Beta installer (Tested on Load 3, cq-quickstart-beta-6.3.0-load18)
- Cloudwords Connector Package
Installation through Package Manager
1) Sign in to AEM Home page by accessing URL: http://<hostname>:<port>, Username - xxxxx, Password - xxxxx.
2) Navigate to AEM’s Package Manager tool to upload the connector package either by accessing following URL: http://<hostname>:<port>/crx/packmgr/index.jsp
Click on Top Navigation -> Tools -> Deployment -> Packages, the package manager interface can be accessed.
3) Click on Upload Package in Top Menu and browse through the path of Cloudwords Translation Connector Installation Package. Click on OK to upload the package.
4) Once package is successfully uploaded, click on ‘Install’.
5) Activity Log states the artifacts which are installed with the package.
Cloudwords Connector Configuration
1) Navigate to AEM’s CloudServices Configuration Manager either by accessing following URL: http://<hostname>:<port>/miscadmin#/etc/cloudservices/cloudwords-translation
Click on Top Navigation -> Tools -> Operations -> Configuration
2) Create Cloudwords Configuration by:
3) Once the cloud configuration is created, double click on it to open the configuration page.
4) Select the Base URL property from the dropdown and enter corresponding API key.
Values in Base URL dropdown can be modified by adding values in following format in environment_urls.json.properties file:
To access the path, open CRXDE Lite and open the property file present at location: “/etc/workflow/models/translation/environment_urls.json.properties”
5) After entering Base URL and API key, click on ‘Connect to Cloudwords' button. In case the credentials are correct, this will fetch the associated ‘Departments’ list.
In case after entering URL and API key, ‘Connect to Cloudwords' button isn’t enabled, then please click anywhere in the opened dialog box.
In case no Department is associated with the account, the ‘Department’ dropbox will be disabled. So a basic check to ensure that connect to Cloudwords is working is that Department dropbox should be available (even if it is disabled). In case API key is incorrect or due to any other reason AEM is unable to communicate with Cloudwords, an error message would be thrown.
Translation Rules Editor
This is one of the most critical step in Connector Installation. The translation rules file contains all the components and the associated properties which are required to be translated. In case any property is missing from this file, then that text will not be sent for translation.
Generation of this file is right now a manual step. By default, few properties of OOTB components are already existing but this needs to be modified as per the requirement.
All the common properties, for e.g. ’text’, which are required to be translated should be listed as:
If any property in a specific component needs to be excluded for translation, then add it as following:
<property name=“image” translate=“false”/>
File location is - /etc/workflow/models/translation/translation_rules.xml
This file can be easily generated using 'The Translation Configuration' tool introduced with 6.3.
Translation Rules JSON Editor
In any application, custom components might be used which render the result in JSON format. Such properties are not converted into proper trans-units, even if they are mentioned in translation_rules.xml file.
We use another translation rules file which should consist of only those properties for translation in JSON which are required to be translated.
Let’s say there is a custom component ‘applicationname/components/customteaser’ containing property name ‘customlink’ which renders data in JSON format. This property contains keys ‘linktext’ and ‘linkvalue’ like this:
“linktext”:"Custom Link Text",
In this case “linktext” is required to be translated and “linkvalue” shouldn’t be translated. So it needs to be added in the rules JSON file in following format:
If this use case if valid, then following file also needs to be configured.
P.S. - There is no need to add the properties which are not required for translation.
File location is - /etc/workflow/models/translation/translation_rules_json.xml
Property Character Limit
In case the application imposes a character limit on the property to be translated and the character limit information needs to be conveyed to the vendor before translation then those properties along with their limits have to mentioned in the file located at /etc/workflow/models/translation/translation_rules_property_character_limit.xml
These limits can be specified as
<property name="jcr:title" limit="10"/>
<property name="jcr:description" limit="40"/>
1) Navigate to AEM’s CloudServices Configuration Manager either by accessing following URL: http://<hostname>:<port>/system/console/configMgr
Click on Top Navigation -> Tools -> Operations -> Web Console and then by clicking on Configuration
2) Following configurations are Cloudwords Connector specific configurations. One can search for these Configurations by provided names or access them via URL mentioned below. These configurations have few default values already set and these can be changed as per requirement.
Cloudwords Translation Connector Factory
- Go to http://<host>:<port>/system/console/configMgr/com.hermease.translation.connector.core.services.CloudwordsTranslationServiceFactoryImpl
- InContext Preview checkbox: This provides flexibility to enable/disable InContext preview feature. By default this feature is enabled.
- Allow SVG tags in preview?: Whether to allow SVG tags in the in-context preview, if false svg images would not be visible In-context preview. This property is ignored if In-Context Preview is disabled.
- Enable Redirect Page Handle?: Whether to handle the page redirection on translated page,if it is disabled, the in-context preview generated for the page is in wcmmode disabled otherwise if enabled, for the translated pages where there is redirect in disabled mode, the in-context preview generated for the page is in wcmmode author(to prevent redirection) . This property is ignored if In-Context Preview is disabled.
- Does Language Code contain hyphen(-)?: In case AEM’s content structure is such that the language code contains hyphen(-) instead of underscore(_), then this checkbox should be enabled. By default this is disabled.
- Is URL encoded/escaped?: Whether the image/assets URL used in the site are encoded/escaped. Ex. In case of HTL styleString context. This property is ignored if In-Context Preview is disabled.
- Translation Approach: Due to issues in AEM APIs currently by default 'Custom' approach is selected. Once the product issues are resolved the approach can be changed to ‘AEM’. This configuration SHOULD NOT be changed, otherwise the connector functionality would break.
- Temporary folder path: This location needs to be configured for storing temporary xliff and zip files. The configuration should be set as per OS. For e.g. in case of linux, the value can be “/tmp”. For Windows, it can be “C:/tmp”. Also there should be write access granted to this folder. By default the value is set to “/tmp”.
- AEM Base URL: This URL contains host and port of the AEM instance on which connector is required to be installed. The syntax should be “http://hostname:port”. By default the value is set to “http://localhost:4502”.
- ID: The user which has administrative rights. It can be admin or any other similar user. By default the value is “admin”.
- Password: Password for above mentioned user.
- Ancestor level for file name: Number of parent node names to append to source page node name to create a unique file name.
Cloudwords Extra Features Service
- Go to http://<host>:<port>/system/console/configMgr/com.hermease.translation.connector.core.services.impl.TranslationObjectConfigImpl
- Number of objects (including pages, assets, metatadata, i18n, tags) to be translated can be configured in 'Translation Object Upload limit' textbox.
- Enable Character Limit Feature: to enable character limit for properties sent for translation. To use this feature PropertyCharacterLimitRuleFile must be configured. By default this feature is disabled.
- Supported Asset MimeTypes can be entered in 'Asset Mimetypes' textbox. The asset types which should be supported needs to be added by clicking on '+' button. The configurations can be added in following format:
- Reference - https://en.wikipedia.org/wiki/Media_type
- Enable Multi Target Language Feature: In order to enable Multi target Language feature in Cloudwords Connector, the checkbox should be enabled .By default this feature is disabled.
- Is LiveCopy used?: In case AEM's content structure is such that the Live Copy Source is required to be sent for translation and there is no need to use Language Copy feature provided by AEM, then the checkbox should be enabled. By default this feature is disabled.
- Enable Delta content translation: In order to enable Delta content translation feature in Cloudwords Connector, this checkbox should be enabled. By default this feature is disabled. (Note: When you disable this checkbox, all previously stored files will be deleted and whole content will be sent for translation).
- Enable delta project level option: Enable this checkbox to provide an option to enable or disable delta feature at the time of project creation.
Cloudwords Proxy Configuration
- Go to http://<host>:<port>/system/console/configMgr/com.hermease.translation.connector.core.services.impl.CloudwordsProxyConfigurationImpl
- Enable HTTP Proxy: If any Proxy Server is used, then this checkbox should be enabled. By default, it is disabled. If this is enabled, then the connection with Cloudwords would be established using these proxy configurations.
- Proxy Configuration: There are 3 options - Custom, Apache and Day Commons.
- Custom - In case it isn’t known how proxy is being set on AEM server, then proxy configurations which are entered in the existing configuration box is preferred and set
- Apache - In case proxy configurations are set in ‘Apache HTTP Components Proxy Configuration’ component, then the values entered in this component are set
- Day Commons - In case proxy configurations are set in ‘Day Commons HTTP Client 3.1’, then the values entered in this component are set. Currently HTTP Proxy NTLM Host and Domain values are not set, so in case the proxy server contains NTLM values, then please select Custom Proxy Configuration. (The issue should be fixed in next release)
- HTTP Proxy Host: Host name or IP address of the Proxy server
- HTTP Proxy Port: Port of Proxy server
- HTTP Proxy User: In case authentication is enabled, then User can be specified here
- HTTP Proxy Password: In case authentication is enabled, then Password can be specified here
- In case authentication is disabled, then also the connection can be established with Cloudwords
- Cloudwords log level setting as per environment. For e.g., it can be ‘Trace’ for Development, ‘Error’ for QA/Prod.
Translation Platform Configuration
This configuration is used to schedule the translation frequency.
Our recommendation would be to keep it to 1 day for Production environment. This is the default value.
On any other environment like QA, Stage, Dev etc., the value can be set to 5 mins by using following cron value: 0 0/5 * * * ? *
System User Validation
Please ensure System User 'translation-job-service' exists in AEM installation. This user is present in default installation of AEM 6.3 and is being used in our solution. In case this user doesn't exist, then please create this same system user and provide it 'Read' access on '/apps'.
Go to http://<host>:<port>/useradmin and search 'translation-job-service'.