I18n_Lib — Usage Guide

Wrapper: v1.5.3 · Platform: OutSystems 11+ Reactive Web

Internationalization for OutSystems Reactive Web through Client Actions. No
server logic — translations are JSON files on the server or a CDN, loaded lazily
per screen.

Client Actions

Each Client Action is a thin JS node wrapping the I18n_Lib.i18n module. The
canonical JS for each is in source/I18nWrapper-Development-Chat-Export.md.

1. Initialization

Recommended (v1.5.3) — i18n.config.js (no client action)

Deploy a single i18n.config.js at your app root (as a module Resource, served at
/{YourModule}/i18n.config.js). The library fetches it on load, constructs the engine,
seeds the persisted locale, and initializes itself — no InitTranslation in
Application OnReady.

// i18n.config.js  →  served at /YourApp/i18n.config.js
return {
    basePath: "/YourApp/locales/",                      // required · must end with /
    locales:  ["en-US", "ar-SA", "ur-PK", "fr-FR", "zh-CN"],
    // defaultLocale: "en-US",
    // resourceVer:   "v1",                              // cache-bust ?t= per deploy
    // cacheStrategy: "force-cache",
    rtlLocales: ["ar-SA", "ar-EG", "he-IL", "ur-PK", "fa-IR"],
    translationMap: { "home": "home", "dashboard": "dashboard" }   // lowercase screen → folder
};

The file is fetched with cache: "no-cache", so editing it takes effect on the next
reload without a cache-bust token. A bare return { … } (above) or a
var I18nConfig = { … } declaration both work. The active locale is seeded from the
OutSystems-persisted $…$CurrentLocale before init, so a reload renders in the last
chosen language immediately.

Legacy / manual — InitTranslation client action

Still supported if you want explicit control (or need config values computed at
runtime). Skip it entirely if i18n.config.js is deployed — running both just
initializes twice.

JS node (parses OS Lists → config, then init):

var localesList = [], rtlList = [], screenObjs = {};
try { localesList = JSON.parse($parameters.Locales); } catch (e) {}
try { rtlList = JSON.parse($parameters.RtlLocales); } catch (e) {}
try {
    JSON.parse($parameters.TranslationMap).forEach(function (item) {
        if (item.key && item.key.trim() !== "")
            screenObjs[item.key.trim().toLowerCase()] = item.value.trim().toLowerCase();
    });
} catch (e) {}
var CSI18n  = require("I18n_Lib.i18n");
var i18n = new TinyI18n();                        // TinyI18n is a global
i18n.locale = $parameters.CurrentLocale || "en-US";
CSI18n.init(i18n, {
    basePath:      $parameters.ResourceLocation,
    resourceVer:   $parameters.ResourceVersion || "",
    locales:       localesList.length ? localesList : ["en-US"],
    defaultLocale: $parameters.DefaultLocale || "en-US",
    enableFallback: true,
    cacheStrategy: $parameters.CacheStrategy || "force-cache",
    rtlLocales:    rtlList.length ? rtlList : ["ar-SA","ar-EG","he-IL","ur-PK","fa-IR"],
    translationMap: screenObjs
}).then($resolve).catch($reject);

Timing is handled for you: if a Screen OnReady fires before init finishes (cache
hit), LoadScreenResource / SwitchLocale / TranslateValidationMessages queue
silently and continue once init resolves.

2. LoadScreenResource — Screen OnReady

LoadScreenResource(ScreenName: "Dashboard")   // or "dashboard,accounts,orders"

Do not block render on it. Paint immediately; the screen shows DefaultValue
text, then refreshes automatically when the JSON lands (pub/sub re-render). Partial
locale coverage is fine — missing files 404 silently and fall back.

3. GetTranslation — Expression (Function = Yes)

| Key | Text | ✅ | Dot key: "dashboard.title" |
| DefaultValue | Text | — | Fallback if key missing |
| Args | Text | — | Comma-separated → %{opt1}, %{opt2}, … |

