Skip to main content

AEM Cloud Connector Installation and Configuration

Install, upgrade, and configure the Smartling AEM Cloud Connector.

This article will walk you through the steps to install and configure AEM Cloud with Smartling. Before proceeding with the AEM Cloud installation, please read the information below along with the additional linked resources.

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

Simplified Index Management support
​
As of AEM Cloud Connector version 5.9.71, the connector no longer provides its own indices. You must add the connector's index definitions to your AEM customization project's diff.json file. See Simplified Index Management using the diff index.
​
Download the AEM Cloud Connector's diff.json file from the Attachments section at the bottom of this article.
​
Each environment uses one diff.json file. If your project already has one for your own indexes, merge these six entries into it. Do not replace it or add a second file, because entries in additional files are ignored.
​

If you are upgrading from a version earlier than 5.9.71, see Upgrading the Connector.

  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>

    Note: 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"/>

Tip: To deploy the connector’s index definitions from your project’s diff.json, set allowIndexDefinitions to true on your ui.apps and ui.apps.structure packages, and add oak:index to immutableRootNodeNames (the default is apps,libs).

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.

Adding or updating index definitions in diff.json triggers a re-index during your Cloud Manager pipeline deployment, which can take a while depending on repository size. Plan for this time in your maintenance procedure.


Upgrading the Connector

Follow these steps when you upgrade to a new version of the AEM Cloud Connector.


Before you deploy

If you are upgrading from a version earlier than 5.9.71 (action required): The connector no longer provides its own index definitions. Before you deploy, add the connector's index definitions to your AEM project's diff.json. Download diff.json from the Attachments section at the bottom of this article.

If your project already has a diff.json file for your own indexes, merge these entries into it. Do not replace it or add a second file, because entries in additional files are ignored. For details, see Adobe's Simplified Index Management using the diff index.
​
​Note: Adding or updating index definitions triggers a re-index during your Cloud Manager pipeline deployment. Deployment time depends on the size of your repository, so plan for this before you deploy.

After you deploy

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.

screenshot-1.png


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

    screenshot-6.png

  4. Edit the configuration for Sites as follows

    screenshot-5.png

  5. Edit configuration for Assets as follows

    screenshot-4.png


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

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

Smartling Configuration Editor

Screenshot_2021-02-02_at_14.52.12.png

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.

Screenshot 2023-10-25 at 6.40.15 PM.png


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
}

Select target languages with language groups

Requires AEM Cloud Connector version 5.9.76 or later.

You can let users choose a language group in the Smartling dialog instead of selecting each target language one by one. When the user selects a group, the dialog resolves the languages that belong to the group and selects them as the target languages for the translation request.

This feature is optional and is turned off by default.

How to use the feature

  1. In the OSGi configuration file com.smartling.aem.connector.automation.ui.SmartlingDialogConfiguration.cfg.json, set language.groups.enabled to true. See the Example OSGi configuration file below. The configuration is deployed on the next Pipeline Build.

  2. Open the Smartling dialog. The dialog now has a Language Group field above Target Languages. Open the list to see the groups available for the selected Smartling project.

  3. Select a group. The languages in the group are selected as target languages.
    ​

    Smartling dialog with the de_fr_es language group selected and German, French and Spanish filled in as target languages

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 OSGi 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,
"language.groups.enabled": true,
"check.dam.folder.descendants": false,
"max.jobs.limit":100
}


OSGi 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.

  • language.groups.enabled - Shows the Language Group field in the Smartling dialog. When set to true, the field lists the language groups available for the Smartling project, and selecting a group selects its languages as the target languages. The default is false. For details, see Select target languages with language groups.

  • 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.

  • max.jobs.limit - Controls the maximum number of jobs displayed in the Add to Job tab. The default value is 100.


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.impl.config.CallbackUriProviderConfig.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.

aem-cloud-character-limit.png


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 visual context 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
}


Visual context 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

Screenshot_2021-02-02_at_14.52.03.png


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

Screenshot_2021-02-02_at_14.51.12.png


Control access to the translate button

Requires AEM Cloud Connector version 5.9.74 or later.

By default, every user with access to the connector sees the Translate button. You can use the smartling:translationButton permission to control which users and groups can see it. This is useful when only certain teams, such as project owners or localization managers, should submit content for translation.

The permission only controls the visibility of the Translate button. Users who don’t have the permission can still request translations through the References panel.

This feature is optional and is turned off by default. The connector grants the permission by default to the smartling-projects-owners group, with allow on the path /content.
​

aem-cloud-access-control-list


​How to use the feature

First, your AEM administrator must enable the feature in OSGi. It is off by default. com.smartling.aem.connector.automation.impl.visibility.TranslationButtonVisibilityService.cfg.json:
​

{   
"restrict.translation.button": true
}


After that, an administrator can assign the permission to a specific user or group. For example:

AEM Permissions view for user test, showing a deny entry for the smartling:translationButton privilege on /content/wknd/language-masters/en/magazine

In this example, the smartling:translationButton privilege is set to deny for the user test on /content/wknd/language-masters/en/magazine. The Translate button is hidden for that user on the Magazine page.


This feature works for Sites, DAM, Forms, and Page Editor UIs.

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
​

file.png


​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.

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.

AEM site language code:

produits.png


Incorrect mapping:

translation_project_properties.png


Smartling language code:

smartling-language-code.png


Correct mapping:

correct_mapping.png

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
}


Automation 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": "NONE"
}


Move strings

You can control which strings are added to a job when you request content for translation. It can be specified in the OSGi configuration file
​com.smartling.aem.connector.core.impl.integration.SynchronousSmartlingFacade.cfg.json:
​
Three options are available:

  • NONE – only add new strings from the file

  • IN_PROGRESS – also move existing untranslated strings from other jobs

  • ALL – move every string in the file, including already published ones

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


Configure Auto-Resubmission for Updated Translations

Once a file is fully published, the AEM connector delivers translations to AEM, but any subsequent edits to those published translations are not automatically sent back.

With this setting enabled, the connector automatically resubmits content when published translations are edited and republished after the original AEM job completed, eliminating manual resubmission when translators fix content post-delivery.


The feature is managed by OSGi configuration com.smartling.aem.connector.automation.impl.republish.AutoRepublishPollingJob.cfg.json:

{
"enabled": true,
"cronExpression": "0 0 8 1/1 * ? *",
"lockTtlMinutes": 30,
"recentlyPublishedWindowDays": 1,
"metadataRetentionDays": 30 }

The connector runs a background job on a configurable schedule. At each interval, it checks whether any translation updates have been made to previously submitted content, using metadata saved at the time of the original upload. If updates are detected, the connector automatically resubmits the content to the same Smartling job using the original request parameters: job, target language, and custom fields. If the original job no longer exists, the connector creates a new job.


Limitations

  • Applies to pages, Experience Fragments (XFs), and Content Fragments (CFs) only.

  • Automatic resubmission only applies to content that was originally requested after this setting was enabled.


Attachments

diff.json contains the AEM Cloud Connector's index definitions. It is required for version 5.9.71 and later. See Installation and Upgrading the Connector for how to use it.

Attachment icon
Did this answer your question?