Integration for Adobe Experience Manager

Installation Guide

November 2017

Introduction 3

SDL and AEM Versions 4

Installing the SDL Connector 5

AEM Package Manager 5

Configuring the SDL Connector 6

Configuring AEM Translation Integration 9

Configuration Instructions 9 Polling Frequency 11

Configure SDL TMS/Managed Translation 12

SDL TMS Preparation 12 Service User Account 12 SDL Managed Translation App 13 Workflows 14 Adding a File Type for AEM Content 14 Create the Configuration 16 Language Mappings 16

Configure SDL WorldServer 17

Service User Account 17 Client ID and Project Types 17 Workflows 17 Adding a File Type for AEM Content 18 Language Mappings 19

Prerequisites 21

Permissions 21 Smoke Test 21

About SDL 23

CONFIDENTIAL 3 SDL Translation Management for AEM – Installation Guide

SDL Translation Management Integration Delivering a culturally relevant and personalized web experience to your international customers relies on the ability to speak to them in their language. Our integrated language platform provides the technology and services you need to deliver quality local language content across every step of the customer journey. The SDL integration with Adobe Experience Manager (AEM) provides a seamless link to SDL’s translation technology and services, enabling you to quickly and easily manage multilingual web content and translation projects from within AEM. The integration can be deployed rapidly with minimal IT support required, enabling you and your teams to get started within minutes. The integration integrates with SDL TMS and SDL WorldServer, providing flexibility in the language technology of choice. Key benefits of the SDL Language Technology Integration for AEM include:

Deliver Quicker: Our simple but powerful platform is proven to cut the time to market for translated content

Save money: Our smart Translation Memory means you’ll never pay to translate the same phrase twice as you build your translation memory and control terminology

Improve Quality and Consistency: Match your language requirements to the right translation tools. Access our intelligent machine translation technology as well as over 1,000 in-house ISO certified translators

Gain control: Use your SDL interface to track project progress, manage spend and identify savings

SDL's integration is closely tied to the Adobe Translation Integration Framework - the features and functionality is therefore defined by this framework and Adobe.

CONFIDENTIAL 4 SDL Translation Management for AEM – Installation Guide

SDL and AEM Versions

This guide is will help you get the connector installed and AEM configured. Versions required:

Adobe Experience Manager 6.1 and above

SDL TMS 11.1 and above, with SDL Managed Translation

SDL WorldServer 11.1 and above Additional notes are included to highlight functional differences that occur in different versions of each product. The Adobe help pages have lots of useful information on how to setup and configure AEM for localization, and it is important to read this before using the connector. https://docs.adobe.com There are also lots of pages and support to guide users on the use of the AEM Translation Framework and submitting translation projects. https://docs.adobe.com/docs/en/aem/6-2/administer/sites/translation/tc-manage.html

CONFIDENTIAL 5 SDL Translation Management for AEM – Installation Guide

AEM Package Manager

Log in to AEM with your administrator credentials. 1. Locate CRX Package Manager from the AEM menu 2. Click Upload Package

3. Browse to the connector package that you acquired from SDL (e.g. com.adobe.granite.translation.connector.sdl.core.pkg-1.0.0.zip), select “Force Upload”, and then click OK:

4. Click the Install button for the package, then again in the resulting dialog:

5. The installation only takes a few minutes.

CONFIDENTIAL 6 SDL Translation Management for AEM – Installation Guide

6. Once complete, the connector will appear in AEM in the Cloud Services area.

To proceed you will need the SDL Language Technology access credentials. If you do not have these, contact your SDL Account Team or SDL Language Technology administrator. Navigate to Cloud Services and scroll down to SDL Translation Management.

1. Click Configure now under the SDL Translation Management service.

2. Complete the dialog with a Title and Name of your configuration. It is recommended to use a Title and Name that will be understandable for the AEM user creating translation projects. This is displayed to the user when they create a translation project as an option to choose configuration they want to use for their project.

3. Select Create

CONFIDENTIAL 7 SDL Translation Management for AEM – Installation Guide

4. This opens up the newly created Configuration.

5. Click Edit.

a. First choose the SDL Language Technology you are connecting to, SDL TMS or SDL WorldServer. The options following will change dependent on the technology.

b. Enter the URL. i. For TMS/Managed Translation: https://languagecloud.sdl.com

ii. For WorldServer: https://<<servername>>.sdlproducts.com/ws-api/v1 c. Enter Username and Password d. Client ID and Secret

i. For TMS/Managed Translation, this is found in the Mantra App. ii. For WorldServer, this is found in the WorldServer Client. Client Secret is not

