You can localize text in your MDriven application by adding the SysTranslation model pattern and calling the Translate OCL operator from actions and ViewModels; this page is for modelers and administrators who maintain translated UI text and culture settings.

What localization does

Localization has two related responsibilities:

• Translation selects translated UI text from your model according to a language code, such as en-US or sv-SE.
• Culture controls how the UI renders culture-dependent values such as dates and numbers. For example, culture can determine whether a decimal value is displayed with a comma or a point as its decimal separator.

MDriven uses translations stored as model objects. When a requested translation does not exist, it keeps the original text. This makes it safe to introduce translation calls before every language has been translated.

Add the translation model pattern

Your model must contain the recognized SysTranslation pattern. The pattern contains these classes:

• SysTranslatable, with a Value that holds the original text.
• SysTranslation, which holds a translated value and connects a translatable text to a language.
• SysTranslationLanguage, with a Code that identifies the language.

The classes and their associations must follow the established pattern so that MDriven can discover and use them. A mergeable example of the localization and translation architectural pattern is listed under Model Examples.

For example, to translate the UI text Save for Swedish users:

1. Create a SysTranslatable object whose Value is Save.
2. Create or select a SysTranslationLanguage with Code sv-SE.
3. Create a SysTranslation connected to both objects and give it the translated value Spara.
4. Restart the system, or reset the translation cache as described in Make new translations visible.

Install the translation service

Install the IMDrivenUITranslation service so MDriven can use the translation objects in the model:

MDriven.Translation.MDrivenUITranslationImpl.Install(ecoServiceProvider);

Newer versions of MDriven Turnkey install this service already. If you run another host or have customized startup code, ensure that this installation is performed during startup.

Translate text in OCL

Use the String.translate operator in OCL to look up a translated value. See Translate for the operator reference.

Translate to the current default language

Pass an empty string to translate using the current default language:

'Translate this text'.Translate('')

In Turnkey, the default language is normally set from the user's browser language, for example en-US or sv-SE.

Translate to a specific language

Pass a language code when you need a specific target language:

'Translate this'.Translate('sv-SE')

This expression looks for:

1. A SysTranslatable whose Value equals Translate this.
2. A related SysTranslation whose language has Code sv-SE.

If it finds a matching translation, it returns the SysTranslation value. If it does not find one, it returns Translate this unchanged.

Force the default language

You can override the default language in an action:

'Whatever'.Translate('DEFAULT=sv-SE')

Use this when the application must use a known default rather than the browser-provided language.

Discover text that needs translation

Creating SysTranslatable objects one at a time is not practical for a large application. MDriven records complete translation misses that occur while the application runs. Call SPOOLMISSED to create SysTranslatable objects for the misses recorded since startup or since the previous spool operation:

'Whatever'.Translate('SPOOLMISSED')

A practical translator workflow is:

1. Run the relevant views and actions so that the application encounters the UI text to translate.
2. Provide an action for an administrator to execute 'Whatever'.Translate('SPOOLMISSED').
3. Open a maintenance ViewModel over the SysTranslatable objects created by the spool operation.
4. Add SysTranslation objects for each required SysTranslationLanguage.
5. Execute RESETCACHE so that users can see the new translations without a system restart.

Only text encountered by the application can be included in the collected misses. Exercise the views, navigation paths, and actions whose text you want to maintain.

Make new translations visible

MDriven builds the translation dictionaries at system startup. A restart therefore makes new translations available, but a restart is often unsuitable while translators are working.

Call RESETCACHE after editing translations:

'Whatever'.Translate('RESETCACHE')

This resets cached application pages that may contain translated text. The next request rebuilds those pages and uses the updated translations.

When testing browser-selected languages, ensure that the browser is configured to send the language for web pages, not only a display-language preference. Browsers can send language and culture information separately, so test the target browser and language configuration used by your users.

Map detected languages to a preferred language

By default, the user's detected browser language is used. You can override that mapping by adding this static method on SysTranslationLanguage:

CheckLanguageMapping(input:String):String

MDriven calls this method when it detects the user's language. Return the language code that your application should use.

