Internationalizing Components

Last update: April 17, 2024

CREATED FOR:

  • Developer

Internationalize your components and dialogs so that their UI strings can be presented in different languages. Components that are designed for internationalization enable UI strings to be externalized, translated, then imported to the repository. At runtime, the user’s language preferences or the page locale determines which language is displayed in the UI.

chlimage_1-9

Use the following process to internationalize your components and provide the UI in different languages:

  1. Implement your components using code that internationalizes strings. Your code identifies the strings to translate, and selects the language to present at runtime.

  2. Create dictionaries and add the English strings to translate.

  3. Export the dictionary to XLIFF format, translate the strings, then import the XLIFF files back into AEM. Alternatively, you can manally add translations to the dictionary.

  4. Incorporate the dictionary into the release management process of your application.

NOTE
The methods described here for internationalizing components is meant for translating static strings. When component strings are expected to change you should use conventional translation workflows. For example, when authors can edit a UI string using properties in the Edit dialog of a component, you should not use a language dictionary to internationalize the string.

Language Dictionaries

The AEM internationalization framework uses dictionaries in the repository to store English strings and their translations in other languages. The framework uses English as the default language. Strings are identified using their English version. Typically, internationalization frameworks use alphanumeric IDs for UI strings. Using the English version of the string as the ID has several advantages:

  • Code is easy to read.
  • The default language is always available.

Localized strings can be stored in several dictionaries in the repository. AEM system dictionaries are located below the /libs node. You can create dictionaries for your components below the /apps node. The AEM internationalization framework combines the dictionaries and makes them available in Sling as a single ResourceBundle object. When components are rendered, they retrieve translated strings from the resource bundle. The combined dictionaries are also deployed on the web server in JSON format to provide translated strings to JavaScript code in web pages.

Also, the Translation tool enables you to manage all dictionaries from one central location.

chlimage_1-10

NOTE
Do not modify the AEM system dictionaries that are located below the /libs node.

Overlaying Strings in System Dictionaries

Strings in dictionaries below the /apps node override duplicate strings in dictionaries that are below the /libs node. If your components use strings that are included in the AEM system dictionaries, duplicate the string in your own dictionary. All components will use the strings from your dictionary.

Note that you cannot predict which translation is used when strings are duplicated in dictionaries that are all located below the /apps node.

Experience Manager


B2B Reimagined: Transforming Go-to-Market Strategies for Profitable Growth

Online | Strategy Keynote | General Audience

B2B brands are facing a digital revolution. Buyers expect hyper-relevant content and self-service, while internally AI is transforming...

Wed, Mar 19, 1:00 PM PDT (8:00 PM UTC)

Register

The True Cost of a Failed Implementation

Online | Session | General Audience

A failed implementation isn’t just an inconvenience — it costs real revenue. Poor execution and misaligned tools disrupt pipelines,...

Wed, Mar 19, 2:00 PM PDT (9:00 PM UTC)

Register

Connect with Experience League at Summit!

Get front-row access to top sessions, hands-on activities, and networking—wherever you are!

Learn more

Register now