Adobe Experience Manager Connector
Overview Key features Update notes Release notes Installation guide Package installation Deployment to AEMaaCS Connector configuration Custom content types Additional settings Custom language mapping Create user group Grant user permissions Share access to projects Auto replace hyperlinks User guide Create new language copy Update language copy Component translation Translation Project template Avilinga Translations console Manual translation retrieval Manual Launch promotion i18n dictionary translation Audit translations Share a project Maintenance Troubleshooting Remote Log service Solve issues

Installation guide

Note: This section covers the installation of Avilinga Translation Connector to the AEM on-premise environment. If you need the instructions to deploy the Connector to AEM as a Cloud Service, follow the next section.

The connector is installed in the usual fashion via the AEM Package Manager:

1. In Tools, Deployment, go to Packages.

2. Click on Upload Package and upload the zip package provided to you by Avilinga. Use the Force Upload option on updating the connector to the new version.

3. Click Install to install the uploaded package. In case of package update click Reinstall.

4. Retain default settings and confirm Install.

Congratulations! You have successfully installed the Avilinga Translation Connector for AEM!

Deployment to AEM as a Cloud Service

Note: Skip this section if you need to install Avilinga Translation Connector to AEM on-premise and follow the Package Installation section.

1. Add the following code to the parent pom.xml file of your AEM repository to specify the Avilinga Maven repository with Translation Connector:

Note: Replace <url> content with the repository URL provided to you by Avilinga. 
<repositories>
    <repository>
        <id>maven-ld-ai</id>
        <name>Avilinga</name>
        <url>url_provided_by_avilinga</url>
        <layout>default</layout>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

2. Add the following code to the <dependencies> section of the parent pom.xml file replacing the <version> content with the version provided to you by Avilinga:

<dependency>
    <groupId>com.avilinga.translation.connector</groupId>
    <artifactId>avilinga-connector-cloud</artifactId>
    <version>version</version>
</dependency>

3. Add the following dependency to the all/pom.xml file replacing the <version> content with the version provided to you by Avilinga:

<dependency>
    <groupId>com.avilinga.translation.connector</groupId>
    <artifactId>avilinga-connector-cloud.all</artifactId>
    <version>version</version>
    <type>zip</type>
</dependency>

4. Add the embedded to the filevault-package-maven-plugin configuration of the all/pom.xml file:

<embedded>
    <groupId>com.avilinga.translation.connector</groupId>
    <artifactId>avilinga-connector-cloud.all</artifactId>
    <type>zip</type>
    <target>/apps/avilinga-connector-packages/container/install</target>
</embedded>

5. Add the filter to the filter.xml file of the all project:

    <filter root="/apps/avilinga-connector-packages"/>

6. Commit your changes and deploy your code to the environment by running the Pipeline.

Connector configuration

To configure Avilinga Translation Connector navigate back to AEM main screen and follow the next steps:

1. In Tools, Cloud Services, go to Translation Cloud Services.

2. Navigate to conf, global and click Create.

3. Select Translation Integration, enter a Title (e.g., Avilinga) and click Create.

4. Configure Sites as follows:

- Set Translation Method to Human Translation.

- Set Translation Provider to Avilinga Translation Connector.

- Recommended setting for Translate Page Assets is Do Not Translate.

Note: this option enables sending of all asset files (i.e., images) with the page. As Avilinga does not accept image files for direct translation they will be skipped anyway during translation project creation. This option does not affect Content Fragments.

- Recommended setting for Translate Component Strings is OFF.

Note: this option allows sending of i18n dictionary items associated with the page. Recommended to keep this setting OFF and to submit i18n files independently.

- Recommended setting for Translate Tags is ON for AEM 6.4.8 and above and OFF for AEM 6.4.2 and prior due to AEM bug. 

Note: this option sends AEM page tags to translation.

- Set Auto Execute Translation option to OFF.

Note: this option affects standard AEM forms only and is not valid for Avilinga.

5. Configure Assets as follows:

- Set Translation Method to Human Translation.