required and will be greyed out. e. Project Configuration:

i. For TMS/Managed Translation, this is the config GUID in TMS. ii. For WorldServer, this is found in the WorldServer Project Type.

f. Select the option to disable or enable Preview. Enabling preview passes a preview package from AEM to SDL for displaying in-context preview during translation and review stages in the workflow.

CONFIDENTIAL 8 SDL Translation Management for AEM – Installation Guide

6. Click the Test Connection button. If successful you will see the following message:

If unsuccessful you will see the following message:

If this happens you need to check your login credentials, and troubleshoot any firewall issues between the two servers.

CONFIDENTIAL 9 SDL Translation Management for AEM – Installation Guide

Detailed instructions on how to configure the AEM Translation Integration Framework can be found on the Adobe docs’ website: AEM 6.1: https://docs.adobe.com/docs/en/aem/6-1/administer/sites/translation/tc-tic.html AEM 6.2: https://docs.adobe.com/docs/en/aem/6-2/administer/sites/translation/tc-tic.html AEM 6.3: https://helpx.adobe.com/experience-manager/6-3/sites/administering/using/tc-tic.html Use these instructions to complete the next few steps, relevant to your translation requirements and language setup.

Configuration Instructions

Navigate to Cloud services and scroll to Translation Integration. 1. Click Show Configurations, then “+”.

2. Complete the dialog with a Title and Name for your Translation Framework.

CONFIDENTIAL 10 SDL Translation Management for AEM – Installation Guide

3. Configure Sites and Assets to use the SDL TMS connector and choose the options as required, referring to the tables below taken from the Adobe docs instructions. Adobe lock down the Communities section to Microsoft Machine Translator, and SDL have no control to be able to change this section.

Sites Configuration Properties

The Sites properties control how the translation of page content is performed. Property Description

Translation Workflow

Select the translation method that the framework performs for site content: Machine Translation: The translation provider performs the translation using machine translation in real time. Human Translation: Content is sent to the translation provider to be translated by translators. Do Not Translate: Content is not sent for translation. This is to skip certain content branches which would not be translated but could be updated with latest content.

Translation Provider

Select the translation provider to perform the translation. A provider appears in the list when their corresponding connector is installed.

Content Category

(Machine Translation Only) A category that describes the content that you are translating. The category can affect the choice of terminology and phrasing when translating content.

Translate Tags Select to translate tags that are associated with the page.

Translate Page Assets

Select how to translate assets that are added to components from the file system or referenced from Assets: Do not translate: Page assets are not translated. Using Sites translation workflow: Assets are handled according to the configuration properties on the Sites tab. Using Assets translation workflow: Assets are handled according to the configuration of the properties on the Assets tab.

Auto-Execute Translation

Select to execute translation jobs automatically after translation projects are created. You do not have an opportunity to review and scope the translation job when you select this option.

Sites Configuration Properties

The Sites properties control how the translation of page content is performed.

CONFIDENTIAL 11 SDL Translation Management for AEM – Installation Guide

Property Description

Translation Workflow

Select the translation method that the framework performs for site content:

Machine Translation: The translation provider performs the translation using machine translation in real time.

Human Translation: Content is sent to the translation provider to be translated by translators.

Do Not Translate: Content is not sent for translation. This is to skip certain content branches which would not be translated but could be updated with latest content.

Translation Provider

Select the translation provider to perform the translation. A provider appears in the list when their corresponding connector is installed.

Content Category

(Machine Translation Only) A category that describes the content that you are translating. The category can affect the choice of terminology and phrasing when translating content.

Translate Tags Select to translate tags that are associated with the page.

Translate Page Assets

Select how to translate assets that are added to components from the file system or referenced from Assets:

Do not translate: Page assets are not translated.

Using Sites translation workflow: Assets are handled according to the configuration properties on the Sites tab.

Using Assets translation workflow: Assets are handled according to the configuration of the properties on the Assets tab.

Auto-Execute Translation

Select to execute translation jobs automatically after translation projects are created. You do not have an opportunity to review and scope the translation job when you select this option.

Polling Frequency

To change the schedule at which the AEM Translation Integration Framework polls SDL to check when translations are ready, you require access to the server location where AEM is installed. This can be done here: http://AEM_SERVER_URL/system/console/configMgr/com.adobe.cq.wcm.translation.impl.scheduler.SyncTranslationState

CONFIDENTIAL 12 SDL Translation Management for AEM – Installation Guide

