Skip to main content

tSM Localization

The tSM Localization feature provides comprehensive support for translating both static and dynamic application content into multiple languages. By default, English and Czech localizations are available out of the box, and the framework can be extended to support additional languages as needed.

1. Overview​

  • Purpose: Enable multi-language support across the entire application—from the user interface to backend data models—ensuring users can interact with the system in their preferred language.
  • Out-of-the-Box Languages: English (en) and Czech (cs).
  • Extensibility: Additional languages can be easily added by creating the relevant localization files and configuration.

2. UI Localization​

In the user interface, text and labels are automatically translated based on the user’s selected language. Localization resource files for the UI are stored under lang/ui, and each language has its own ui_<language_code>.properties file.

Key Features​

  1. tSM Core - Message bundles
    Labels, buttons, messages, and other static texts are retrieved from message bundles specific to each language.

  2. tSM Form Designer - Extensible UI Palette
    Within the tSM Form Designer configuration palette, a dedicated "localization" button allows administrators or editors to provide localized versions of various fields. Once clicked, a form is displayed for entering translations for each supported language.

  3. Default vs. Custom

    • If a customization provides its own localization files, these override the default messages shipped with the core product.
    • This makes it possible to tailor UI texts for specific customer needs without modifying the core resource files.

3. Backend Localization​

3.1 Language Detection​

The backend determines the user’s preferred language by reading the App-Language HTTP header. All localized responses (e.g., error messages, labels, entity names) are selected accordingly.

3.2 Message Bundles​

  • File Structure

    • Static texts are managed in lang/messages (for general messages) and lang/ui (for UI-related messages).
    • Each language has a separate properties file. For instance:
      • messages_en.properties
      • messages_cs.properties

  • Resolution Priority

    1. Customized properties in the microservice (if provided).
    2. Default properties in the core product.

3.3 Usage​

Localized text in the backend is typically used for:

  • Entity Names and Descriptions
    e.g., rendering a human-readable status in a Public API (model.CustomerPublic.status).
  • Enum Values
    e.g., localizing states such as active / inactive.
  • Core UI Text Access
    All core UI localization files are also exported into tsm-commons/src/main/resources/lang/ui_<language_code>.properties, making them available to backend processes that require the same translations.

4. Data-Level Localization​

4.1 localizationData property​

For entities requiring localized content (e.g., a “Priority” entity with fields name and description), a dedicated property named localizationData is introduced. This column stores translations keyed by language code:

{
  "id": "967cc206-c95a-40ba-9173-8cacc5e945e9",
  "code": "HIGH",
  "name": "High",
  "description": "<p>High priority</p>",
  "localizationData": {
    "cs": {
      "name": "Vysoká",
      "description": "Vysoká priorita"
    },
    "de": {
      "name": "Hoch",
      "description": "Hohe Priorität"
    }
  }
}

Updating Localized Data​

  • PUT: Provide all localization entries for a complete overwrite.
  • PATCH: Update only a subset of languages or fields while leaving the rest unchanged.

5. Configuration and Forms​

  • Form Definitions
    Each form definition in the system can include a localizationData object—mirroring the JSONB column in the database—to store and retrieve localized text.
  • Localization Editing
    When configuring forms, a dedicated button is displayed next to any text field. Clicking it opens a dialog where localized texts for multiple languages can be entered.

6. Dynamic Attributes and Characteristics​

Some entities may have dynamic, per-attribute localizations (e.g., a characteristic or metadata field displayed in different languages). Where possible, these follow the same localizationData model, though the structure may vary depending on specific business requirements. If a global entity-level localizationData is insufficient for highly dynamic attributes, dedicated localized sub-fields or a more granular approach may be employed.

7. Elasticsearch Considerations​

If the Entity leverages Elasticsearch for full-text search, the following pattern applies:

  • Code Lists
    To avoid confusion and redundancy, localized code list values are typically not indexed directly in Elasticsearch. A common approach is to index a code (e.g., HIGH) and then refer back to the database or a message bundle for localized display values.
  • Searching by Localized Fields
    Search involves a multi-step lookup:
    1. Identify matching code list entries via a dedicated code or reference.
    2. Filter or present results using the localized text.

Future enhancements may introduce more robust indexing strategies for localized fields if business requirements demand direct full-text queries in multiple languages.

10. Summary​

tSM Localization is a flexible, extensible system designed to cover all aspects of multi-language support within the application, including:

  1. Static Text (UI labels, messages, system outputs)
  2. Dynamic Data (entity names, descriptions, code lists, catalogs, and custom attributes)
  3. Seamless Integration with both frontend and backend, ensuring that localized values can be easily accessed, updated, and managed.