I18n_Lib is a lightweight internationalization library for OutSystems Reactive Web and Mobile apps. Translations live in JSON files loaded at runtime — add or update languages without redeploying.

How it works

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

Key Features

• Lazy loading — each screen fetches only the JSON it needs, for a fast initial load.
• Automatic re-render — no client variable, no ghost dependency. Expressions refresh themselves when translations load or the locale changes, reusing the OutSystems locale publish/subscribe pipeline.
• RTL auto-switch — including locales OutSystems does not ship natively (ur-PK, he-IL, fa-IR); direction holds across navigation.
• Fallback chain — locale ? parent ? default (ar-SA ? ar ? en-US ? en), so the UI never breaks on a missing key.
• Strict JSON validation — pure flat ("a.b.c": "value") or pure nested; mixed formats are caught at load time with clear errors.
• Interpolation & pluralization — %{opt1} placeholders and count-based forms.
• Cache-busting — a ResourceVersion token appends ?t=v1.5 to fetch URLs; bump it on deploy to refresh the browser cache.
• Low footprint — ~1.7 KB minified core; under 4 KB gzipped for the full library.

Client Actions

• InitTranslation (Application OnReady) — initialize and load default translations.
• LoadScreenResource (Screen OnReady) — lazy-load screen-specific translations.
• Translate (Expression, Function = Yes) — return translated text by key.
• SwitchLocale — change language at runtime; syncs the OS locale, applies RTL, and re-renders.
• TranslateValidationMessages — translate the built-in validation messages.
• ObserveDOM / DisconnectObserver — auto-translate data-trans HTML elements.
• SetConfig / GetConfig — override or read configuration at runtime.

Usage Example

Expression:

Translate("common.welcome", "Welcome", UserName)

Output (English): Welcome, Ahmed
Output (Arabic): ??????? Ahmed

Interpolation:

Translate("order.status", "Order %{opt1} is %{opt2}", OrderId + "," + Status)

No ghost dependency needed — because Translate is an Expression, it re-evaluates on render, and the library forces a render when translations load or the locale changes. Do not pass CurrentLocale or TranslationRevision.

JSON File Structure

/locales/
  default/       (loaded at app start)
    en-US.json
    ar-SA.json
  dashboard/     (lazy-loaded per screen)
    en-US.json
    ar-SA.json
  profile/
    en-US.json
    ar-SA.json

Flat vs nested JSON

// Pure flat
{ "dashboard.title": "Dashboard", "status.active": "???" }

// Pure nested
{ "dashboard": { "title": "Dashboard" }, "status": { "active": "???" } }

Wrapper v1.5.1 · OutSystems 11+ Reactive Web & Mobile.