The configuration of TMS/Managed Translation should be performed by the SDL TMS Administrator or SDL Account team who are assigned to your account. The instructions below specify an out-of-the-box configuration, designed to get you started and run a test project. SDL TMS has many options, configurations, and customizations available as part of the setup, and these should be discussed with your TMS Administrator and business leads during the discovery sessions. AEM also has many options and features to deliver xml, images and assets for translation. Work closely with the SDL TMS Administrator to ensure the requirements for files being passed from AEM to TMS are understood and the necessary file types, configurations and workflows are setup to support.

SDL TMS Preparation

The connector needs to have Language Cloud customizations enabled on the TMS. To do this, SDL Professional Services will need to add a line of code to your TMS’s customization file. You’ll then need to contact SDL Cloud Ops to run that customization to add to TMS. Raise a ticket in the SDL Helpdesk to action these items. The URL for the Connector is: https://languagecloud.sdl.com This should be provided along with the service user account details below to the Salesforce Admin setting up the app.

Service User Account

A service account should be created in SDL Managed Translation for use in authenticating the Connector. This account should only be used by the Connector and not by a human individual to protect against password resets. An example would be: Username: AEM-Integration-CUSTOMER-NAME Password: <<<use a strong, 16 digit password>>> Create a Permissions group with the following permissions.

Language Cloud Login via SDL Language Cloud View Cost Information Portal Create job Submit job on View all portal created jobs

CONFIDENTIAL 13 SDL Translation Management for AEM – Installation Guide

You can test the user and permissions have been set up correctly if you go to this URL and login to SDL Managed Translation. https://languagecloud.sdl.com/en/managed-translation/login

Note: You will only need to access SDL Managed Translation to test the User permissions and make the two settings above. After the setup, the Work givers will use their own personal account to access SDL Managed Translation, or their TMS accounts.

SDL Managed Translation App

Login to SDL Managed Translation using the Service User Account created earlier. 1. Go to the username in top right, and click the dropdown 2. Select My Applications

3. Create an AEM Connector App

4. This will give you the Client ID and Secret

CONFIDENTIAL 14 SDL Translation Management for AEM – Installation Guide

Workflows

Once you have your Service User in place you can create multiple configurations to be used in separate AEM configurations. Any standard TMS workflow options are ok to use for your AEM content. If you want to check project scope from the AEM interface in the SDL connector, you’ll need to add the Authorization stage to the workflow. The workflow should also have a Rebuild Translation and Translated Content Retrieval stage to ensure translations are returned to AEM at the end of the workflow. An example workflow is shown below:

Adding a File Type for AEM Content

An Options XML File will be provided by SDL to support the XML standard received from AEM. This has been built using standard files available in the AEM installation. There will be occurrences where customers have custom xml content that requires the options file to be modified.

To support AEM XML:

1. Create a new Options XML File in the Resources area 2. Upload the sdlftsettings file provided by SDL or that you created yourself.

CONFIDENTIAL 15 SDL Translation Management for AEM – Installation Guide

3. Then create a Content type with these settings and include the Options XML File.

Managing TAGSMETADATA.xml and ASSETSMETADATA.xml

In the AEM Translation Integration configuration, there were two option to translate Tags and Metadata. If these options where chosen, then AEM creates two additional xml files for translation called TAGSMETADATA.xml and ASSETSMETADATA.xml. These xml files will contain the associated tags and metadata such as SEO Terms, page titles, image Alt tags from the pages sent for translation. In most cases, the AEM XML file type you have created above will support the extraction of the associated translation content. Important Note: If these options are chosen, but the AEM pages don’t contain any tags or metadata, AEM still creates the XML and sends to SDL TMS for translation. TMS will process the files but they will contain zero words for translation. These files should not be deleted or modified in any way – they are correct and should be returned to AEM as part of the connector integration.

To Support AEM JSON in AEM 6.2 and above

AEM 6.2 supports an additional feature to translate Content Dictionaries. These files can be delivered to SDL TMS as .json format or as XML with json content. A file type should be created to support this content in the same way as you have done above for the AEM XML.

To Support Images and other Assets in AEM

AEM supports sending image files and assets for translation. From the Sites area, users can choose to include images (.jpg and .png) when they send pages for translation. In TMS ensure these file types are catered for and added to the workflows to be sent to the translators, or new workflows created to pass the images directly to Translated Content Retrieval if no editing is required. Within the AEM Assets area, users can use AEM to store and manage many types of file, including PDFs, InDesign, Dita and others. For each file type to be sent to TMS, ensure the appropriate file type is supported, and the associated pre-processing method and workflow applied in the TMS configuration.