GetTranslation("common.welcome", "Welcome", UserName)          // → "مرحباً، Ahmed"
GetTranslation("order.status", "Order", OrderId + "," + Status) // %{opt1},%{opt2}

JS:

var CSI18n = require("I18n_Lib.i18n");
$parameters.TranslatedText = CSI18n.t($parameters.Key, $parameters.DefaultValue, $parameters.Args);

No ghost dependency needed. Because GetTranslation is an Expression, OutSystems
re-evaluates it on every render, and the library forces a render (via the OS flush)
when translations load or the locale changes. Called before init → returns
DefaultValue, never crashes.

4. SwitchLocale — locale switcher

| Locale | Text | ✅ | Target locale, e.g. "ar-SA" |

var CSI18n = require("I18n_Lib.i18n");
if ($parameters.Locale && $parameters.Locale.trim() !== "") {
    var locale = $parameters.Locale.trim();
    CSI18n.setLocale(locale);   // sets active locale, syncs OS locale, publishes → re-render
    document.documentElement.setAttribute("dir",  CSI18n.getDirection());
    document.documentElement.setAttribute("lang", locale);
    document.body.classList.toggle("is-rtl", CSI18n.isRTL());
}

Then, if the target screen has locale-specific modules not yet loaded:

LoadScreenResource(ScreenName: "Dashboard")

That's it — no RevisionCounter reassignment, no Assign Client.CurrentLocale.
setLocale publishes on the OS LocaleService, which re-renders every
GetTranslation Expression.

5. SetConfig / GetConfig

SetConfig overrides config at runtime (empty value = keep current).
translationMap and rtlLocales merge; other keys replace.

SetConfig(BasePath: "/Staging/locales/", ResourceVersion: "v2")
SetConfig(CacheStrategy: "no-cache")                 // dev: always revalidate

GetConfig returns a snapshot (BasePath, DefaultLocale, Locales, CacheStrategy, …)
for debugging.

6. IsRTL / GetDirection

If(IsRTL(), "layout-rtl", "layout-ltr")   // container CSS class
GetDirection()                            // "rtl" or "ltr"

Built-in RTL locales: ar-SA, ar-EG, he-IL, ur-PK, fa-IR (extend via
SetConfig(RtlLocales: …) — merges). init() patches the OS LocaleService so RTL
holds across navigation even for locales OS doesn't ship natively.

.layout-rtl { direction: rtl; text-align: right; }
.content    { margin-inline-start: 16px; padding-inline-end: 8px; } /* auto-flips */

7. ObserveDOM — HTML outside expressions (optional)

For text set directly in HTML (not through GetTranslation).

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

The observer handle is tracked inside the library, so you don't store it in a
variable — DisconnectObserver() with no argument tears down whatever ObserveDOM()
last created. Calling ObserveDOM() again auto-disconnects the previous one (no
stacking). data-trans nodes also re-translate automatically when a lazy fetch lands
(they subscribe to the load event internally).

8. TranslateValidationMessages

Translates OutSystems' built-in validation messages ("Required field", "Invalid
email", …). Call after SwitchLocale.

TranslateValidationMessages(EspaceName: "MyApp")

Originals (default locale) are captured on first call and used as fallbacks, so
switching back restores them correctly. Kept intentionally — removing it would
lose OS's built-in validation translations.

Troubleshooting

JSON format & fallback

• One format per file — pure flat { "a.b": "v" } or pure nested
  { "a": { "b": "v" } }; mixed throws at load.
• Fallback (default en-US): ar-SA → ar → en-US → en → DefaultValue.

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

2. Prerequisites

3. File Structure

/locales/
├── default/              ← shared keys (nav, footer, common)
│   ├── en-US.json
│   └── ar-SA.json
├── dashboard/            ← screen-specific keys
│   ├── 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.

4. Client Actions Reference

5. InitTranslation

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

Input Parameters

TranslationMapItem Structure

