Localization
A page shows its text in the session's language. What an author writes on a translatable property is a key — the server looks it up when it renders the page, and the page looks it up again every time the value changes and every time the viewer switches language. What should be shown as written is content, and is said to be so. The two rules to keep in mind:
- a value on a
[Translatable]property is a key unless you say otherwise, whether it is set on the view or bound to the controller, and whether it arrives with the page or later; - a key with arguments — a count, a name — is a
UIPhrase, never a string you put together yourself.
Translation sources
application.AddLocalizationSource(dictionary) registers an in-memory source: a dictionary keyed by language, then by key,
each value the translated text.
internal static class AppTranslations
{
public static IReadOnlyDictionary<string, IReadOnlyDictionary<string, string>> Build()
=> new Dictionary<string, IReadOnlyDictionary<string, string>>
{
["en"] = new Dictionary<string, string>
{
["app.home.header"] = "Roster",
["app.files.one"] = "{count} file",
["app.files.other"] = "{count} files"
},
["zh-Hans"] = ZhHans.Words
};
}
application.AddLocalizationSource(AppTranslations.Build());
That overload wraps the dictionary in the built-in DictionaryTranslationSource. AddLocalizationSource(ITranslationSource source) registers any other source — implement ITranslationSource (Languages, TryTranslate(language, key, out value),
and, if it can, ListWords(language)) for one backed by a database, a .resx set, or a translation service, and register it
the same way, or as an ordinary DI service (ITranslationSource is resolved from the container too). Sources are consulted
most-recently-added first, so a later AddLocalizationSource call can override a key an earlier one set. Sources registered in
the container rank below every AddLocalizationSource source, whatever the order they were added in, and among themselves the
last-registered answers first. An ITranslator registered in the container replaces the whole chain: the sources above,
ConfigureLocalization's options and the fallback order below are all ignored, and that translator answers every lookup on
its own — ITranslator's default members still give it arguments and plurals.
The page receives a language's words. A browser translates by a table of the language's words — every key the translator
lists, the framework's own among them — fetched once per language from /_ne/words/{language}.json and cached under its
version. So put nothing in a translation source that the page may not read. A source that cannot list its words (ListWords
answers null) still works: the page asks the server about a key its table lacks, once per language, and once more after
5 s should the ask fail.
A source's words are listed once per language and held for the life of the process, and the page's table is cached under its
version: a source whose words change at runtime shows the change only after a restart — or answers null from ListWords, and
is then asked key by key.
UILocalizationOptions
application.ConfigureLocalization(options =>
{
options.DefaultLanguage = "en";
options.KeyPrefixes.Add("app.");
options.ReportMissingWords = true;
});
DefaultLanguage(default"en") is the fallback language used when a translation is missing for the session's requested language, and the language a brand-new session starts in when negotiation finds nothing.NegotiateLanguage(defaulttrue) starts a new session in the first language its browser asks for (Accept-Language, most wanted first) that an application source names — as written, else by its primary language, sonl-BEfindsnl— and inDefaultLanguagewhen none of them is there. Only a new session: one the reader switched keeps its language. Set it tofalsefor an application in one language for everyone.KeyPrefixes— with any prefix set, a plain string is looked up only when it starts with one (the framework's ownui.is always one). Empty, the default, every string is a key. See Keys and content.ReportMissingWords— whether a missing word is collected and logged;null, the default, reports in Development and not in Production. See Missing translations.
Keys and content
[Translatable] marks a component or item-model property whose value is a translation key rather than literal text —
TextComponent.Title, TextBaseItem.Title, BadgeItem's text properties, and most other text-bearing properties of
the built-in components and models carry it. A lookup miss falls back to the key itself, which is what makes writing
"Add one" directly, with no translation source configured, work exactly as shown in getting started.
An author-declared item — a static MenuItem or TabItem — is translated as a bound one is. An icon is a name, never a word:
no icon property is translatable, and an icon that differs per language is a binding.
The price of that convenience is that a value equal to a key is translated: a card named like an entry of your dictionary shows the entry's words. Two ways to keep content as written:
AsContent(property)on the instance — this one text, this one badge — shows the property as written, bound or static:new TextComponent().BindTitle(nameof(CardController.Name)).AsContent(TextComponent.TitleProperty)IsContent = trueon an item — a select's option, a menu entry — shows every word of that item as written:new OptionItem { Id = "utf-8", Title = "UTF-8", IsContent = true }Every built-in item has it; an application's own item type says it by implementing
IContentItem. It holds for a value of the item's row pushed later too: the server says so on the update, and the page shows it as written.KeyPrefixesfor the whole application: namespace your keys (app.home.header) and every string without a prefix is content. This is what reaches the places neitherAsContentnor an item's mark is written — a default template's items you did not make yourself. With prefixes set, missing-word reports are exact, too.
A package that builds fields from an application's data marks them content the same way: the Graph node canvas's catalogue — kinds, pins, choices — shows as written in every language.
A UIPhrase is always looked up, whatever its key and whatever the property. An author's text standing as an argument — an
option's title in a framework word, a caption — is UIPhrase.Text(title): looked up only where the text itself would be (under
KeyPrefixes, only a prefixed one).
Every translatable text property takes a phrase. A title, a description, a tooltip, a badge's text and tooltip — on a
component and on an item alike (TextBaseItem, TextItem, BadgeItem, MenuItem) — a placeholder, a prefix and a suffix, an
accessible name, an image's alternative text, a separator's, progress bar's or spinner's title, an input's FormatMessage and a
field's help are typed UIPhrase?. A string converts to one implicitly, as the author's text (UIPhrase.Text), so
Title = "Anna" and .SetPlaceholder("Search") read as before and are looked up exactly as a plain string was; a key with
arguments, or a moment, stands in the same place: Description = UIPhrase.Of("chat.seen", ("at", lastSeen)). Content keeps its
rule — IsContent or AsContent shows an author's text as written, while a key is always translated. Code that read such a
property as a string reads the phrase's Key (the text, for an author's text) instead. A conditional mixing a string and a phrase
now yields a phrase; where a plain string was meant, cast the string to object.
Arguments: UIPhrase and `
A word with a slot is written once, in the source, with a named slot: "Hello, {name}!". A slot is { + letters, digits or
_ + }; one the arguments do not fill stays as written, and there is no escape. {0} is a name like any other, which is how
positional arguments work.
A value carrying a key and its arguments is a UIPhrase (NE.Standard.UI.Primitives.Localization, a global using):
[RecursiveMember]
public partial UIPhrase? Greeting { get; set; } = UIPhrase.Of("app.greeting", ("name", "Ann"));
// the view
new TextComponent().BindTitle(nameof(HomeController.Greeting))
The phrase travels to the page as it is ({"key":"app.greeting","args":{"name":"Ann"}}) and the page fills it in its
language — again after a language switch. An argument is a string, a number, a bool, null, or another phrase, which is
translated first:
UIPhrase.Of("app.editor.title", ("page", new UIPhrase("app.cards"))) // "{page} · Roster editor"
Numbers are written as they are (1234.5, never 1,234.5 or 1 234,5 — no grouping, no language's digits), on the page
and on the server alike, and the plural form is picked from the number itself: a number in a culture's format is yours to format
and pass as a string, as an argument of its own beside the count. A NaN or an infinity has no JSON literal: it travels as
null and fills its slot with nothing, on the page and on the server, and as a count it picks no plural form. A key
alone is new UIPhrase(key) (or UIPhrase.Of(key)). A string converts into a phrase only as the author's text —
UIPhrase.Text(text), which UIPhrase.FromString also returns — never as a key. Words that must say something — a toast's, a
validation message's, a preset's — are refused blank: UIPhrase.HasWords(words) is that test (a key always says something, an
author's text unless it is blank), and a component or a check of your own asks it rather than spelling the rule again.
A file's size is a UIFileSize, written by the page in the reader's language exactly as a file tile writes its own — "45 bytes",
"1.5 kB", "1,5 МБ", each unit 1024 of the one before — and written again after a language switch. A plain number stays a number (and
a plural's count), so a size is always this type. The server paints it as the page writes it in English and the page writes it
again before the first paint; where no page writes it at all (a word the server translates itself) it reads as that English. A
size with nothing around it — a file dialog's line under the name — is its Phrase(), the framework's ui.file.size ({size}):
Description = UIPhrase.Of("app.file.sent", ("name", file.Name), ("size", new UIFileSize(file.Size))) // "{name}, {size}"
Description = new UIFileSize(file.Size).Phrase() // the size alone
Where the words are read as inline markup — a description, a tooltip — an argument written as text is shown as written.
A string, an author's text (after its lookup) and any other value's text are escaped there, so a name a person typed as
[a](b) or **x** shows as typed rather than becoming a link or bold; the key's own words, a nested key's words, numbers,
flags, moments and file sizes stay markup. A place that shows words as text escapes nothing. A description that is wholly what a person
typed — a chat's message, bound as a string — is shown as written with SetDescriptionPlain(true), and a tooltip of a name the
controller holds with SetTooltipPlain(true).
Plurals
A numeric argument named count picks the plural form of the key: the lookup tries key.{category}, then key.other, then
the key itself. The categories are the CLDR ones (zero, one, two, few, many, other) for the language — English and
German have one/other, Russian and Ukrainian one/few/many/other, Polish the same, Spanish and French one/many/
other, Chinese only other; a language the framework does not know takes other.
["ru"] = new Dictionary<string, string>
{
["app.files.one"] = "{count} файл",
["app.files.few"] = "{count} файла",
["app.files.many"] = "{count} файлов",
["app.files.other"] = "{count} файла"
}
Files = UIPhrase.Of("app.files", ("count", 21)); // "21 файл"
Give a key's plural forms in every language or none: a language with only the plain key falls to the default language's
key.other, since each step of the lookup goes through the whole fallback order. A table need not hold a form its language
never picks: Chinese has only other, and a listing does not report key.one missing there. A form the language does pick is
reported when no table holds it — Russian's files.few and files.many where the tables hold only files.one and
files.other, which a lookup would quietly fill from Russian's own files.other.
Context.Translate
A controller translates in code with Context.Translate — for a download's name, anything not carried by a translatable
property (a notification's words are translated on the page, see dialogs and notifications):
Context.Translate("app.save.done") // a plain value
Context.Translate("app.greeting", new Dictionary<string, object?> { ["name"] = "Ann" }) // named: {name}
Context.Translate("app.saved-count", 3) // positional: {0}
Context.Translate(UIPhrase.Of("app.files", ("count", 3))) // a phrase, plural included
Translate(key, arguments) takes a dictionary of named arguments, Translate(key, params object?[]) positional ones ({0},
{1}, …), and Translate(UIPhrase) a phrase; these three always look the key up. Translate(string) is the plain-value
path and returns string? — the key itself for a key nothing translates (a blank key too), null only for a null key. Text built in
code is in the language the page was in at that moment; to have it follow a switch, bind a UIPhrase instead.
A view's title with arguments
A view's Title is a key; TitleArguments fill it:
public override string Title => "app.editor.title"; // "{page} · Roster editor"
public override IReadOnlyDictionary<string, object?>? TitleArguments
=> new Dictionary<string, object?> { ["page"] = new UIPhrase("app.cards") };
The document's title is translated with them on the server and again at every switch.
Switching the language
The session's language is UserSessionState.Language. Switching it rewrites the page in place — every translatable value,
every phrase, the framework's own words, the title — with no navigation and without touching the controller's state.
The switcher. LanguageSwitcherComponent offers the translator's languages, each named in itself (English, 中文(简体))
and never translated: with one language nothing is drawn, with two a press switches, with more it opens a list. The button shows
the language's two-letter code ("EN", "ZH" for zh-Hans) and nothing else — no chevron, whatever a press does. It is as wide as
its widest language, so it keeps its place when the language changes, and its accessible name says the language and, with two,
the one a press switches to, each with the code it shows ("Language: English (EN), switch to Русский (RU)" —
UIStrings.LanguageSwitch takes {language}, {code}, {other} and {otherCode}; with more, "Language: English (EN)" —
UIStrings.LanguageCurrent). SetDisplay(UILanguageDisplay.Name) shows the
language's name rather than its code, SetLanguages([...]) narrows or orders the choices, and it takes an icon, a button look
and size, and a tooltip like any button (ButtonVariant, Size and IconSize are the theme switcher's too, ISwitcherComponent).
On a page in a language it does not offer (SetLanguages left the page's out), the switcher shows the page's language as a
label that is never a choice and marks none of its own current; a two-language toggle then asks for the first language it
lists. A second press on a toggle while the first switch is still loading goes back.
AsField() draws the switcher as a settings form's field instead: a caption ("Language", UIStrings.LanguageField, or
SetTitle's, decided at render), a box in the form's appearance (Filled unless SetFieldVariant says otherwise) showing the page's
language by its name after the author's icon, and a press opening the list whether there are two languages or more. A choice
switches the page exactly as the button's does, and every switch moves the field. The theme switcher has the same shape
(theming).
UIPage.Header(title, description, new LanguageSwitcherComponent(), new ThemeSwitcherComponent())
From a command. Context.UpdateSessionAsync changes the language like any other session field; the page follows at once:
[UICommand]
public async Task SwitchToChineseAsync(CancellationToken cancellationToken)
=> await Context.UpdateSessionAsync(session => session with { Language = "zh-Hans" }, cancellationToken);
For the rest of that command Context.Handle.Session.Language is the new language, so Context.Translate answers in it. From an
interaction, SetLanguageEffect("zh-Hans") switches the page without a command.
Every page of the session follows. A switch made on one page — the switcher, SetLanguageEffect, a command's
UpdateSessionAsync, IUISessions.UpdateUserSessionsAsync — reaches every page open under the session, and a page the framework
keeps for later hears it before it next paints or attaches, so a reader who comes back to it finds it in the new language.
Reacting to a switch. UIControllerBase.OnLanguageChangedAsync(previousLanguage, cancellationToken) runs once per change on
every runtime of the session, wherever the change was made — inline from a command's UpdateSessionAsync, as a command when the
switcher did it, and on a kept runtime before its next render paints or at its next attach, before OnNavigatedAsync;
previousLanguage is the one that controller last heard:
protected override Task OnLanguageChangedAsync(string previousLanguage, CancellationToken cancellationToken)
{
// Bound keys and phrases need nothing — the page translates them again. Text built with Context.Translate does.
Status = Context.Translate("app.status.ready");
return Task.CompletedTask;
}
What follows a switch at once besides the words: a number field and a date, time or date-time field with no Culture of its
own, a timestamp (below), and a data grid's and a chart's numbers and dates — the page's words table carries the language's
number and date culture. What does not, until the next render: a number or a date the controller wrote into text itself (write
it again from OnLanguageChangedAsync), and a popup already open, which keeps its words until it opens again.
Dates and times
A date, time or date-time field shows one predictable default: yyyy-MM-dd and HH:mm, whatever the page's language, until
it is asked for a culture's patterns. The page's language still gives the month and day names, AM and PM, and the placeholder —
the format in the page's own letters (дд.ММ.гггг чч:мм in Russian, the words ui.picker.letter.*) — and a language switch
redraws them from the page's words.
The culture's patterns are opt-in. ConfigureTemporal(o => o.FollowCulture = true) gives every field without a
DisplayFormat its culture's short date and time patterns — its Culture's, else the page language's: dd.MM.yyyy on a
Russian page, M/d/yyyy and h:mm tt on an English one, the year always four digits — and a switch redraws the format too. A
field that names its own Culture shows that culture's patterns whatever FollowCulture says. A pattern the shared formatter
cannot write (an era, a zone, a fraction) falls back to yyyy-MM-dd and HH:mm.
The application can set its dates and times once. ConfigureTemporal on the application builder says whether fields follow
the culture, how a clock counts its hours, and may give a date and a time pattern for every language:
application.ConfigureTemporal(o =>
{
o.FollowCulture = true;
o.HourCycle = UIHourCycle.TwentyFourHour; // the culture's patterns, 14:05 in every language
});
application.ConfigureTemporal(o =>
{
o.DateFormat = "dd.MM.yyyy";
o.TimeFormat = "HH:mm"; // to the minute; a field whose step reaches seconds adds them
});
HourCycle is Default (the count of the pattern a field falls back on: 24 hours in HH:mm; where the culture is followed, its
own — 14:05 in Russian, 2:05 PM in American English), TwentyFourHour or TwelveHour. A pattern
is written in the shared tokens — yyyy, MM, M, dd, d, MMM, MMMM, ddd, dddd, HH, H, hh, h, mm, m,
ss, s, tt, anything else as it stands — and is checked at startup: a letter outside them, a quote, a two-digit year, a
missing part, or a TimeFormat whose hours disagree with HourCycle is refused. The options hold for every date, time and
date-time field without a DisplayFormat of its own (which still wins), after a language switch too, and for the picker's hour
column (2 PM on a 12-hour clock); the page's language still gives the month and day names and AM and PM. A
timestamp's day and time are written in the same patterns, in the reader's zone; only a relative one ("5 minutes ago") is the
browser's own words for the page's language.
A field reads what is typed in the format it shows. Text in the shown format — the default, the culture's, or a DisplayFormat of the
author's — is read on the page and sent as the value it names; text in another shape goes to the server as typed, which reads it by
the field's Format and Culture or refuses it.
A moment in the reader's own zone is a TimestampComponent. It takes an instant (Value, a DateTimeOffset whose offset says which
instant it is, never where it is shown) and the page writes it in the reader's time zone — Format is DateTime, Date or
Time, written in the application's patterns and the page's names as a date field is, or Relative ("5 minutes ago",
"yesterday"), in the browser's words for the page's language and kept current as time passes, or RelativeDate ("Today",
"Yesterday", else the day as Date writes it — a day header in a chat), by the same words and clock. One render of a view serves every
reader, so the server paints the instant in UTC, in the same patterns, marked UTC where it shows a clock (a relative one as its
day and time), and the page writes it in the reader's zone before it is first painted — a moment in a phrase's words too, and a
file size in the reader's language — so the reader never sees the UTC text. On the server, the zone the page reported
as it attached is the session's (Context.TimeZone, Context.ToLocalTime, Context.StartOfDayUtc,
controllers).
Validation messages
A field's validation message is translated like any other text, and written again when the page switches language — a rule's,
a bound Validation, and the runtime's refusal alike:
new TextInputComponent()
.Required("form.name-required") // a key (or text) by the plain rule
.Regex("^.{0,12}$", UIPhrase.Of("form.name-max", ("max", 12))) // a key with its argument
NameValidation = UIValidationMessage.Error("form.name-taken"); // from the controller
NameValidation = UIValidationMessage.Error(UIPhrase.Of("form.min", ("count", 3)));
A string is looked up as a plain value on a translatable property is (under KeyPrefixes, only a prefixed one); a UIPhrase is
always looked up and filled, and UIPhrase.Text("…") passes an author's literal where a phrase is asked for. A value the runtime
cannot read is refused with the input's own FormatMessage, else the framework word ui.value.format. FormatMessage is
translatable like any other message; AsContent(IFormattedInputComponent.FormatMessageProperty) on the input keeps it as
written.
The framework's own words
UIStrings is the vocabulary the framework's own chrome uses — a date picker's "Today", a tab strip's "More tabs", a file
input's "Uploading… %", an empty list's "Nothing to show." — each a key (UIStrings.PickerToday, UIStrings.TabsMore,
…) with English text in UIStrings.English; a component package adds its own (DataGridStrings, CodeInputStrings,
ChartsStrings, GraphStrings). The palette's colour names are words too — ui.color.name.* (UIStrings.ColorNameKey,
English "Iron fog", "Quantum blue", …), on a chip's tooltip and accessible name.
The framework ships its words in English, Russian (ru) and Simplified Chinese (zh-Hans) — the core's
(UIStrings.Translations) and each package's (IUIStringsSource.Translations). English is always on; the other two are
opt-in, in one line:
application.AddFrameworkWords("ru", "zh-Hans");
That turns them on for the core and for every registered package, ranked below the application's own sources, so a word of yours with the same key overrides one. A language no source ships is refused when the application is built. It adds no language to the page's switcher: a language is the page's once a source of the application names it. Any other language an application brings itself — a word is translated the same way as your own text, by the same key in your own source:
application.AddLocalizationSource(new Dictionary<string, IReadOnlyDictionary<string, string>>
{
["en"] = new Dictionary<string, string> { [UIStrings.TabsMore] = "More tabs…" },
["fr"] = new Dictionary<string, string> { [UIStrings.TabsMore] = "Plus d'onglets" }
});
To see what there is to translate, UIStrings.List(packages) gives every framework and package key with its English,
UIStrings.Discover(assemblies) finds the packages' sources in their assemblies without a service container, and
UIStrings.Missing(source, language, packages) lists the keys a source has no word for:
IReadOnlyList<IUIStringsSource> packages = UIStrings.Discover(typeof(DataGridStrings).Assembly, typeof(ChartsStrings).Assembly);
IReadOnlyList<string> untranslated = UIStrings.Missing(new DictionaryTranslationSource(AppTranslations.Build()), "fr", packages);
The shipped tables are what to start another language's from: UIStrings.Translations["zh-Hans"] and each package's
Translations hold every key. The framework demo (examples/DemoApp/DemoTranslations.cs) turns the shipped tables on and
keeps only its own words.
Missing translations
With ReportMissingWords on — by default in Development — the translator collects every word asked for and missing: a key
asked in a language other than the default that no source has in it, or, with KeyPrefixes set, a prefixed key nothing
translates. Each is logged once at Warning (at most 4096, then one line saying the report stopped), and collected in
IUIMissingWords, which a test resolves from the application's services:
IUIMissingWords missing = services.GetRequiredService<IUIMissingWords>();
// ... render the pages, run the commands ...
Assert.Empty(missing.Snapshot().Where(word => word.Language == "zh-Hans"));
Snapshot() gives the UIMissingWord(Language, Key)s so far and Clear() starts over; UIApplication.MissingWords is the
same collector. Without KeyPrefixes every piece of content in a non-default language counts as a miss, so the report is exact
only with prefixes; what is marked content (AsContent, an item's IsContent) is never reported, and neither is a key's plural
form asked about and absent, nor, when a table is listed, a form its language never picks. A listed table does report a plural
form its language picks and no table holds (see Plurals), so such a gap shows at the first listing, where the lookup of that
count never reports it. The demos each namespace their own words this way (demo., grid-demo., charts., code-demo.,
nodes., planner., icons-demo.), and a test holds each demo's table complete. For a check that renders nothing,
UIStrings.Missing above compares a source with the framework's keys.
Under KeyPrefixes the report also names static text that is no key. A plain string on a translatable property, or on an
item the author declared, that starts with no prefix and is not marked content is shown as written in every language — where
the author may have meant a key. Each view is inspected as it is compiled, and each such text is recorded once as a
UIMissingWord with Kind = UIMissingWordKind.Unkeyed (its Key the text, its Language empty) and logged with the view,
component and property it stands on; a missing word proper is UIMissingWordKind.Untranslated. Bound values are data and stay
silent, and so do text without a letter ("—", "404") and an address on a translatable Url. Mark what is meant as written:
AsContent(property) for one property, IsContent for an item, and AsContentTree() on a component for the static text of
it and of everything under it — its children and the items it declares — a sample, a page of prose, a table of data.
AsContentTree is report-only: it changes nothing rendered or looked up.
Fallback order
A lookup tries, in order: the requested language in the application's own sources, then the framework's words in that
language (the shipped tables turned on by AddFrameworkWords, and English, which is the built-in floor), then the application's
DefaultLanguage in its own sources, then the framework's words in that language, then UIStrings' built-in English together
with each installed package's own English words (which answers for any requested language, so a framework word nobody has
translated still reads instead of showing its key), and finally the key itself if nothing answered. So a Russian page reads the
framework's Russian before the application's default-language word, and an English page of an application whose default is
Russian reads the framework's English. Within each language step the sources are asked in the order given under Translation
sources: AddLocalizationSource calls last-first, then the container's ITranslationSource services last-first. An
application's own word always outranks the framework's in the same language — the framework's words are a base to override, not
a ceiling. The page's table of a language is this same order worked out for every key at once, so the
page and the server always agree. None of this applies when the container holds an ITranslator of its own; that one replaces
the whole lookup.