- Set Translation Provider to Avilinga Translation Connector.

- Recommended setting for Translate Content Fragment Assets is Do Not Translate.

Note: this option enables sending of all asset files (i.e., images) with the page. As Avilinga does not accept image files for direct translation they will be skipped anyway during translation project creation. 

- Recommended setting for Translate Metadata is ON.

Note: this option allows sending asset metadata to translation.

- Recommended setting for Translate Tags is ON for AEM 6.4.8 and above and OFF for AEM 6.4.2 and prior due to AEM bug. 

Note: this option sends AEM page tags to translation.

- Set Auto Execute Translation option to OFF.

Note: this option affects standard AEM forms only and is not valid for Avilinga.

- Click Save & Close.

Further reference: https://experienceleague.adobe.com/docs/experience-manager-64/administering/introduction/tc-tic.html

6. Navigate to conf, global, Avilinga Translation Connector and click Create.

7. Enter a Title (e.g., Avilinga), and click Create.

8. Configure Basic as follows:

- Select correct Avilinga Environment.

Note: select Stage for testing and UAT, Production for billable jobs only.

- Set Username and Password as provided by Avilinga.

- Click Check Credentials and Continue.

9. Continue to configure Basic as follows:

- Set Default Cost Centre from cost centers associated with your Avilinga AEM API user.

- Set Default Turnaround from options on your Avilinga account.

- Set Default Workflow from options on your Avilinga account. 

Note: for testing and UAT please select Machine Translation only.

- Set Default Quote Approval as required.

- Set Send reference data with content for translation as required.

Note: sends preview image of pages to Avilinga, but increases AEM project creation overhead and upload package size.

- Recommended setting for Auto-launch from References is ON.

- Recommended setting for Auto-fetch translations is ON.

Link: learn more about auto-fetch translations.

- Recommended setting for Auto-promote Launches of translations is ON.

- Recommended setting for Auto-delete Launches of translations after promotion is ON.

- Recommended setting for Delete AEM project after all languages completed is ON.

- Recommended setting for Send anonymous usage log data to help in resolving issues is ON. 

Link: learn more about logging.

- Recommended setting for Hide AEM native translation forms is ON.

- Ignore references on translation update by default option sets default state of the corresponding checkbox on the panels and dialog boxes while creating update-type translation jobs.

10. Adjust Service settings if necessary:

- Set Connection timeout value in seconds.

- Set Number of connection attempts value as integer.

- Set Pause between connection attempts value in seconds.

- Set Auto-fetch translations interval value in minutes.

- Set one or multiple values for Root path for content audit and component translation.

Note: this feature provides users with the ability to access the Avilinga Audit and Update Component on all child nodes of the set values.

- Set Force exclude i18n files to ON for AEM versions prior to 6.4.8.

Note: helps solve issues with i18n dictionary items on prior AEM versions.

- set Force page timestamp to ON for AEM versions prior to 6.4.8.

Note: helps solve issues with page translation updates on prior AEM versions.

- set Use Avilinga Rollout Config for promoting Launches to ON to make it possible to update translation of Title and Description of the page. 

Note: this option replaces the /libs/msm/launches/rolloutconfigs/launch/contentUpdate configuration node with /apps/msm/avilingalaunches/rolloutconfigs/launch/contentUpdate as changing nodes and properties under /libs is not recommended.  Link: learn more about title and description update issue

- Click on Save & Close.

11. If the Avilinga Auto-fetch translations option is set to ON (see above), disabling the native AEM TIF auto-retrieve feature is highly recommended. This will prevent collisions between Avilinga and AEM TIF fetchers.

- Navigate to /system/console/configMgr to open Web Console Configuration.

- Search for Translation Platform Configuration and click to edit.

- Set Scheduler Cron value to 59 59 23 31 12 ? 2099

- Set Scheduler Repeat Translation Cron value to 59 59 23 31 12 ? 2099

- Click Save.

Congratulations! Installation and configuration are now complete!

Custom content types

