5.4 Multi-Language & Internationalization

5.4 Multi-Language & Internationalization

Exam Focus: Multi-language architecture is a key competency tested on the Intermediate Developer exam. You must understand how project languages are structured, identify the critical distinction between Translatable Texts and System Texts, explain the fallback mechanisms when translations are incomplete, manage translation workflows using the Batch Translate and Excel export/import tools, internationalize enumeration captions without breaking business logic, and configure Right-to-Left (RTL) layout rendering.

Global enterprises deploy software across diverse geographic territories, requiring applications that fluently adapt to local languages, numbering conventions, and cultural layouts. The Mendix platform provides a comprehensive internationalization (i18n) and localization (l10n) engine deeply integrated into Studio Pro and the client runtime.

---

Project Language Configuration & Architecture

Multi-language capabilities are managed in App Settings > Languages in Studio Pro (older material calls this Project Settings — Mendix renamed Project to App in Studio Pro 9). The language architecture revolves around two foundational concepts:

+-----------------------------------------------------------------------------+
|                        Project Language Hierarchy                           |
+-----------------------------------------------------------------------------+
| Default Language  --> Authoring baseline & runtime fallback (e.g., en_US)   |
| Active Language   --> Currently selected editing language in Studio Pro      |
| Secondary Langs   --> Localized target languages (e.g., nl_NL, de_DE, ar_SA) |
+-----------------------------------------------------------------------------+

1. The Default Language

• Definition: Exactly one language in the app is designated as the Default Language, marked as such on the Languages tab of App Settings.
• Authoring Baseline: When a developer models a new page, creates an enumeration, or writes a validation message, the text is initially authored in the default language.
• Runtime Fallback: If a user runs the application in a secondary language (such as French) and encounters a UI element whose French translation was left blank, the Mendix runtime falls back to the Default Language text. This prevents empty labels and missing button captions.

2. The Active Language in Studio Pro

• At design time, developers can toggle the Active Language via the language selector located in the bottom status bar of Studio Pro.
• Switching the active language changes the design-time canvas: all page labels, button text, and menu captions switch to show the text defined for that specific language. Untranslated elements are visually highlighted (typically preceded by a yellow warning marker or question mark) to alert developers to missing copy.

Translatable Texts vs. System Texts

A critical distinction tested on the exam is the functional difference between Translatable Texts and System Texts:

Why System Texts Require Explicit Translation

When a team adds a new language (e.g., Japanese), they often focus entirely on translating page labels. However, if they fail to translate the System Texts, end users will encounter an awkward hybrid experience: while form labels appear in Japanese, login errors, session timeouts, and pagination buttons will abruptly appear in English.

---

Enumeration Internationalization: Key vs. Caption

Enumerations represent fixed lists of values (e.g., OrderPriority: Low, Medium, High, Critical). In Mendix, enumerations strictly separate their programmatic identifiers from their presentation strings:

+-----------------------------------------------------------------------------+
|                          Enumeration Architecture                           |
+-----------------------------------------------------------------------------+
| Name / Key (Immutable):   'InReview'                                        |
|   - Used in Database records, XPath queries, Microflow decisions, and APIs  |
|                                                                             |
| Captions (Localized):                                                       |
|   - English (Default):     "Under Review"                                   |
|   - Dutch (nl_NL):         "In Beoordeling"                                 |
|   - German (de_DE):        "In Prüfung"                                     |
|   - French (fr_FR):        "En Cours d'Examen"                               |
+-----------------------------------------------------------------------------+

• The Rule of Logic Independence: Microflows, nanoflows, rules, and XPath constraints always reference the enumeration Name (the internal key). They never evaluate the caption.
• Caption Localization: Developers define localized captions for every language in the enumeration editor. When a drop-down or data grid renders an enumeration attribute, Mendix looks up the caption corresponding to the logged-in user's active session language without requiring conditional microflows.

---

Translation Workflows: Tools and Operations

Mendix Studio Pro provides built-in tools to streamline enterprise translation projects:

1. Batch Translate Tool

• Located under Language > Batch Translate.
• Allows developers to find all occurrences of a specific phrase across the entire project (or within specific modules) and translate them simultaneously.
• For example, if the word "Save" appears on two hundred buttons, Batch Translate replaces all occurrences with "Opslaan" (Dutch) in a single operation.

2. Translatable Texts Overview

• Located under Language > Translatable Texts.
• Displays a comprehensive, searchable grid of all strings in the application, comparing the source language against the target language.
• Includes filters to identify Untranslated texts, allowing translators to rapidly locate incomplete copy.

3. External Translation via Excel (.xlsx)

• Enterprise translation projects are typically outsourced to professional linguistic agencies who do not have access to Studio Pro.
• Developers navigate to Language > Export Translation File to generate an Excel spreadsheet containing source strings, target strings, and unique platform keys.
• Translators populate the target column in Excel.
• The developer re-imports the spreadsheet via Language > Import Translation File. Mendix matches rows by their cryptographic string keys and populates the project model without risk of breaking application logic.

---

Runtime Language Switching & Fallback Mechanics

How does an application know which language to display to an active user?

1. User Account Language Association: Every user entity specializing Administration.Account or System.User maintains a reference to System.Language (System.User_Language). When a user logs in, the client runtime initializes the UI in the language linked to their user record.
2. Language Switcher Widget: Developers can place the Language Selector widget into navigation bars or page headers. When a user selects a different language from the drop-down, Mendix immediately updates their active session language and redraws the client UI.
3. Anonymous Users: For unauthenticated public visitors, Mendix inspects the browser's HTTP Accept-Language header. If the project supports that language, it renders in that locale; otherwise, it falls back to the project Default Language.

---

Right-to-Left (RTL) Support & Bi-Directional Layouts

Languages such as Arabic (ar_SA), Hebrew (he_IL), Farsi, and Urdu read from right to left. Mendix Atlas UI provides native, automated RTL adaptation:

• Configuration: When a project includes an RTL language, selecting it sets the HTML document root attribute to dir="rtl".
• Atlas UI Grid Mirroring: Flexbox layout grids automatically invert their horizontal axis: column 1 appears on the far right, and subsequent columns flow toward the left.
• Navigation & Icons: Left-anchored sidebars automatically move to the right side of the screen. Directional icons (such as "Next" back-and-forward arrows) mirror horizontally, while direction-neutral icons (such as search magnifying glasses or user avatars) maintain their orientation.