CONFIDENTIAL 16 SDL Translation Management for AEM – Installation Guide

Create the Configuration

Create your configuration in TMS and assign the content type(s). The rest of the TMS setup should be performed as you would normally for any setup. Ensure that the Source and Target Encoding settings on the Encoding tab of the Configuration are set to “utf-8” for the AEM XML file type.

Language Mappings

It is important to ensure that the language mappings are accurate between AEM and TMS. For example if TMS is expecting en_us > fr, then the user in AEM must select the correct language codes during translation project creation.

Language mapping nodes are installed as part of the connector, and can be found in AEM under CRDX Lite

CONFIDENTIAL 17 SDL Translation Management for AEM – Installation Guide

The configuration of SDL WorldServer should be performed by the SDL WorldServer Administrator or SDL Account team who are assigned to your account. The instructions below specify an out-of-the-box configuration in SDL WorldServer to support the SDL WorldServer Connector and are designed to get you started and run a test project. SDL WorldServer has many options, configurations, and customizations available as part of the setup, and these should be discussed with your SDL WorldServer Administrator and business leads during the discovery sessions. AEM also have many options and features to deliver xml, images and assets for translation. Work closely with the SDL WorldServer Administrator to ensure the requirements for files being passed from AEM to SDL WorldServer are understood and the necessary file types, configurations and workflows are setup to support.

Service User Account

A service account should be created in SDL WorldServer for use in authenticating the Connector. This account should only be used by the Connector and not by a human individual to protect against password resets. An example would be: Username: AEM-Integration-CUSTOMER-NAME Password: <<<use a strong, 16 digit password>>> Assign the necessary Permissions for the user to be able to create and manage projects.

Client ID and Project Types

A new Client ID should be created to support the integration with AEM. We would recommend keeping this Client separate from all other Clients and workstreams in SDL WorldServer. Project Types can be created under this Client ID to be used in separate AEM Configurations.

Workflows

Once you have your Service User in place you can create multiple configurations to be used in separate AEM configurations. There are many options to setting up workflows in WorldServer, and there are some key stages to be defined for the AEM connector to perform certain functions. Failing to include these stages will result in errors or functionality not being available in the connector. An Example workflow is shown below. The Service User account should also be assigned to these key stages of the workflow.

CONFIDENTIAL 18 SDL Translation Management for AEM – Installation Guide

1. Authorization stage is required to provide Scope information to the user in AEM 2. Translate stage is required for translation to be performed as usual, but is also required to

support the Reject Translation feature in AEM 6.3 3. Translated Content Retrieval stage is required to support the polling mechanism from AEM

to retrieve files from WorldServer and back to AEM 4. The Reject link from Translated Content Retrieval back to Translate step supports the Reject

Translation feature. 5. The Done link from Translated Content Retrieval to Finish supports the Approve Translation

feature in AEM.

Adding a File Type for AEM Content

An Options XML File will be provided by SDL to support the XML standard received from AEM. However this has been built to the best of our ability using standard files available in the AEM installation. There will be occurrences where customers have custom xml content that requires the options file to be modified.

Managing TAGSMETADATA.xml and ASSETSMETADATA.xml

In the AEM Translation Integration configuration, there were two option to translate Tags and Metadata. If these options where chosen, then AEM creates two additional xml files for translation called TAGSMETADATA.xml and ASSETSMETADATA.xml. These xml files will contain the associated tags and metadata such as SEO Terms, page titles, image Alt tags from the pages sent for translation. In most cases, the AEM XML file type you have created above will support the extraction of the associated translation content.

CONFIDENTIAL 19 SDL Translation Management for AEM – Installation Guide

Important Note: If these options are chosen, but the AEM pages don’t contain any tags or metadata, AEM still creates the XML and sends to SDL WorldServer for translation. SDL WorldServer will process the files but they will contain zero words for translation. These files should not be deleted or modified in any way – they are correct and should be returned to AEM as part of the connector integration.

To Support AEM JSON in AEM 6.3

AEM 6.3 supports an additional feature to translate Content Dictionaries. These files are delivered to SDL WorldServer as .json format. A file type should be created to support this content in the same way as you have done above for the AEM XML.

To Support Images and other Assets in AEM

