AEM Cloud Connector Installation and Configuration

The following article will walk you through the steps to installing and configuring AEM Cloud with Smartling. Before proceeding with AEM Cloud installation, please read the following and linked additional resources.

Please note that this Connector is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.

Background

Adobe separated “code” and “content” for AEM Cloud. The “code” part of the repository is immutable and can only be changed with Pipeline build. The connector package contains both “code” and “content” data, it cannot be installed via CRX DE Package Manager anymore. To install the Smartling AEM Cloud Connector, you need to add a repository where the connector is and should depend on them and embed in the package.

Adobe suggested ISV Partners to submit a connector to the public Maven repository. Therefore, it is recommended to embed the connector as a part of AEM customization project.
 

Installation (Required)

Steps for embedding connector to a customization project

1. Copy and paste the following to main POM.xml (i.e. the public Maven repository where connector package is resided)

<repository>

    <id>central</id>

    <name>Central Repository</name>

    <url>https://repo.maven.apache.org/maven2</url>

    <layout>default</layout>

    <snapshots>

        <enabled>false</enabled>

    </snapshots>

</repository>

2. Check all dependencies. Add the following dependency to the connector package in main POM

<dependency>

        <groupId>com.smartling.aem</groupId>

        <artifactId>com.smartling.aem.connector</artifactId>

        <version><smartling-AEM-connector-version></version>

        <type>zip</type>

    </dependency>

Within the version tag, input the latest version of the connector which can be found here. If you are upgrading the connector input the version you are upgrading to and refer to these additional instructions. 

3. Add dependency to the connector package in All project’s POM

<dependency>

        <groupId>com.smartling.aem</groupId>

        <artifactId>com.smartling.aem.connector</artifactId>

        <type>zip</type>

    </dependency>

4. The Smartling AEM Cloud should be embedded. Add the connector package as embedded dependency to All package (the following listing is an example)

<plugin>

        <groupId>org.apache.jackrabbit</groupId>

        <artifactId>filevault-package-maven-plugin</artifactId>

        <extensions>true</extensions>

        <configuration>

            <group>com.adobe.aem.guides</group>

            <allowIndexDefinitions>true</allowIndexDefinitions>

            <embeddeds>

                <embedded>

                    <groupId>com.adobe.aem.guides</groupId>

                    <artifactId>aem-guides-wknd.ui.apps</artifactId>

                    <type>zip</type>

                    <target>/apps/wknd-packages/application/install</target>

                       </embedded>

                <embedded>

                    <groupId>com.adobe.aem.guides</groupId>

                    <artifactId>aem-guides-wknd.ui.content</artifactId>

                     <type>zip</type>

                    <target>/apps/wknd-packages/content/install</target>

                </embedded>

                     <embedded>

                        <groupId>com.adobe.aem.guides</groupId>

                        <artifactId>aem-guides-wknd.ui.content.sample</artifactId>

                        <type>zip</type>

                        <target>/apps/wknd-packages/content/install</target>

                       </embedded>

                     <embedded>

                        <groupId>com.smartling.aem</groupId>

                        <artifactId>com.smartling.aem.connector</artifactId>

                        <type>zip</type>

                        <target>/apps/smartling-vendor-packages/application/install</target>

                        </embedded>

                  </embeddeds>

           </configuration>

    </plugin>

5. Add filter for Smartling package

<filter root="/apps/smartling-vendor-packages"/>

Ensure that the `allowIndexDefinitions` flag is set to `true` for the configuration.

Note: Maven build will create an “All” package with the Smartling Cloud Connector embedded inside. The Connector will be installed on AEM Cloud with the next AEM Cloud Pipeline Build.

When installing or updating the Smartling package, keep in mind that indexes for the repository may be included. Adding or updating indexes can trigger AEM to re-index, which can take a while. Please plan for this time in your maintenance procedure.

Upgrading the Connector

Please follow these steps after upgrading to a new version of the Connector.

After Connector installation, cache for these UI files should be invalidated:

• /libs/cq/gui/components/authoring/editors/clientlibs/sites/page (js/css)
• /apps/smartling-connector/clientlibs/configuration (js/css)
• /apps/smartling-connector/clientlibs/touch-ui-smartling-job-assets-view (js/css)
• /apps/smartling-connector/clientlibs/touch-ui-smartling-job-xf-view (js/css)
• /apps/smartling-connector/components/language-selector/clientlib (js/css)
• /apps/smartling-connector/clientlibs/touch-ui-smartling-job (js/css)
• /libs/cq/translation/translationrules/clientlibs/contextproperty (js/css)

Use these tools to clear UI cache:

1. Invalidate/Rebuild UI libraries via /libs/granite/ui/content/dumplibs.rebuild.html
2. Remove cache for the files in Dispatcher, see info linked here.
3. Clear browser's cache

Configuration

Create a Translation Integration Configuration 

You can create a new configuration (folder). To do this, open Translation Cloud Services.

Now you can create a configuration folder where you will add two translation configurations.

1. Open the new Translation Cloud Services (/mnt/overlay/cq/translation/gui/content/cloudservices.html)
2. Select conf - global and click Create.
3. From the dropdown, select Translation Integration Configuration
   