By default, all standard AEM page components are configured to be translated by any translation connector. If your site contains third-party non-standard components, use the Translation Rules editor to set additional translatable rules.

1. In Tools, General, go to Translation Configuration.

2. Select /content and click Edit.

3. Select General and add, delete or edit properties.

Note: all translatable page properties should be in the General section. Further reference: https://docs.adobe.com/content/help/en/ experience-manager-learn/sites/translation/ translation-rules-editor-technical-video-setup.html

Additional translation settings

Avilinga Translation Connector provides the way to set the maximum length of component properties that Avilinga should adhere to when translating pages. If you need length limits for the component properties, use the Avilinga Translation Features tool to set up the limits:

1. In Tools, General, go to Avilinga Translation Features. 

Note: Avilinga Translation Features Editor looks very similar to the AEM Translation Configuration Editor and provides a consistent method for editing the property settings.

2. On the Properties tab add new component and click the Add Component button or select existing component from the list below.

3. Select Component and add or delete properties.

Note: Use the General section to set property settings for all components in AEM.

4. On the References tab append properties to ignore during translation update into own component group or General group. 

Custom language mapping

Avilinga API accepts the following ISO standardized language codes by default:

  • ISO 639-1 example: de (German)
  • ISO 639-1 plus ISO 3166-1 alpha-2 separated by an underscore example: de_CH (Swiss German)
  • ISO 639-3 example: GSW (Swiss German)

Should your sites deviate from these standards you will need to set custom language mappings.

1. In Tools, General, go to Avilinga Translation Features:

2. Select Language mapping tab:

- Add or delete language mapping and click Save.

ISO 639: https://iso639-3.sil.org/code_tables/639/data ISO 3166: https://www.iso.org/iso-3166-country-codes.html

Create user group

Users in the Administrator group will automatically have all privileges required to launch and retrieve jobs.

For other users, an Avilinga user group with appropriate permissions must be set.

Note: you can skip this section and grant permissions for each user separately.

1. In Tools, Security, go to Groups.

2. Click on Create Group.

3. Configure Details as follows:

- Set ID as required (e.g. avilinga-translation).

- Set Name as required (e.g. Avilinga Translation).

- Set Description as required.

- Add Members to the group by selecting users or other groups.

Note: you can skip this step and add Members to the group later.

- Click Save & Close.

Grant user permissions

You can grant access to /conf node for each user separately or to the newly created avilinga-translation group.

1. Navigate to /crx/de/index.jsp on your AEM installation to open CRXDE:

- Select the /conf node. 

- Select the Access Control tab.

- Press the + button to add a New Entry.

2. Configure the New Entry as follows: 

- Set Principal to the previously defined Group ID (e.g. avilinga-translation)

- Set Type to Allow.

- Set Privileges to jcr:read.

- Click OK.

- Click Save All at the top left corner of the CRXDE screen.

Your Avilinga user group has now been correctly configured.

Note: each AEM user who is going to create and manage translation projects should belong to the projects-users or projects-administrators AEM group.

Please contact us if you have any questions.

Share access to translation projects

Users can share access to their projects in order to enable cross-user fetch and retrieval.

To activate this feature, create a Group with the ID avilinga-shared-access. All users who are members of this group will have access to fetch all newly created Avilinga projects.

Note: avilinga-shared-access is a reference ID for the Avilinga Translation Connector. Your Group ID must be named exactly in order for this feature to work. Link: learn more about creating a user group.

Auto replace hyperlinks

Adobe Experience Manager Translation Integration Framework automatically adapts relative hyperlinks in translated content to the target language. However, if you have absolute links in your content, they should be processed using Avilinga automatic hyperlink replacement feature. To set custom rules for automatic replacement:

1. In Tools, General, go to Avilinga Translation Features:

2. Select Auto replace URLs tab:

- Add or delete auto replace rules and click Save.

Note: use the {source_language} placeholder to identify the source language code. Note: use the {target_language} placeholder to identify the target language code. Note: It is possible to create as many rules as necessary for auto replacements.