For example, if the model is authored in Swedish, English translations are available, and French users should receive English rather than the original Swedish text:

if input.contains('fr') then
  'en'
else
  input
endif

Keep the returned code aligned with the Code values in SysTranslationLanguage. For example, if your English translation language is stored as en-US, return en-US rather than en.

Culture settings and number display

The translation pattern also includes SysCultureSettingsSingleton. It separates two settings that would otherwise both come from the browser:

Setting	Controls	Example
Culture	Culture sent to the UI for rendering dates and numbers.	A decimal can render with a comma or point, depending on the selected culture.
TranslationCulture	The current SysTranslationLanguage used for translated text.	A user can receive Swedish UI text while using a culture selected for their preferred number and date formatting.

You can make these properties derived and allow each user to own their values. This lets a user choose translation language independently from number and date formatting.

Default decimal display

SysCultureSettingsSingleton.DefaultDecimalDisplay supplies a default string format for Angular, Blazor, and WPF when no format is already present. The generated format follows this pattern:

0.00<zeros controlled by DefaultDecimalDisplay>#######

Use this setting to establish a consistent decimal display across the application without adding a format to every individual presentation. An explicitly supplied format is not replaced.

Metric and imperial presentation

The same culture settings pattern supports metric and imperial display choices. MDriven stores values in the metric system and can present and edit them in imperial units when configured on the relevant attribute. When MetricImperial indicates imperial display, DefaultDecimalDisplay is generally multiplied by two for attributes because imperial units need higher precision.

For the available settings, supported conversions, attribute tagged values, and presentation-unit behavior, see MetricImperial.

Example: maintain a translated button label

Assume a ViewModel action contains this label expression:

'Create order'.Translate('')

To provide Swedish text:

1. Run the page containing the action so that Create order is registered as a translation miss.
2. Run 'Whatever'.Translate('SPOOLMISSED').
3. Locate the SysTranslatable with Value Create order.
4. Add a SysTranslation connected to the sv-SE SysTranslationLanguage and set its translated value to Skapa order.
5. Run 'Whatever'.Translate('RESETCACHE').
6. Request the page with Swedish selected as the web-page language in the browser. The label displays Skapa order.

If the Swedish translation is missing, the label remains Create order.

See also

• Translate OCL operator
• MetricImperial
• Model Examples
• UI & Styling Documentation

Right-to-left (RTL) languages

RTL support: needs confirmation. The supplied documentation does not describe right-to-left layout support, text-direction handling, or an RTL configuration procedure for MDriven clients.

Do not infer RTL support from the available UI-styling material. Confirm the target client's RTL behavior and any required configuration before documenting or committing to an RTL deployment.

See also

• MDriven Stylesheet

Culture and decimal display

Keep translation and display culture separate

The SysCultureSettingsSingleton pattern provides two culture-related settings rather than relying only on the browser-provided default:

• Culture controls the culture supplied to the browser and affects how numbers and dates are rendered, such as thousand separators and whether decimal values use a comma or point.
• TranslationCulture controls the current SysTranslationLanguage used for translations.

The properties of SysCultureSettingsSingleton can be made derived, allowing their values to be based on values owned by a user.

Set a default decimal display

SysCultureSettingsSingleton.DefaultDecimalDisplay supplies a default StringFormat for Angular, Blazor, and WPF when no format is already present. The documented format pattern is similar to 0.00<zeros controlled by DefaultDecimalDisplay>#######.

This setting is intended to provide a consistent decimal-number display without adding a format individually to every value.

When MetricImperial indicates Imperial units, DefaultDecimalDisplay is multiplied by two on attributes. The documentation describes this as handling the higher precision needed for Imperial values because of their lower granularity.

Test browser-selected language settings

The localization video notes that browsers can send language and culture information separately. When testing browser-selected localization, test the browser and language configuration used by the intended users. The video specifically advises setting the browser's web-page language setting, not only its display-language setting.

See also

• Documentation:MetricImperial
• Translate

Locale-specific formatting

Culture and translation language can be controlled separately with SysCultureSettingsSingleton.