4. Edit the configuration for Sites as follows
   
    
5. Edit configuration for Assets as follows
   

To learn more about available options, see the official AEM documentation.

Make sure that the Auto-execute Translation option is enabled for both the Sites and Assets tabs.

Smartling Configuration Editor

The Web Console is not available for users in AEM Cloud. It means you don’t have a UI in AEM for configuring additional options for the connector. However, you can apply OSGi configurations with special JSON files. It works for both AEM Standalone and AEM Cloud. 

You should create a new AEM locale user for the connector or reuse existing. Content Viewer should have permissions to browse (read) content. These requirements are the same as for Touch Connector. The only difference is deploying configuration to AEM: via UI for Touch Connector, via JSON file for Cloud Connector.

Adding multiple source locales to a project

You can only have one Smartling project configuration in AEM. This project has source and target locales that are mapped to the source and target locales of the project in Smartling. Each project in Smartling can have only one source locale. 

To translate AEM content in Smartling from multiple source locales, you can add a source locale override to the Smartling project configuration, and map that source locale to the appropriate AEM project in Smartling. This allows you to translate AEM content from multiple source languages, within a single AEM instance.

To add multiple source locales, do the following:

1. Create an AEM Connector project in Smartling with the source locale you want to translate from
2. Get the API credentials from Account Settings > API v2 > Project Tokens > Create Tokens
3. In the Smartling project configuration in AEM, add source locale override (pictured)
4. Insert credentials

Add as many source locales overrides as required. Ensure each override is mapped to a Smartling project with the AEM locale as the source locale.

How to configure the connector to narrow the list of target languages

Go to the following OSGi configuration file and set the first two settings to true:  com.smartling.aem.connector.automation.ui.SmartlingDialogConfiguration.cfg.json

{
  "respect.content.observing.language.roots": true,
  "only.sibling.language.roots": true
}

OSGi Configuration Options

The SmartlingDialogConfiguration.cfg.json file is used to control the behavior of the connector. Adjusting these settings allows you to fine-tune how the connector interacts with your AEM instance and handles translation processes.

Example Configuration File

Below is an example of a configuration file with the recommended settings:

com.smartling.aem.connector.automation.ui.SmartlingDialogConfiguration.cfg.json

{
  "respect.content.observing.language.roots": true,
  "only.sibling.language.roots": false,
  "translation.project.enable.legacy.config.validation": true,
  "target.content.existence.validation": false,
  "translation.pseudo.default": false,
  "check.dam.folder.descendants": false
}

Settings Descriptions

• respect.content.observing.language.roots - Ensures that the connector respects the language root structure in AEM. This helps properly identify language copies based on AEM’s multilingual site hierarchy. This option is passed directly to AEM, additional related information can be found here.
• only.sibling.language.roots - Allows content from non-sibling language roots to be included in translation requests. When set to true, only direct sibling language roots are included in translation requests. Set to false to allow content from non-sibling language roots to be included.
• translation.project.enable.legacy.config.validation - Enables validation of translation project configurations using legacy (older) configuration methods. Useful for maintaining compatibility with legacy setups that have not migrated to the newer configuration schema.
• target.content.existence.validation - Controls the validation to check whether the target (translated) content already exists. When set to true it prevents overwriting or recreating already translated assets.
• translation.pseudo.default - Controls whether pseudo translation is used by default. When set to true, all translation requests will return pseudo translations. Pseudo translation is typically used for testing content structure and layout before conducting actual translation.
• check.dam.folder.descendants - When set to true, this option allows the connector to recursively check within DAM folders for translatable assets. This can be useful for bulk translations where assets may be nested within subfolders. 

Configure Web Callbacks

When the translation of a file is completed, Smartling sends an HTTP request to the AEM Cloud Connector. The connector then instructs AEM to sync the translation with Smartling.

To configure web callbacks, ensure the appropriate URL is specified in the OSGi configuration file.

The connector can also validate the signature of incoming callback requests using a shared secret. To enable this feature, contact your Smartling Solution Architect or another Smartling representative to enable signed callbacks for your account.

Example configuration file:
com.smartling.aem.connector.core.SmartlingCredentialsConfiguration.cfg.json

{
  "callback.url": "https://domain.com/services/smartling/sync-translation",
  // This property is used by default.

  "callback.host.url": "https://my.domain.com",
  // If callback.url is not specified, then this URL will be used: 
  // https://my.domain.com/services/smartling/sync-translation

  "callback.shared.secret": "MySecret"
}

Also, you will need to allow anonymous access to Smartling AEM connector callback endpoint:
/services/smartling/sync-translation

you can do this within org.apache.sling.engine.impl.auth.SlingAuthenticator.cfg.json

{
  "sling.auth.requirements":[
    "+/",
    "-/libs/granite/core/content/login",
    "-/etc.clientlibs",
    "-/etc/clientlibs/granite",
    "-/libs/dam/remoteassets/content/loginerror",
    "-/aem/update.theme",
    "-/linkexpired",
    "-/services/smartling/sync-translation"
  ]
}

Add character limits