AEM supports sending image files and assets for translation. From the Sites area, users can choose to include images (.jpg and .png) when they send pages for translation. In SDL WorldServer ensure these file types are catered for and added to the workflows to be sent to the translators, or new workflows created to pass the images directly to Translated Content Retrieval if no editing is required. Within the AEM Assets area, users can use AEM to store and manage many types of file, including PDFs, InDesign, Dita and others. For each file type to be sent to SDL WorldServer, ensure the appropriate file type is supported, and the associated pre-processing method and workflow applied in the SDL WorldServer configuration.

Language Mappings

It is important to ensure that the language mappings are accurate between AEM and SDL WorldServer. For example if SDL WorldServer is expecting en_us > fr_fr, then the user in AEM must select the correct language codes during translation project creation. It is also important to make sure there are no duplicate language codes being used in SDL WorldServer. There should only be one single source language, and all language derivatives should be defined as such. For example Germany (Germany) and Germany (Austria) should be defined as de-de and de-AT respectively. If they are both set to de-de, the connector will error as it cannot find a single language code to map to.

CONFIDENTIAL 20 SDL Translation Management for AEM – Installation Guide

Language mapping nodes are installed as part of the connector, and can be found in AEM under CRDX Lite

CONFIDENTIAL 21 SDL Translation Management for AEM – Installation Guide

After installing the SDL Connector and following the necessary configuration work, we would recommend these prerequisites be confirmed and the smoke test performed to ensure the basic setup has been completed and the connector is working correctly.

Permissions

System Admin rights to the AEM Instance to which you want to install the SDL Connector.

Ensure you can access the SDL Language Technology server through any firewalls or proxy servers

o Go directly to the Server URL in a browser – can you see the login screen? o Do a test Ping on the URL – do you get a response?

You have the configuration details of the SDL Language Technology, provided by your SDL Administrator or SDL Account team.

Smoke Test

It’s a good idea to run a test through the system to ensure all of the settings have been made correctly and fully. Using pages from the Geometrixx Demo Site (AEM 6.1, 6.2) or We.Retail (AEM 6.3), is always a good test. Here are some steps to walk through an end-to-end process.

1) Install the connector from the adobe package manager 2) Go to the SDL Translation Management Cloud service and create a new configuration

a. Enter the credentials (Ensure you enter this accurately, there should be no trailing backslash on the URL).

3) Go to the Translation Integration Cloud service and edit the “Default configuration - Translation Integration”

a. Select Human Translation b. Select SDL Translation (or the name you gave when creating the Config in step 2) c. Set Translation Page Assets to “Using sites translation workflow” d. Deselect all other options

4) Go to Sites, We.Retail a. Go to Language Masters > English > Products > Men b. Select Coats c. Open the References tab d. Select Language Copies

5) Select Create and Translate a. Select Language as French b. Tick Select all sub pages c. Enter a Project Title d. Select Create

6) Go To Projects a. Open the project you have just created

7) Go to Translation Summary a. Select the Epsilon (…) in the bottom right of the tile

CONFIDENTIAL 22 SDL Translation Management for AEM – Installation Guide

b. Select Edit, and go to the Translation tab c. Ensure the source language is set as English (en) and the target language is set as

French (fr) i. You may need to alter these settings depending upon your SDL setup, ie en-

us/fr-fr d. Ensure the Translation Method, Translation Provider and Cloud Config match what

you setup earlier. e. Select Save

8) Send to Translation a. In the drop down at the top of the Translation Job tile select Start b. The Status should show the following states in order

i. Committed for Translation ii. Submitted

iii. Translation in progress c. To ensure the process is working it is often necessary to refresh the browser window

9) When Translation in Progress is displayed in AEM, login to SDL to see your project created. a. The project should create, pre-process the files and move to a stage such as

authorization. b. Move the project through the workflow to Translated Content Retrieval

10) In AEM, open your Project a. The Status in the Translation Job tile should show “Ready for Review” b. If not, open the Epsilon in the tile and check the individual files c. To ensure the process is working it is often necessary to refresh the browser window

11) Once all files are in Ready for Review status a. In the Translation Job tile, click the dropdown and select Approve Translations b. The status on the Translation Job tile shows Approved c. Go back into SDL and the translation job should also show as Complete

This has completed a basic round-trip test of the connector.

CONFIDENTIAL 23 SDL Translation Management for AEM – Installation Guide

SDL (LSE: SDL) is the global innovator in language translation

technology, services and content management. For more than 20

years, SDL has transformed business results by enabling nuanced

digital experiences with customers across the globe so they can create

personalized connections anywhere and on any device. Are you in the

know? Find out more at SDL.com.

Copyright © 2017 SDL plc. All Rights Reserved. All company product or service names referenced herein are properties of their respective owners.