Setting	Controls
Culture	What is given to the browser for number and date rendering, including conventions such as thousand separators and decimal commas or points.
TranslationCulture	The current SysTranslationLanguage.

The SysCultureSettingsSingleton properties can be derived, and users can own their own values.

ViewModel display formats

When a ViewModel column needs a specific display format, set a tagged value on the column.

UI technology	Tagged value	Notes
WPF, Blazor, MVC	StringFormat	Sent to the binding and follows the common text-format pattern for numbers, DateTime, and TimeSpan.
Angular	StringFormatAngular	Appended to the binding as an Angular filter. It works best for read-only values because this formatting is not handled well for two-way data binding.
MVC	StringFormatRazor	Enables Razor-code transformation for read values. One-way binding works best when formatting write values is difficult.

For Angular, number:2 is documented as a number format with two decimals. numberhash:2 is documented as working like C# ToString('0.00######').

See Text formatting for the available formatting patterns and examples.

Default decimal display

SysCultureSettingsSingleton.DefaultDecimalDisplay supplies a default decimal-number display format when no explicit format is already present. It injects a StringFormat for Angular, Blazor, and WPF using a pattern like 0.00<zeros controlled by DefaultDecimalDisplay>#######.

This setting is intended to provide consistent decimal-number display without adding a format to every attribute.

See also

• Documentation:Text formatting

Translate UI text

You can translate text in ViewModels and actions for applications whose users work in different browser languages.

MDriven uses a model pattern to store translations. The pattern contains:

• SysTranslatable, with the original text in its Value.
• SysTranslation, connected to the translatable text.
• SysTranslationLanguage, with a language Code such as en-US or sv-SE.

For example, a translatable value of Save can have a SysTranslation for language code sv-SE. When the current translation language is sv-SE, the UI can show that translated value.

Enable translation services

If your model follows the translation pattern, install IMDrivenUITranslation:

MDriven.Translation.MDrivenUITranslationImpl.Install(ecoServiceProvider);// Installs translation services

Newer versions of MDriven Turnkey already install this service.

Translate a string

Use the Translate operation on the text that you want to show in the user's language.

'Translate this text'.Translate('')

An empty language argument uses the current default language. MDriven Turnkey sets that default from the user's browser language, typically a value such as en-US or sv-SE.

You can request a specific language instead:

'Translate this'.Translate('sv-SE')

This looks for a SysTranslatable whose Value is Translate this, then looks for its translation with language code sv-SE. If no matching translation exists, the original string remains visible.

To force the default language, use DEFAULT=:

'Whatever'.Translate('DEFAULT=sv-SE')

Discover text that needs translation

Do not create every SysTranslatable object by hand. Run this action expression to create SysTranslatable objects for complete translation misses seen since system start-up, or since the previous spool:

'Whatever'.Translate('SPOOLMISSED')

For example, after users have opened a ViewModel containing Save, Cancel, and Order date, run SPOOLMISSED. Create translations for the spooled translatable values and connect each translation to the required SysTranslationLanguage.

Make new translations visible

Translation dictionaries are created at system start-up. Restart the system to load newly added translations.

When translators need to see their changes without a restart, run:

'Whatever'.Translate('RESETCACHE')

RESETCACHE resets cached application pages. The next request recreates the page and can show the newly added translation.

Separate translation language from culture

SysCultureSettingsSingleton separates two settings that the browser otherwise supplies together:

Setting	Controls
Culture	How the browser renders numbers and dates, including thousand separators and comma-versus-point decimal formatting.
TranslationCulture	The current SysTranslationLanguage used for UI text.

You can make these properties derived and let each user own their values. This lets a user, for example, use one culture for number and date formatting while using another translation language for UI text.

Map detected browser languages

Add the static CheckLanguageMapping(input:String):String method on SysTranslateLanguage to replace a detected browser language with your preferred language. For example, map French users to English when English translations exist but French translations do not:

if input.contains('fr') then
  'en'
else
  input
endif

Watch the localization walkthrough.

See also

• Translate OCL operator
• MetricImperial
• UI & Styling Documentation

Control the default language and localization settings

