Add a locale for Adaptive Forms based on Core Components supporting-new-locales-for-adaptive-forms-localization

URL Locale Selector ([locale]):

The system prioritizes the locale specified within the URL using the [locale] selector. This format allows caching for better performance.

Format: The URL follows this format: http:/[AEM Forms Server URL]/content/forms/af/[afName].[locale].html?wcmmode=disabled.

Example: https://[server]/content/forms/af/contact-us.hi.html renders the form in Hindi.

afAcceptLang Request Parameter:

To override the user’s browser locale, you can use the afAcceptLang parameter in the URL.

Example: https://[server]/forms/af/survey.ca-fr.html?afAcceptLang=ca-fr forces the form to render in Canadian French.

User’s Browser Locale (Accept-Language Header):

If no other locale is specified, AEM Forms considers the user’s browser locale sent using the Accept-Language header.

Open your command line or terminal window.

Navigate to the desired location on your machine where you want to store the repository (for example, /adaptive-forms-core-components).

Run the following command to clone the repository:

git clone https://github.com/adobe/aem-core-forms-components.git

This command downloads the repository and create a folder named aem-core-forms-components on your machine. Throughout this guide, we refer to this folder as the [Adaptive Forms Core Components repository].

Open the command line and choose a directory to store your AEM as a Cloud Service repository, such as /cloud-service-repository/.

Run the below command to clone the repository:

git clone https://git.cloudmanager.adobe.com/<organization-name>/<program id>/

To clone your Git repository, you need some information:

• Organization name: This identifies your team or project within Adobe Experience Manager as a Cloud Service (AEM as a Cloud Service).

• Program ID: This specifies the program associated with your repository.

• Credentials: You need a username and password (or a personal access token) to access the repository securely.

Where to find this information?

For step-by-step instructions on locating these details, refer to the Adobe Experience League article “Accessing Git”.

Your project is ready!

When the command completes successfully, you see a new folder created in your local directory. This folder is named after your program (for example, program-id). This folder contains all the files and code downloaded from your AEM as a Cloud Service Git repository.

Throughout this guide, we refer to this folder as the [AEMaaCS project directory].

Open the repository folder in an editor.

Locate the Guide Localization Service.cfg.json file. This file controls the locales supported by your AEM Forms application. You can edit this file to add a new locale.

• Existing file: If the file already exists, locate it within your AEM Forms project directory. The typical location is:

  code language-shell
  [AEMaaCS project directory]/ui.config/src/main/content/jcr_root/apps/<appid>/osgiconfig/config`.

  Replace <appid> with your project specific app ID. You can find <appid> for your AEM Project in the archetype.properties file.

  

• New file: If the file doesn’t exist, you need to create it in the same location mentioned above. Do not copy paste the name of the file from this document, rather manually type the name. The file name Guide Localization Service.cfg.json includes spaces. This is intentional and not a typo in the documentation.

  A sample file with the list of OOTB supported locales is:

  code language-none
  { "supportedLocales":[ "en", "fr", "de", "ja", "pt-br", "zh-cn", "zh-tw", "ko-kr", "it", "es" ] }

Add the locale code for your desired language to the file.

1. Use the List of ISO 639-1 codes to find the two-letter code representing your desired language.

2. Include the locale code to the Guide Localization Service.cfg.json file. Here are some examples:

   • Left-to-Right Languages:

     • English (United States): en-US
     • Spanish (Spain): es-ES
     • French (France): fr-FR

   • Right-to-Left Languages:

     • Arabic (United Arab Emirates): ar-ae
     • Hebrew: he (or iw for historical reference)
     • Farsi: fa

After making changes, ensure the Guide Localization Service.cfg.json file is formatted correctly as a valid JSON file. Errors in JSON formatting can prevent it from functioning properly. Save the file.

Locate the sample client library:

Within your local copy of the [Adaptive Forms Core Components repository], navigate to the following path:

    /aem-core-forms-components/it/apps/src/main/content/jcr_root/apps/forms-core-components-it/clientlibs

Copy and paste the library:

1. Copy the clientlib-it-custom-locale folder.

   

2. Navigate to the following directory within your [AEMaaCS project directory]:

   code language-none
   /ui.apps/src/main/content/jcr_root/apps/<app-id>/clientlib

   Important: Replace <app-id> with the actual ID of your application.

3. Paste the copied clientlib-it-custom-locale folder into this directory.

   

Update aemLangUrl path in languageinit.js

1. Navigate to the following directory within your [AEMaaCS project directory]:

   code language-none
   /ui.apps/src/main/content/jcr_root/apps/<app-id>/clientlib/clientlib-it-custom-locale/js

2. Open the languageinit.js file in your editor.

3. Locate the following line in the languageinit.js file:

   const aemLangUrl = /etc.clientlibs/forms-core-components-it/clientlibs/clientlib-it-custom-locale/resources/i18n/${lang}.json;

4. Replace forms-core-components-it with your <app-id> (actual ID of your application) in the above line.

   const aemLangUrl = '/etc.clientlibs/<app-id>/clientlibs/clientlib-it-custom-locale/resources/i18n/${lang}.json';

   

Navigate to the Locale Directory:

Within your [AEMaaCS project directory], navigate to the following path:

    /ui.apps/src/main/content/jcr_root/apps/<program-id>/clientlibs/clientlib-it-custom-locale/resources/i18n/

Important: Replace <program-id> with your actual application ID.

Locate the sample English language file:

AEM Forms provides a sample English locale file (.json) on GitHub.

The English language file includes the default set of strings for reference. Your locale-specific file should mimic the structure of the English language file.

For languages like Arabic, Hebrew, and Farsi, text reads from right to left (RTL) instead of left to right (LTR) like English. To ensure your forms display correctly in these languages, we recommend using our sample locale files as a guide. These files provide a reference for how to format text, dates, and other elements for RTL languages. You can find the sample locale files for:

• Arabic
• Hebrew
• Farsi

By leveraging these sample files, you can ensure your forms provide a seamless experience for users working in RTL languages.

Create your locale file:

1. Create a new .json file within the i18n directory.
2. Name the file using the appropriate locale code for your desired language (For example, fr-FR.json for French and ar-ae.json for Arabic). The structure of this file should mirror the English locale file.

Structure and Translation:

1. Open the newly created file in a text editor.

2. Replace the English values with the corresponding translations for your target language.

3. Once you’ve finished translating the strings, save the file.

Locate the configuration folder:

Navigate to the following directory in your [AEMaaCS project directory]:

/ui.content/src/main/content/jcr_root/etc

Create the necessary folders (if missing):

If the etc folder doesn’t exist within jcr_root folder, create it. Inside etc, create another folder named languages if it’s missing.

Create the locale configuration file:

Within the languages folder, create a new file named .content.xml. Do not copy paste the name of the file from this document, rather manually type the name.

Open this file and paste the following content, replacing [LOCALE_CODE] with the actual locale code (For example, ar-ae for Arabic).

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
      jcr:primaryType="nt:unstructured"
      languages="[de,es,fr,it,pt-br,zh-cn,zh-tw,ja,ko-kr,hi]"/>

WARNING: Do not replace the existing list. Instead, append your new locale code within square brackets, separated by commas, like this (using ar-ae as an example):

languages="[de,es,fr,it,pt-br,zh-cn,zh-tw,ja,ko-kr,hi,ar-ae]"

Include the New Folders in filter.xml:

Navigate to the /ui.content/src/main/content/meta-inf/vault/filter.xml file in your [AEMaaCS project directory].

Open the file and add the following line at the end:

<filter root="/etc/languages"/>

Save the file.