Localization and Text (Client-Side)

Serenity uses a global localization table to resolve localized strings on the client. Text keys are looked up in this table, which is populated from server-side localization scripts.

The Localization Table

Localized strings are stored in a global table keyed by text keys (e.g. "Dialogs.YesButton"). The table is populated from server-side localization scripts and can be extended at runtime with addLocalText.

Resolving Text

localText

localText(key, defaultText?) returns the localized string for a key, falling back to defaultText or the key itself:

import { localText } from "@serenity-is/corelib";

localText("Dialogs.YesButton");          // "Yes" if registered, otherwise "Dialogs.YesButton"
localText("Missing.Key", "Fallback");    // "Fallback"

text

text is an alias for localText:

import { text } from "@serenity-is/corelib";

text("Dialogs.YesButton");

tryGetText

tryGetText(key) returns the localized string or undefined (unlike localText, it does not fall back to the key):

import { tryGetText } from "@serenity-is/corelib";

const value = tryGetText("Some.Key"); // string | undefined

Adding Text at Runtime

addLocalText adds entries to the localization table:

import { addLocalText } from "@serenity-is/corelib";

// Single entry
addLocalText("Db.Northwind.CustomerName", "Customer Name");

// Nested object (flattened with dots)
addLocalText({ Customer: { Name: "Name" } }, "Db.Northwind.");
// registers "Db.Northwind.Customer.Name"

Text Proxies

Generated text classes (in ServerTypes/Texts.ts) use proxyTexts to provide strongly-typed access to text keys. For example:

import { UserPermissionDialogTexts } from "./ServerTypes/Texts";

UserPermissionDialogTexts.DialogTitle; // resolves the text key

The proxy supports .asKey() (returns the key) and .asTry() (returns undefined when missing).

Localization in Widgets

Widgets and grids use localized text for titles, buttons, and messages. For example, EntityGrid resolves its title from the entity's plural display name:

protected getDisplayName(): string {
    return localText(this.getLocalTextDbPrefix() + 'EntityPlural', this.getEntityType());
}