Supporting new locales for Adaptive Forms localization supporting-new-locales-for-adaptive-forms-localization
Adobe recommends using the modern and extensible data capture Core Componentsfor creating new Adaptive Formsor adding Adaptive Forms to AEM Sites pages. These components represent a significant advancement in Adaptive Forms creation, ensuring impressive user experiences. This article describes older approach to author Adaptive Forms using foundation components.
AEM Forms provide out of the box support for English (en), Spanish (es), French (fr), Italian (it), German (de), Japanese (ja), Portuguese-Brazilian (pt-BR), Chinese (zh-CN), Chinese-Taiwan (zh-TW), and Korean (ko-KR) locales. You can add support for more locales also, like Hindi(hi_IN).
Understanding locale dictionaries about-locale-dictionaries
The localization of adaptive forms relies on two types of locale dictionaries:
-
Form-specific dictionary Contains strings used in adaptive forms. For example, labels, field names, error messages, help descriptions. It is managed as a set of XLIFF files for each locale and you can access it at
[author-instance]/libs/cq/i18n/gui/translator.html
. -
Global dictionaries There are two global dictionaries, managed as JSON objects, in the AEM client library. These dictionaries contain default error messages, month names, currency symbols, date and time patterns, and so on. You can find these dictionaries at
[author-instance]/libs/fd/xfaforms/clientlibs/I18N
. These locations contain separate folders for each locale. Because global dictionaries are not updated frequently, keeping separate JavaScript files for each locale enables browsers to cache them and reduce network bandwidth usage when accessing different adaptive forms on the same server.
Add support for new locales add-support-for-new-locales
Perform the following steps to add support for a new locale:
Add localization support for non-supported locales add-localization-support-for-non-supported-locales
AEM Forms currently support localization of Adaptive Forms content in English (en), Spanish (es), French (fr), Italian (it), German (de), Japanese (ja), Portuguese-Brazilian (pt-BR), Chinese (zh-CN), Chinese-Taiwan (zh-TW), and Korean (ko-KR) locales.
To add support for a new locale at the Adaptive Forms runtime:
1. Clone the repository clone-the-repository
- From the command line, navigate to where you would like to clone the Forms Cloud Service repository.
- Execute the command that you retrieved from Cloud Manager. It is similar to
git clone https://git.cloudmanager.adobe.com/<my-org>/<my-program>/
. - Use the git user name and password to clone the repository.
- Open the cloned Forms Cloud Service repository folder in your preferred editor.
2. Add a locale to the Guide Localization service add-a-locale-to-the-guide-localization-service
-
Locate the
Guide Localization Service.cfg.json
file and add the locale you want to add to the list of supported locales.note note NOTE Create a file with the name as Guide Localization Service.cfg.json
file, if already not present.
3. Add locale-name specific folder client library add-locale-name-specific-folder
- In UI.content folder, create
etc/clientlibs
folder. - Further create a folder named as
locale-name
underetc/clientlibs
to serve as a container for xfa and af clientlibs.
3.1 Add XFA client library for a locale in a locale-name folder
Create a node named as [locale-name]_xfa
and type as cq:ClientLibraryFolder
under etc/clientlibs/locale_name
, with category xfaforms.I18N.<locale>
, and add the following files:
- I18N.js defining
xfalib.locale.Strings
for the<locale>
as defined in/etc/clientlibs/fd/xfaforms/I18N/ja/I18N
. - js.txt containing the following:
/libs/fd/xfaforms/clientlibs/I18N/Namespace.js
I18N.js
/etc/clientlibs/fd/xfaforms/I18N/LogMessages.js
3.2. Add Adaptive Form client library for a locale locale-name folder
-
Create a node named as
[locale-name]_af
and type ascq:ClientLibraryFolder
underetc/clientlibs/locale_name
, with category asguides.I18N.<locale>
and dependencies asxfaforms.3rdparty
,xfaforms.I18N.<locale>
andguide.common
. -
Create a folder named as
javascript
and add the following files:- i18n.js defining
guidelib.i18n
, having patterns of “calendarSymbols”,datePatterns
,timePatterns
,dateTimeSymbols
,numberPatterns
,numberSymbols
,currencySymbols
,typefaces
for the<locale>
as per the XFA specifications described in Locale Set Specification. - LogMessages.js defining
guidelib.i18n.strings
andguidelib.i18n.LogMessages
for the<locale>
as defined in/etc/clientlibs/fd/af/I18N/fr/javascript/LogMessages.js
.
- i18n.js defining
-
Add js.txt containing the following:
code language-none i18n.js LogMessages.js
4. Add locale support for the dictionary add-locale-support-for-the-dictionary
Perform this step only if the <locale>
you are adding is not among en
, de
, es
, fr
, it
, pt-br
, zh-cn
, zh-tw
, ja
, ko-kr
.
-
Create a folder
languages
underetc
, if not present already. -
Add a multi-valued string property
languages
to the node, if not present already. -
Add the
<locale-name>
default locale valuesde
,es
,fr
,it
,pt-br
,zh-cn
,zh-tw
,ja
,ko-kr
, if not present already. -
Add the
<locale>
to the values of thelanguages
property of/etc/languages
. -
Add the created folders in the
filter.xml
under etc/META-INF/[folder hierarchy] as:code language-none <filter root="/etc/clientlibs/[locale-name]"/> <filter root="/etc/languages"/>
Before committing the changes into the AEM Git repository, you need to access your Git repository information.
5. Commit the changes in the repository and deploy the pipeline commit-changes-in-repo-deploy-pipeline
Commit the changes to the GIT repository after adding a locale support. Deploy your code using the full stack pipeline. Learn how to set up a pipeline to add new locale support.
Once the pipeline is complete, the newly added locale appears in the AEM environment.
Use added locale in Adaptive Forms use-added-locale-in-af
Perform the following steps to use and render an Adaptive Form using newly added locale:
- Log in to your AEM author instance.
- Go to Forms > Forms and Documents.
- Select an Adaptive Form and click Add Dictionary and Add Dictionary To Translation Project wizard appears.
- Specify the Project Title and select the Target Languages from the drop-down menu in the Add Dictionary To Translation Project wizard.
- Click Done and execute the created translation project.
- Select an Adaptive Form and click Preview as HTML.
- Add
&afAcceptLang=<locale-name>
in the URL of an Adaptive Form. - Refresh the page and Adaptive Form is rendered in a specified locale.
There are two methods to identify the locale of an Adaptive Form. When an Adaptive Form is rendered, it identifies the requested locale by:
-
Retrieving the
[local]
selector in the adaptive form URL. The format of the URL ishttp://host:[port]/content/forms/af/[afName].[locale].html?wcmmode=disabled
. Using[local]
selector allows caching an Adaptive Form. -
Retrieving the following parameters in the listed order:
-
Request parameter
afAcceptLang
To override the browser locale of users, you can pass theafAcceptLang
request parameter to force the locale. For example, the following URL forces to render the form in Canadian-French locale:https://'[server]:[port]'/<contextPath>/<formFolder>/<formName>.html?wcmmode=disabled&afAcceptLang=ca-fr
-
The browser locale set for the user, which is specified in the request using the
Accept-Language
header.
-
If a client library for the requested locale does not exist, it checks for a client library for the language code present in the locale. For example, if the requested locale is en_ZA
(South African English) and the client library for en_ZA
does not exist, the adaptive form uses the client library for en
(English) language, if it exists. However, if none of them exist, the Adaptive Form uses the dictionary for en
locale.
Once the locale is identified, the Adaptive Form picks the form-specific dictionary. If the form-specific dictionary for the requested locale is not found, it uses the dictionary for the language in which Adaptive Form is authored.
If no locale information is present, Adaptive Form is delivered in the original language of the form. The original language is the language used while developing the Adaptive Form.
Get a sample client library to add support for new locale. You need to change the content of the folder in the required locale.
Best Practices to support for new localization best-practices
-
Adobe recommends creating a translation project after creating an Adaptive Form.
-
When new fields are added in an existing Adaptive Form:
- For machine translation: Re-create the dictionary and run the translation project. Fields added to an Adaptive Form after creating a translation project remain untranslated.
- For human translation: Export the dictionary through
[server:port]/libs/cq/i18n/gui/translator.html
. Update the dictionary for the newly added fields and upload it.
See Also see-also
- Create an AEM Adaptive Form
- Add an AEM Adaptive Form to AEM Sites page
- Apply themes to an AEM Adaptive Form
- Add components to an AEM Adaptive Form
- Use CAPTCHA in an AEM Adaptive Form
- Generate PDF version (DoR) of an AEM Adaptive Form
- Translate an AEM Adaptive Form
- Enable Adobe Analytics for an Adaptive Form to track form usage
- Connect Adaptive Form to Microsoft SharePoint
- Connect Adaptive Form to Microsoft Power Automate
- Connect Adaptive Form to Microsoft OneDrive
- Connect Adaptive Form to Microsoft Azure Blob Storage
- Connect Adaptive Form to Salesforce
- Use Adobe Sign in an AEM Adaptive Form
- Add a new locale for an Adaptive Form
- Send Adaptive Form data to a database
- Send Adaptive Form data to a REST endpoint
- Send Adaptive Form data to AEM Workflow
- Use Forms Portal to list AEM Adaptive Forms on an AEM website