NE.Standard

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 (default true) 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, so nl-BE finds nl — and in DefaultLanguage when none of them is there. Only a new session: one the reader switched keeps its language. Set it to false for 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 own ui. 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 = true on 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.

  • KeyPrefixes for the whole application: namespace your keys (app.home.header) and every string without a prefix is content. This is what reaches the places neither AsContent nor 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.