You can control the language used for translations in a localized MDriven application, including browser-based defaults, forced defaults, and preferred-language mapping.

Localization uses the IMDrivenUITranslation service and the translation model pattern. The pattern stores translatable source text in SysTranslatable objects, translated text in SysTranslation objects, and language codes in SysTranslationLanguage objects.

Newer versions of MDriven Turnkey install the translation service. If your system requires manual installation, install it with:

MDriven.Translation.MDrivenUITranslationImpl.Install(ecoServiceProvider);

Use the browser language by default

MDriven Turnkey sets the IMDrivenUITranslation Default-Language setting from the user's browser language. Typical language codes are en-US and sv-SE.

For browser-based applications, ensure that the browser sends the language used for web pages. The browser display language alone may not provide the language value used by the application.

Force a default language

Use an EAL action to force the default language. For example, the following action forces Swedish:

'Whatever'.Translate('DEFAULT=sv-SE');

The text Whatever is the string on which the translation operation is invoked; DEFAULT=sv-SE sets the default language.

Translate text to the selected language

To translate text using the user's selected language, pass an empty language argument:

'Translate this text'.Translate('');

To request a specific language, provide its code:

'Translate this'.Translate('sv-SE');

MDriven looks for a SysTranslatable with a Value of Translate this, then looks for a related translation whose language code is sv-SE. If no matching translation exists, MDriven keeps the original text.

Map detected languages to a preferred language

Add the static method CheckLanguageMapping(input:String):String on SysTranslateLanguage when you need to replace a detected browser language with another language.

For example, if the model is designed in Swedish and contains English translations, map French users to English:

if input.contains('fr') then
  'en'
else
  input
endif

This method runs when MDriven detects the user's language.

Create and refresh translations

Use SPOOLMISSED to create SysTranslatable objects for translation lookups that have missed since startup or since the previous spool operation:

'Whatever'.Translate('SPOOLMISSED');

Translation dictionaries are created at system startup. Restart the system to load newly added translations into the dictionaries.

When translators must see updates without a restart, reset cached pages with:

'Whatever'.Translate('RESETCACHE');

RESETCACHE clears cached pages so that the next request recreates them and can reflect the new translations.

Separate culture from translation language

SysCultureSettingsSingleton separates culture from translation language:

Setting	Controls	Example
Culture	Values sent to the browser that affect number and date rendering.	A culture can determine whether decimal values use a comma or a point.
TranslationCulture	The current SysTranslationLanguage used for text translation.	A user can receive English translated text while using a culture for their preferred date and number format.

You can make SysCultureSettingsSingleton properties derived and let each user own their values. For decimal display and metric or imperial settings, see Documentation:MetricImperial.

See also

• Documentation:MetricImperial
• Documentation:EAL
• Documentation:Learn OCL

Map detected languages to a preferred language

You can map a detected browser language to a preferred translation language when your application does not provide a translation for the detected language.

Add the following static method on SysTranslateLanguage:

CheckLanguageMapping(input:String):String

MDriven calls this method when it detects the user's language. Return the detected language unchanged, or return another language code.

For example, if the model is designed in Swedish and has English translations, you can show English to users whose detected language contains fr:

if input.contains('fr') then
  'en'
else
  input
endif

Control culture and translation culture

You can use SysCultureSettingsSingleton to control culture and translation culture separately when the browser default is not sufficient.

• Culture controls the culture sent to the browser and affects how numbers and dates are rendered, including thousand separators and whether decimal values use a comma or point.
• TranslationCulture controls the current SysTranslationLanguage.

You can make the SysCultureSettingsSingleton properties derived and let each user provide their own values.

The DefaultDecimalDisplay setting injects a StringFormat for Angular, Blazor, or WPF when no format is already present. It uses a pattern like 0.00<zeros controlled by DefaultDecimalDisplay>####### to provide a consistent decimal display.

When MetricImperial indicates Imperial, DefaultDecimalDisplay is multiplied by two on attributes. This accounts for the higher precision needed for Imperial values.

See also

• Translate OCL operator
• Learn OCL
• Model Examples