1. Overview

I18n Library provides multi-language support for OutSystems Reactive Web and Mobile apps through client actions. Translations are loaded from JSON files at runtime — no redeployment needed to add or update languages.

How it works:

App starts → InitTranslation loads default JSON → Screen opens → LoadScreenResource loads screen JSON → Translate expressions render text

Automatic re-render (new): you no longer need a TranslationRevision client variable or any “ghost dependency”. Translations refresh on screen automatically when a JSON file finishes loading or when the locale changes. See Automatic Re-render.

2. Key Features

• Runtime JSON translations — add or edit languages without redeploying the app.
• Lazy, per-screen loading — each screen fetches only the JSON it needs.
• Automatic re-render — no client variable, no ghost dependency; expressions refresh themselves.
• Right-to-left (RTL) support — including locales OutSystems does not ship natively (ur-PK, he-IL, fa-IR).
• Fallback chain — locale → parent → default, with graceful handling of missing files.
• Interpolation & pluralization — %{opt1} placeholders and count-based forms.
• CDN or app-resource hosting — relative or absolute base paths.
• Validation-message translation and optional data-trans HTML auto-translation.
• Low footprint — core + wrapper are roughly 3–4 KB gzipped combined.

3. Prerequisites

4. File Structure

/locales/
├── default/              ← shared keys (nav, footer, common) — loaded at app start
│   ├── en-US.json
│   └── ar-SA.json
├── dashboard/            ← screen-specific keys — loaded on demand
│   ├── en-US.json
│   └── ar-SA.json
├── profile/
│   ├── en-US.json
│   └── ar-SA.json
└── settings/
    ├── en-US.json
    └── ar-SA.json

Rule: The default/ folder is loaded automatically at app start. Screen folders are loaded on-demand. You only need JSON files for locales you actually translated — missing files 404 silently and fall back to the default locale.

5. Client Actions Reference

6. InitTranslation

Where: Application → OnReady (runs once on app load)

Input Parameters

TranslationMapItem Structure

TranslationMapItem (Record)
├── Key   : Text    → OutSystems screen name (case-insensitive)
└── Value : Text    → JSON folder name under basePath

How to Build

Step 1 — Create TranslationMap list:

// Assign → TranslationMapList
ListAppend(TranslationMapList, {Key: "Dashboard",  Value: "dashboard"})
ListAppend(TranslationMapList, {Key: "Profile",    Value: "profile"})
ListAppend(TranslationMapList, {Key: "Settings",   Value: "settings"})

Step 2 — Create Locales list:

// Assign → LocalesList
ListAppend(LocalesList, "en-US")
ListAppend(LocalesList, "ar-SA")

Step 3 — Call InitTranslation:

InitTranslation(
    BasePath:         "/MyApp/locales/",
    TranslationMap:   TranslationMapList,
    ResourceVersion:  "v1.5",   (optional)
    Locales:          LocalesList
)

Timing Note

InitTranslation is async — it starts fetching but doesn't block the app. If a screen calls LoadScreenResource before init completes, the library auto-queues and executes after init resolves. No error, no timing issue.

7. LoadScreenResource

Where: Each Screen → OnReady event

Input Parameters

Output Parameters

How to Use

// Screen OnReady — that's all. No revision variable to increment.
LoadScreenResource(ScreenName: "Dashboard")

Do not block render on it. The screen paints immediately with each Translate call's DefaultValue, then updates automatically the instant the JSON arrives.

Behaviour

8. Translate (Expression)

Where: Any Expression widget — set Function = Yes

Input Parameters

Expression Formula

Translate("dashboard.title", "Dashboard", "")

No ghost dependency needed. Because Translate is an Expression (Function), OutSystems re-evaluates it on every render, and the library triggers a render when translations load or the locale changes. Do not pass CurrentLocale or TranslationRevision as trailing parameters — that pattern is obsolete. Called before init → returns DefaultValue, never crashes.

Args — Interpolation

JSON:

{ "welcome": "Hello, %{opt1}. You have %{opt2} notifications." }

Expression:

Translate("common.welcome", "Hello", "Gokula,5")

Output: "Hello, Gokula. You have 5 notifications."

Resolution Priority

1. Current locale (e.g., ar-SA)  → found? → return
2. Parent locale (e.g., ar)      → found? → return
3. Default locale (e.g., en-US)  → found? → return
4. Parent of default (e.g., en)  → found? → return
5. DefaultValue parameter        → return
6. Empty string ""               → return

9. Automatic Re-render (How Reactivity Works)

The library reuses the OutSystems locale publish/subscribe pipeline — the same mechanism the platform uses to re-render on a locale change. You do not manage a client variable.

When a lazy translation file finishes loading, the library publishes a re-render for the active locale. Every Translate expression re-evaluates and picks up the newly loaded text. The screen shows DefaultValue first, then swaps to the translation with no flicker — all non-blocking.

When you call SwitchLocale, the library sets the active locale, syncs the OutSystems locale (so native date/number formatting follows), and publishes a re-render. Again, no manual assignment.

Requirement: the value must be a Translate Expression (Function = Yes). Static text set directly on a widget will not update.

10. SwitchLocale & RTL

Where: Language switcher button/dropdown OnClick

Input Parameters

Switcher Flow (Button OnClick)

1. SwitchLocale(Locale: "ar-SA")         ← sets locale, syncs OS, applies dir/lang, re-renders
2. LoadScreenResource(ScreenName: ...)   ← only if the target screen has modules not yet loaded