TranslationMapItem (Record)
├── Key   : Text    → OutSystems screen name (exact match)
└── 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"})
ListAppend(TranslationMapList, {Key: "Transfers",  Value: "transfers"})

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.3", (optional)
    Locales:          LocalesList
)

What Happens

1. Library initializes with config
2. Fetches default/en-US.json and default/ar-SA.json
3. Stores translations in memory
4. Library is ready for loadForScreen() and t() calls

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.

6. LoadScreenResource

Where: Each Screen → OnReady event

Input Parameters

Output Parameters

How to Use

// Screen OnReady:
LoadScreenResource(ScreenName: "Dashboard")

// Then assign:
TranslationRevision = TranslationRevision + 1

Behaviour

When Screen Name Is Not Mapped

If ScreenName doesn't exist in TranslationMap, no screen-specific JSON is loaded — but default/ translations are still available. This is not an error.

7. Translate (Expression)

Where: Any Expression widget — set Function = Yes

Input Parameters

Output

Expression Formula

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

Important: Include CurrentLocale and TranslationRevision as trailing parameters. They aren't used by the function logic — they are ghost dependencies that force OutSystems to re-evaluate the expression when locale changes or translations load.

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

8. SwitchLocale

Where: Language switcher button/dropdown OnClick

Input Parameters

Full Switcher Flow (Button OnClick)

1. SwitchLocale(Locale: "ar-SA")
2. Assign → Client.CurrentLocale = "ar-SA"
3. LoadScreenResource(ScreenName: GetCurrentScreen())

9. SetConfig

Where: Anywhere at runtime (optional — for advanced use)

Input Parameters

Rule: Empty String = Keep Current Value

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

When to Use

• Switch CDN endpoint mid-session
• Force cache refresh after deployment
• Enable/disable fallback for testing

10. GetConfig

Where: Debug screens, developer tools

Output Parameters

Usage

GetConfig()
// Use outputs for debug display or conditional logic

11. 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": "قيد الانتظار"
    }
}

Pattern 6 — Dynamic Screen Name

// Reusable across screens:
LoadScreenResource(ScreenName: GetCurrentScreenName())

12. JSON File Format

Rule: Use ONE Format Per File

✅ Pure Flat Example

{
    "dashboard.title": "Dashboard",
    "dashboard.subtitle": "Your overview",
    "dashboard.summary.total": "Total",
    "dashboard.alerts.empty": "No active alerts."
}

✅ Pure Nested Example

{
    "dashboard": {
        "title": "Dashboard",
        "subtitle": "Your overview",
        "summary": {
            "total": "Total"
        },
        "alerts": {
            "empty": "No active alerts."
        }
    }
}

❌ 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.

13. Troubleshooting

Error: "Invalid or missing I18n instance"

Cause: LoadScreenResource called before InitTranslation resolved.
Fix: Already handled in v1.3.0+ — the library auto-queues. If you still see this error, ensure InitTranslation is in Application OnReady (not Screen OnReady).

Expressions show DefaultValue, not translation

Check:

1. Is CurrentLocale included in the Translate expression? (ghost dependency)
2. Is TranslationRevision included in the Translate expression? (ghost dependency)
3. Is TranslationRevision incremented after LoadScreenResource?
4. Is the screen name in TranslationMap?
5. Does the JSON file exist at the expected URL?

Locale switched but text didn't change

Check:

1. Did you call LoadScreenResource after SwitchLocale?
2. Did you increment TranslationRevision?
3. Does the JSON file exist for the new locale?

RTL not flipping

Check:

1. Did you set dir attribute on <html> after switch?
2. Is the locale in the rtlLocales list? (default: ar-SA, ar-EG, he-IL, ur-PK, fa-IR)
3. Are you using logical CSS properties or [dir="rtl"] selectors?

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. The fallback locale (en-US) is used instead.

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

Cause: Key doesn't exist in any loaded JSON file.
Fix:

1. Check spelling of key in JSON file
2. Check that the correct module JSON is loaded for this screen
3. Add a DefaultValue to the Translate call as safety net