Translating Fields in Form Containers

Liferay DXP 2025.Q1+/Portal 7.4 GA132+

Important

Currently, this feature is behind a release feature flag (LPD-37927). Read Release Feature Flags for more information.

Localize text inputs in form containers directly in the Page Editor to provide multilingual support for Text, Long Text, and Rich Text fields. This ensures content aligns with users’ preferred languages, improving form usability and accessibility.

To translate fields in form containers,

Create a localizable custom object.
Add a Form Container fragment to a page and map it to the custom object.
Choose the fields to add to the fragment.

While selecting, refer to the Localizable column to identify which fields are localizable.
A prompt appears asking you to add a Localization Select fragment (1). If you skip this step, you can add it later from the Fragments and Widgets sidebar (2).

Tip

You can place the Localization Select fragment outside the form container.

Note

Adding a Localization Select fragment with missing or hidden localizable fields triggers an error message when attempting to publish the page.

With the Localization Select fragment, display translated fields in the page.

The Localization Select fragment switches languages and tracks the translation status of fields. Translated fields show a status of Translated (all fields localized), Not Translated (no localization), or Translating (number of translated fields compared to total fields).

Note

The Localization Select fragment evaluates all fields across all forms on the page. For example, two forms with four fields each result in a total of eight fields.

Note

When working with forms based on objects with different scopes, each object may have its own default language. In this case, the fragment applies the more restrictive scope. For example, if one object is scoped to the instance and another to the site, the site scope is used.

Configuring the Localization Select Fragment

You can adjust the fragment’s size and choose whether to display the language label. To configure the fragment,

Select the Localization Select fragment. The settings appear on the right under the General tab.
Click Size under Options to select the fragment’s size (normal or small).
Check Hide Language Label to hide the language code label and show only the language flag.

Display or hide the language code label using the Hide Language Label configuration.

Configuring Non-Localizable Field Behavior

You can control how non-localizable fields behave during translation workflows:

Select the Form Container fragment. The settings appear on the right under the General tab.
In the Unlocalizable Field State configuration, select an option: Disabled to prevent input in the field or Read Only to display the field without allowing edits.
Use the Unlocalizable Fields Message setting to add a message displayed over the fields.

Click the flag icon next to the message and select another language to localize it.

Adapting Localizable Input Fragments

When developing input fragments that support translations, you must manage localized input fields dynamically.

A typical input fragment uses a single <input> field:

<input name="description" type="text" value="defaultValue">

For translations, create additional <input> elements for each language:

<input name="description" type="text" value="defaultValue">
<input name="description_en_US" type="text" value="englishValue">
<input name="description_es_ES" type="text" value="spanishValue">
<input name="description_fr_FR" type="text" value="frenchValue">

Detecting When to Create Localized Inputs

The fragment must know when to create these additional inputs and update their values. This is achieved through specific events:

Detecting Language Changes

When the user switches languages in the localization drop-down, the localizationSelect:localeChanged event is triggered. Your fragment must listen for this event and update its behavior to store inputs for the selected language.
```
Liferay.on('localizationSelect:localeChanged', (event) => {
});
```
For example, set input focus for the selected language:
```
Liferay.on('localizationSelect:localeChanged', (event) => {
   const selectedLanguageId = event.languageId;
   document.querySelector(`[name="description_${selectedLanguageId}"]`).focus();
});
```
From this point onward, any user input should be stored in the appropriate language-specific input field.
Notifying Translation Updates

When the user modifies the input for a specific language, your fragment should notify the localization drop-down that the translation has been updated.
```
Liferay.fire('localizationSelect:updateTranslationStatus', { languageId: languageId });
```
For example,
```
Liferay.fire('localizationSelect:updateTranslationStatus', { languageId: 'es_ES' });
```
This ensures the drop-down reflects the change in translation status.

By listening for localizationSelect:localeChanged, your fragment detects language changes and ensures user input is correctly stored in language-specific input fields. When the input is updated, firing the localizationSelect:updateTranslationStatus event keeps the localization drop-down synchronized.
Context Variables

Fragments can use these variables to manage inputs:
- localized: Indicates if a field supports localization (true or false).
- valueI18n: Stores translations indexed by language ID.
- attributes: For non-localizable fields, the attributes include:
  - unlocalizedFieldsMessage: Displays messages for non-localizable fields (default: [name-of-the-field] cannot be localized).
  - unlocalizedFieldsState: Configures the state as disabled or read-only.
Backend Expectations

Ensure localized inputs follow the format inputName_languageCode (e.g., inputName_en_US and inputName_fr_FR) for each language.