There is no Assign Client.CurrentLocale step and no revision increment. SwitchLocale handles direction and re-render for you.

RTL Support

Built-in RTL locales: ar-SA, ar-EG, he-IL, ur-PK, fa-IR (extend via SetConfig). The library takes ownership of the OutSystems RTL flag, so direction holds correctly across navigation — including for locales OutSystems does not ship natively (ur-PK, he-IL, fa-IR), which previously stayed left-to-right.

/* Use CSS logical properties or [dir="rtl"] selectors */
.content { margin-inline-start: 16px; padding-inline-end: 8px; }
[dir="rtl"] .sidebar { right: 0; left: auto; }

11. TranslateValidationMessages

Where: After SwitchLocale. Translates the OutSystems built-in validation messages (“Required field”, “Invalid email”, …).

TranslateValidationMessages(EspaceName: "MyApp")

The original (default-locale) messages are captured on first call and used as fallbacks, so switching back restores them correctly.

12. ObserveDOM (Optional)

Where: Screen OnReady, for text placed directly in HTML (outside Translate expressions).

<span data-trans="dashboard.title" data-trans-default="Dashboard"></span>
<span data-trans="common.greeting" data-trans-default="Hello" data-trans-args="Gokula,5"></span>

Screen OnReady:    ObserveDOM()             ← translates existing nodes, watches new ones
Screen OnDestroy:  DisconnectObserver()     ← no argument — tears down the internal observer

The observer is tracked inside the library, so you do not store its handle — DisconnectObserver() with no argument tears down whatever ObserveDOM() last created. Calling ObserveDOM() again auto-disconnects the previous one. These nodes also re-translate automatically when a lazy fetch lands.

13. SetConfig / GetConfig

SetConfig overrides configuration at runtime (empty value = keep current). TranslationMap and RtlLocales merge into the existing values; all other keys replace.

SetConfig(
    BasePath:        "",          ← unchanged
    ResourceVersion: "v2.0",     ← updated
    CacheStrategy:   "no-cache", ← updated
    EnableFallback:  True         ← unchanged
)

GetConfig returns a snapshot of the current values (BasePath, ResourceVersion, Locales, DefaultLocale, CacheStrategy, EnableFallback) for debugging.

14. Common Patterns

Pattern 1 — Simple Text

Translate("common.save", "Save", "")

Pattern 2 — Text With Variables

// JSON: "Last updated: %{opt1}"
Translate("dashboard.lastUpdated", "Last updated", FormatDateTime(Now(), "dd MMM yyyy"))

Pattern 3 — Multiple Args

// JSON: "%{opt1} — %{opt2} on %{opt3}"
Translate("dashboard.list.item", "", "John,Transfer,15 Jul")

Pattern 4 — Conditional Default

Translate("premium.feature", If(IsPremiumUser, "Unlock", "Upgrade to access"), "")

Pattern 5 — Inside a List/Table

// In a Table Records expression:
Translate("status." + GetRecordList.Current.Status, GetRecordList.Current.Status, "")

JSON structure:

{
    "status": {
        "active": "نشط",
        "inactive": "غير نشط",
        "pending": "قيد الانتظار"
    }
}

15. JSON File Format

Rule: Use ONE Format Per File

✅ Pure Flat Example

{
    "dashboard.title": "Dashboard",
    "dashboard.subtitle": "Your overview",
    "dashboard.summary.total": "Total"
}

✅ Pure Nested Example

{
    "dashboard": {
        "title": "Dashboard",
        "subtitle": "Your overview",
        "summary": { "total": "Total" }
    }
}

❌ This Will Throw Error

{
    "dashboard": {
        "title": "Dashboard",
        "summary.total": "Total"
    }
}

Error: [I18n_Lib] Invalid JSON structure at key: "dashboard.summary.total". Use either pure flat or pure nested format.

16. Troubleshooting

Expressions show DefaultValue, never the translation

1. Confirm the value is a Translate Expression (Function = Yes), not static widget text.
2. Confirm the screen name is mapped in TranslationMap (or that the key lives in default/).
3. Confirm the JSON file exists at the expected URL and the key spelling matches.

Locale switched but text didn't change

1. Confirm you called SwitchLocale (not just changed a variable).
2. If the target screen has its own module, call LoadScreenResource after the switch.
3. Confirm the JSON file exists for the new locale (otherwise the fallback text shows).

RTL not flipping

1. Confirm SwitchLocale ran (it sets dir / lang on <html>).
2. Confirm the locale is in rtlLocales (default: ar-SA, ar-EG, he-IL, ur-PK, fa-IR).
3. Use CSS logical properties or [dir="rtl"] selectors in your theme.

Console: 404 for some locale files

This is normal. If you have 5 locales configured but only 2 JSON files for a screen, the missing ones 404 silently and the fallback locale is used instead.

Console warns “LocaleService unavailable” (once)

Cause: the OutSystems locale service could not be resolved. Translations still load and render; the automatic re-render is disabled.
Fix: ensure InitTranslation runs in Application OnReady.

Translation shows [missing "en-US.some.key" translation]

Cause: the key doesn't exist in any loaded JSON file.
Fix: check the key spelling, confirm the right module JSON is loaded for the screen, and add a DefaultValue to the Translate call as a safety net.

I18n_Lib — wrapper v1.5.1 · OutSystems 11+ Reactive Web. See CHANGELOG for version history.