(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Translation Input

Overview

• The Translation Input component is a form control for entering and managing multilingual text.
• It provides a simple interface with integrated language selection.
• It supports internationalization where text values must exist in multiple languages.
• Common use cases include product descriptions, error messages, and user-facing text.

Specs

Tokens

Structure

(Configured in General Properties)

• displayName - Sets the display name of the component shown in the structure panel. For example, "Product Name Translations" allows for easy identification of the component's purpose in the application structure, making it easier for developers and content editors to locate this specific translation field.

(Configured in Visual Properties)

• saveInLocalStorage - Determines whether the component's entered translations are preserved in local storage between sessions. When enabled, translation data persists between page reloads, improving user experience for complex multilingual forms that may take time to complete.

(Configured in Non-Visual Properties)

• dataField - Defines the field name that will be used when submitting form data. For example, setting to "productName" ensures the translations are submitted with this field name in the form data object, making it clear what the translations represent on the server side.
• controlsRequestType - Specifies how the translation data is sent in HTTP requests: 'BODY', 'HEADER', or 'PATH'. For example, setting to "BODY" includes the translations in the request body, which is standard for most form submissions with multilingual data.

(Configured in Visibility)

• displayConditions - Defines conditions for displaying the component. This allows showing or hiding the translation input based on complex rules involving other form values, user roles, or application state.

Styling

(Configured in Visual Properties)

• labelTranslations - Sets the label text displayed above the input field, with support for multiple languages. For example, {"en-US": "Enter Product Name", "de-DE": "Produktname eingeben"} ensures proper localization of the field label based on the user's language settings.
• paddingClass - Configures spacing around the translation input component using CSS classes. For example, "p-4" adds medium padding on all sides of the component to improve visual spacing within its container.
• defaultValue - Sets the initial translation values that will be used when the form is reset. For example, setting to {"en-US": "Default Product", "de-DE": "Standardprodukt"} would pre-populate these translations when a form is first loaded or reset.

Actions & Variants

(Configured in Visual Properties — Variants)

• hidden - Controls whether the component is visible in the form. When set to true, the component remains in the form structure but is not displayed, which is useful for conditional translation fields that should only appear in specific scenarios.
• readonly - Controls whether the translations can be modified by users. When set to true, the translation field displays the existing translations but prevents changes, which is useful for reference-only scenarios or when translations are managed through another system.

(Configured in Event Actions Properties)

• events - Configures the events that the component can trigger and respond to:
• ON_VALUE_CHANGE - Triggered when any translation value changes. Can be used to perform immediate actions based on translation changes, such as updating preview text or validating language-specific content.
• ON_INIT_BASED_ON_USER_VIEW - Triggered specifically when the component initializes in user view mode rather than edit mode.
• ON_INIT - Triggered when the translation input component is initialized. Can be used to perform setup operations like loading default translations from external sources.
• ON_DESTROY - Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.

Tests

(Configured in Testing Hooks Properties)

• id - Specifies a unique identifier for the component used for programmatic access. For example, "productNameTranslations" enables targeted manipulation of this specific translation field.
• dataTestId - Sets the testing hook ID for automated testing. For example, setting to "product-name-translations" allows test scripts to reliably locate this component for automated testing of multilingual content.
• enableAsHotspot - Enables the component as a guided tour hotspot. When enabled, the translation input can be highlighted during onboarding or tutorial flows to explain its multilingual functionality to new users.
• guidedTourHotSpotTitle - Sets the title for the guided tour hotspot, supporting translations. For example, {"en-US": "Product Name Translations", "de-DE": "Produktname Übersetzungen"} provides clear identification during guided tours.
• guidedTourHotSpotDescription - Sets the description for the guided tour hotspot, supporting translations. For example, {"en-US": "Enter product names in multiple languages", "de-DE": "Geben Sie Produktnamen in verschiedenen Sprachen ein"} provides detailed instructions during guided tours.

Validation

(Configured in Validation Properties)

• validation - Configures validation rules for the translation input field. This allows you to set requirements such as mandatory translations for specific languages or character limits. For example, setting required validation ensures that at least one language translation is provided before the form can be submitted.

Authorization

(Configured in Authorization Properties)

• authorizationDisable - Specifies a policy set that determines when the component should be disabled based on user permissions. For example, setting to "translatorOnlyPolicy" will disable the translation input for users who don't have translation privileges according to the specified policy.
• visibilityPolicySetId - Determines the visibility of the component based on specified policy sets. For example, setting to "contentEditorsPolicy" restricts the translation input visibility to users with content editing privileges.

Guidelines

Usage

• Capture multilingual copy and bind it for submission via dataField and controlsRequestType (e.g., send in BODY).
• Localize the field label with labelTranslations.
• Pre-populate known strings with defaultValue.
• Preserve in-progress work across reloads with saveInLocalStorage.

Sizing & Layout

• Adjust spacing around the control using paddingClass.
• Keep labels concise in labelTranslations to maintain compact layout.

States & Feedback

• Visibility: Control presence with hidden and displayConditions.
• Editability: Present as view-only with readonly.
• Validity: Enforce required locales/limits with validation; react to changes via events.ON_VALUE_CHANGE.

Data-Driven / Conditional Behavior

• Specify required locales and character limits with validation.
• Establish consistent baselines with defaultValue.

Visibility & Authorization

• Gate visibility with visibilityPolicySetId.
• When users may view but not edit, disable interaction with authorizationDisable and clarify state via readonly.

Content & Localization

• Provide localized onboarding for tours with enableAsHotspot, guidedTourHotSpotTitle, and guidedTourHotSpotDescription.
• Ensure serialized output keys are correct using dataField and controlsRequestType.

Dos & Don’ts

Accessibility

• Provide clear, localized labels using labelTranslations.
• Expose non-editable state programmatically with readonly (and disable interaction via authorizationDisable when appropriate).
• Enforce required locales and constraints through validation to avoid ambiguous partial entries.
• Localize tour guidance using guidedTourHotSpotTitle and guidedTourHotSpotDescription.
• Avoid color-only cues; rely on rule-based feedback via validation and clear text via labelTranslations.
• Reduce cognitive load by hiding irrelevant inputs with displayConditions and seeding predictable values via defaultValue.
• Maintain readability in dense layouts using paddingClass.