You can set a character limit for a property mapping. This feature was introduced in version 5.9.50. We recommend using it with plain text strings. The character limits will be visible to linguists working on translations in the CAT Tool.

How to configure visual context

You can configure context for the connector using a JSON file to specify a service user for retrieving context. This AEM user must be a local user and must have read only (jcr:read) permissions for the /content path.

Example Configuration File 

Below is an example of a configuration file: 
/apps/<your_app>/osgiconfig/config/com.smartling.aem.connector.context.impl.resources.http.HttpResourceLoader.cfg.json

{
  "direct.rendering": true,
  "server.url": "<your-aem-instance-url>",
  "user.name": "<your-content-viewer-user-name>",
  "user.password": "<your-content-viewer-user-password>",
  "connection.timeout": 2000,
  "socket.timeout": 10000,
  "request.wcmmode": "disabled"
  "preview.from.source": true
}

Settings Descriptions

• direct.rendering (optional; default is true) - Controls how the connector captures context.
  When set to true, the connector captures context from AEM natively using SlingRequestProcessor. When set to false, the connector captures context directly from AEM, using HTTP based rendering. If set to false, you must also provide values for the next three fields.
• server.url (required when direct.rendering is set to false) - The URL of your AEM Author instance.
• user.name (required when direct.rendering is set to false) - Username for local AEM Cloud user.
• user.password (required when direct.rendering is set to false) - Password for local AEM Cloud user.
• connection.timeout (optional; default is 2000 ms) - Connection timeout (in milliseconds) for loading context from the AEM instance. Minimum: 2000 ms, Maximum: 10000 ms.
• socket.timeout (optional; default is 10000ms) - Socket timeout (in milliseconds) for loading context from the AEM instance. Minimum: 10000 ms, Maximum: 20000 ms
• request.wcmmode (optional; default is disabled) - WCMMODE used for previewing context. When set to disabled, it shows the page as it would appear on the publish instance; no authoring UI is rendered. When set to preview, the page is rendered in preview mode, simulating how it would look in publish, but still within the author environment. 
• preview.from.source - Enables or disables taking the context preview from the source. For pages and experience fragments, the context preview is taken from associated launches by default. 

The configuration will be deployed on the next Pipeline Build.

After you have completed all steps above, you can check connector installation and initial configuration on Cloud Services page

Clicking on `Test Connection` icon should check connectivity to Smartling TMS and retrieving a context. A successful connection message will appear.

Troubleshooting Configuration

1. When creating a Smartling configuration, make sure that you set the configuration for the page that is the parent to your sites (original and localized).
2. Error: "The Translation Provider Doesn't Support Translation for the Selected Language Pair."The AEM Cloud Connector is delivered with predefined language mappings between Smartling and AEM language codes. This error means that the AEM site language code does not match a Smartling language code. For example, an AEM site uses the code "fr" for French, but Smartling project uses "fr-FR" for French (France). To correct the problem, update the mapping and restart your job.
   1.  

AEM site language code:

Incorrect mapping:

Smartling language code:

Correct mapping:

You can adjust language mappings in /apps/granite/translation/connector/config/smartling/languageMapping. Generally, you should only need to edit this file when you add a new language in AEM.

Automation Configuration

The connector allows you to configure AEM Translation project automatic options. The OSGi configuration can be specified as com.smartling.aem.connector.automation.impl.wcm.project.TranslationProjectResourceManager.cfg.json:

{
"polling.retry.count": 60,
"polling.retry.sleep": 600,
"polling.upload.complete": 30,
"translation.project.enable.approve": true,
"translation.project.enable.delete": true,
"translation.project.enable.promote.launch": true
}

Configuration Options

polling.retry.count
Defines the number of times AEM will retry polling the translation provider (Smartling) to check the status of a job.

polling.retry.sleep
Specifies the number of seconds the system will wait between each polling attempt.

polling.upload.complete
Sets the time (in minutes) the connector waits after content is requested for translation before checking if the upload is complete. The minimum is 10 and the maximum is 30. 

translation.project.enable.approve
Enables users to approve translation jobs directly from the AEM UI. 

translation.project.enable.delete
Allows users to delete translation projects from the AEM UI.

translation.project.enable.promote.launch
Enables promotion of translation projects to a Launch — an AEM feature used to stage and review content updates before publishing.

translation.project.enable.legacy.config.validation
Controls whether validation is enabled for legacy translation configurations applied to a page.

Auto Authorize

Auto Authorization can be used as a default value for the Authorize Job option in the Smartling Dialog. OSGi configuration file is:  com.smartling.aem.connector.core.impl.integration.SynchronousSmartlingFacade.cfg.json:

{
"auto.authorize": true,
"move.strings": false
}

Configure socket timeout

The connector makes HTTP connection to Smartling with socket timeout set to 40000 milliseconds by default. If you experience errors related to SocketTimeoutException, you can adjust this value in the OSGi configuration file:
com.smartling.aem.connector.core.impl.integration.platform.ApiInstanceBuilder.cfg.json

api.socket.timeout defines the timeout for requests sent to Smartling, in milliseconds. The minimum value is 10000 ms, the maximum is 60000 ms, and the default is 40000 ms.