Localization
Multi-language reports and a localized designer.
Status: accepted as a requirement by the owner (2026-10-28: "Report writer and report should support multilanguage and the
designer support localization. Use best practice."). Decision record: adr/ADR-009-localization.md.
Requirements: SPEC §3.13 (REQ-I18N-001…016). Implementation tasks: PLAN §2 (cross-cutting rows) and the phase files named below.
Two separate problems, two separate mechanisms. Never mix them.
| A. Report localization | B. Product (UI) localization | |
|---|---|---|
| What | The content a report produces: labels, titles, numbers, dates, direction, fonts | The text of the designer, viewers, diagnostics and notifications |
| Who chooses the language | The report run (parameter, request, viewer, schedule) | The signed-in user / host UI culture |
| Where strings live | Inside the .beeprpt file (localization.strings) |
Catalogue providers (satellite assemblies, JSON/XLIFF packs, plug-ins) |
| Contract | ReportStringResolver, IMessageFormatter, ReportExecutionContext.Culture |
ILocalizer, IStringCatalogProvider, IMessageFormatter |
| Already implemented | CultureFallback, ReportStringResolver, SimpleMessageFormatter, PseudoLocalizer (Abstractions) |
Localizer, IStringCatalogProvider, diagnostic arguments, UiNotification.MessageKey |
1. Principles (best practice, researched)
- Language tags are BCP 47; lookup is RFC 4647 truncation.
fr-CA → fr → default, computed by our ownCultureFallback(notCultureInfo.Parent, which depends on the operating system's culture data), so a report resolves the same strings on every host. Telerik documents the failure this avoids: a regional-only resource silently falling back to English (source); Oracle BI Publisher documents the explicit exact → language → default lookup we adopt (source). - Translations travel with the report. String tables are inside
.beeprpt(one file, one ETag, versioned and diffed with the report). Telerik's standalone designer supports localization only in its archive format and not in its plain format (source); we avoid that split. - Keys, not hard-coded text. Every user-visible string, in reports and in product UI, is a key into a string table.
Source language is the default culture. Keys are stable identifiers (
ui.designer.property.fontSize); a translation is never used as a key. - Messages, not concatenation. Sentences with numbers, plurals or gender use message templates
(
"{count, plural, one {# page} other {# pages}}"), never string concatenation. The built-in formatter handles named placeholders; the ICU MessageFormat formatter (plural/select/CLDR rules) is a plug-in (§4). - Culture only at the presentation edge. The file format, expressions, parameter values, data, logs and audit records
are culture-invariant (decimal point, ISO dates, English log messages). Culture is applied when text is formatted for
output or UI. Tests run under
tr-TR,ar-SA,de-DEto catch accidental culture dependence (the Turkish-icase). - Nothing silent. Missing translation, unknown key, malformed tag, invariant-globalization mode and malformed message
templates are diagnostics (
BR1301…BR1305), reported throughIOperationReporterlike every other failure. - Pseudo-localization from day one.
qps-ploc(accented, +35% length) andqps-plocm(mirrored) are real cultures in the resolver, so truncation, overflow, hard-coded strings and RTL mirroring show up in tests and screenshots before any translator is involved. - Plug-and-play languages. A language is a provider registration, not a code change. Exchange formats and machine translation are plug-ins.
2. Report localization (A)
2.1 Culture resolution for a run
ReportExecutionContext.Culture (and TimeZone) is set once per run from, in priority order: explicit request culture →
report parameter marked role: language → user/host culture → settings.culture → localization.defaultCulture. The
ReportStringResolver chain is requested truncations → default truncations. The chosen culture, the chain and every
fallback used are recorded in the run diagnostics.
2.2 What is localizable
Any text-bearing property accepts a literal or @str:key: labels, table headers, titles, parameter prompts and
descriptions, chart titles/axes/legends, empty-data messages, bookmarks and document-map entries, alt text, tooltips,
page-number templates, hyperlink titles. Expressions use Tr("key"), Tr("key", name1, value1, …), and the read-only
values Culture, Language, Direction. Function and operator names stay invariant (Sum, Iif, , and . syntax)
so a report is portable between users; only help text and tooltips in the editor are localized.
Dashboard hosts use the same @str:key convention with the host's registered IStringCatalogProvider plug-ins. See dashboard accessibility and titles.
2.3 Data in several languages
Three supported patterns, all expressed with ordinary report features (no special engine mode):
1. Translated static text — string tables (§2.1).
2. Translated data — multilingual columns or translation tables; the report picks one with
Iif(Language = "fr", [name_fr], [name_en]) or a data set filtered by a language parameter.
3. One request, several languages — burst by culture: the service renders the same definition for a list of cultures
and returns/delivers one file per culture (REQ-I18N-007). A report can also switch language per group or sub-report with
an expression that sets the sub-report's culture parameter (multi-language document).
2.4 Formatting
All formatting goes through ReportExecutionContext.Culture: numbers, percent, currency, dates, times, calendars (Gregorian,
Hijri, Thai Buddhist, … from the .NET culture), first day of week, and digit shapes. Rules:
* Currency symbol/code is data or a format setting, not the culture (a French user can view USD amounts):
format: { type: "currency", currency: "USD" }.
* digitSubstitution: context | none | native (setting and per style) for Arabic-Indic and other native digits.
* Sort and group comparisons use CompareInfo of the run culture (or ordinal when sort: ordinal), so ä sorts correctly
in German and Swedish; the collation used is recorded in the run diagnostics.
* Case mapping is culture-aware only when the author writes Upper(x, culture); default is invariant to avoid the Turkish-i bug.
* Platform dependence: .NET globalization data comes from ICU (Linux/macOS, Windows 10+) or NLS, so formats can differ
slightly between hosts and OS versions. Mitigations: (a) the engine reports the globalization provider and ICU version in
run metadata; (b) golden tests tolerate documented differences and pin the cultures they check; (c) hosts that need
bit-identical output can bundle ICU (Microsoft.ICU.ICU4C.Runtime) — decision recorded in ADR-009. Invariant-globalization
mode (InvariantGlobalization=true) disables culture data entirely; the validator reports BR1304.
2.5 Right-to-left, bidi and fonts (REQ-LAY-012 expanded)
settings.direction: auto | ltr | rtl(defaultauto= from culture viartlCultures) and item-leveldirection. RTL mirrors band content order, table/crosstab column order, alignmentstart/end(neverleft/rightin new styles), page margins (inside/outside), page numbering, and chart axes.- Text is laid out with the Unicode Bidirectional Algorithm (UAX #9) per run plus HarfBuzz shaping and per-script font
fallback. Spike S-02 found
SKShapershapes a single run with a single font: no bidi reordering and no fallback, soITextMeasurerbuilds on Beep.Skia'sTextLayout(HarfBuzz + bidi per run, observed in SDD §2) and adds script itemization with thefontFallbackchain; a missing glyph yields diagnosticBR4xxxinstead of silent tofu boxes (P04.A.2). - Measurement and drawing must use the same shaper (S-02: measuring with
SKFont.MeasureTextbut drawing shaped text is off by up to 45% for Arabic). Tolerances: ≤0.05 pt and ≤0.05% per line. - Fonts: reports reference font families plus per-script fallback lists; embedded fonts are TrueType (S-01: CFF fonts become Type 3 in Skia PDF). Pseudo and RTL fixtures include Arabic, Hebrew, Devanagari, Thai, CJK.
2.6 Output metadata
PDF: document /Lang and per-element language where available; HTML: lang and dir attributes on the document and on
runs whose language differs; XLSX: sheet rightToLeft, DOCX: w:bidi/w:rtl; images: none. Exports state the culture in
their metadata (dc:language).
2.7 Translation workflow
Designer localization editor (P10.C.5): culture list, key/value grid with the default text as source, missing-translation
highlighting, length warnings against the item width, preview-culture switch, RTL toggle, coverage report (percent
translated per culture). Exchange through ILocalizationExchangeFormat plug-ins: XLIFF 2.1 (default, OASIS standard,
carries context notes and max length), PO, RESX, CSV, JSON. Round-trip must be lossless for keys, text, notes and
max-length. An optional ITranslationAssistant plug-in (machine translation) is off by default; no report text leaves the
process unless the host registers and enables an assistant, and every call is audited.
3. Product (UI) localization (B)
- Contract: every designer/viewer string is
ILocalizer.GetText(key, culture, args). No literals in UI projects. Diagnostics display throughILocalizer.Describe(catalogue keydiag.<Code>, positional arguments); notifications carryMessageKey. Logs and audit stay invariant English so operations can search them; users see localized text with the same reference id. - Providers (plug-and-play):
IStringCatalogProviderimplementations —ResxCatalogProvider(satellite assemblies, the .NET-native route and the only one Visual Studio tooling edits),JsonCatalogProvider/XliffCatalogProvider(drop-in files, e.g.locales/de.json), and any custom provider. Later registrations override earlier ones, so a customer can re-word any string without forking. An adapter exposes the catalogue asMicrosoft.Extensions.Localization.IStringLocalizerfor ASP.NET Core hosts. - Shipped languages:
en(source), pseudoqps-ploc/qps-plocm, andar(RTL proof) in the first release; further languages as separate packagesBeep.Reports.Locale.<culture>so adding one needs no core release. A language is "complete" at 100% keys; incomplete packs ship only with a coverage statement. - Runtime switching: changing the UI culture re-resolves all visible text without restarting the host; the designer
chrome mirrors for RTL (Beep.Skia host
FlowDirection), including icons that imply direction. - Property grid and toolbox: item descriptors (
IReportItemDescriptor) provideDisplayNameKey/DescriptionKey/CategoryKeyinstead of names, so third-party plug-in items are localizable too. - Culture-aware input in the designer: number/date parsing in editors uses the UI culture; values are converted to the invariant stored form immediately, and the expression editor always uses invariant syntax.
- Accessibility: accessible names, tooltips, keyboard-shortcut hints and screen-reader texts are catalogue strings.
- Quality gates (CI): (1) key coverage — every key referenced in code exists in
en; (2) no literals — an analyzer/test flags string literals assigned to UI text properties in UI projects; (3) pseudo-locale screenshots of key designer screens atqps-plocandqps-plocmshow no truncation or unmirrored chrome; (4) pack completeness is reported per language.
4. Library and format choices (researched 2026-10-28)
| Concern | Choice | Alternatives considered | Evidence / status |
|---|---|---|---|
| Message syntax (plural/select/gender) | ICU MessageFormat via plug-in Beep.Reports.Localization.Icu (done); default SimpleMessageFormatter has no dependency |
.NET composite format (no plural), SmartFormat (not ICU syntax), Rh.MessageFormat (young) | Chosen: MessageFormat 8.0.0 (Jeffijoe) — MIT per repository, 193 stars, 195 commits, netstandard2.0/net8/net10, CLDR plural rules, 26 tests pass on net8/9/10 (TECHNOLOGY_REVIEW.md). Alternative kept behind the same contract: Rh.MessageFormat (richer CLDR data but a very young single-author repository: 27 commits, 6 stars) |
| Interchange format | XLIFF 2.1 (OASIS) | PO (gettext), RESX, CSV | XLIFF is what translation vendors/tools and Oracle BI Publisher use; PO/RESX/CSV as extra plug-ins |
| UI string storage | RESX satellites + JSON/XLIFF drop-in packs behind one contract | Only RESX; only JSON | RESX is the .NET/VS-native path; JSON/XLIFF allow packs without rebuilding |
| Fallback algorithm | RFC 4647 lookup, own implementation | CultureInfo.Parent |
OS-dependent data would make output host-dependent |
| Bidi + shaping | Beep.Skia TextLayout (HarfBuzz + bidi per run) + script itemization |
SKShaper alone |
S-02: SKShaper has no bidi/fallback |
| Pseudo-localization | Own PseudoLocalizer (qps-ploc, qps-plocm) |
Third-party tools | Trivial, no dependency, same ids Microsoft uses |
5. Where each part is built
| Part | Phase / task |
|---|---|
CultureFallback, ReportStringResolver, IMessageFormatter, SimpleMessageFormatter, PseudoLocalizer, Localizer, IStringCatalogProvider, diagnostic arguments, UiNotification.MessageKey |
Done in P00.E.4 (Abstractions; 79 foundation tests incl. localization) |
Report localization model, validator (BR1301–BR1305), @str: binding, migrations; XLIFF/PO/RESX/CSV/JSON exchange |
P01.D.4, P01.L.1, P01.L.2 |
Tr(), Culture, Language, Direction; culture-aware Format, Upper(x, culture), Compare; invariant syntax |
P03.L.1 |
| Culture formatting, calendars, digit substitution, collation, globalization metadata; bidi, script fallback, mirrored layout, missing-glyph diagnostic | P04.L.1, P04.L.2 (extends P04.A.2, P04.E.1) |
| RTL-aware items, localizable template texts (ICU plural) | P05.L.1 |
Output metadata: PDF /Lang, HTML lang/dir, XLSX RTL, DOCX bidi |
P06.L.1 |
| Culture per request/job, language parameter, burst by culture, localized API diagnostics | P07.L.1 |
| Viewer UI localization, RTL viewer chrome, language selector | P08.L.1 |
| Designer UI catalogue, runtime switching, RTL chrome, no-literals gate; localization editor, XLIFF UI; translation assistant plug-in | P10.L.1, P10.L.2, P10.L.3 (extends P10.C.5) |
Catalogue providers (RESX/JSON/XLIFF), IStringLocalizer adapter, host integration |
P11.L.1 |
| Language packs, pseudo-locale screenshot gate, coverage statements, translator guide | P14.L.1 |
6. Translator guide and coverage statement (P14.L.1, 2026-10-29)
Status of the texts: the de, fr, es and ar texts in DesignerTranslations, ViewerTranslations and EngineLabelCatalog were written by the project, not by a translator. None has had native review. Treat them as drafts.
How to add or fix a language
0. The simplest pack is data, not code: a JSON file named after the culture (de.json) holding { "key": "text" }, read with JsonCatalogProvider.Parse or LoadFolder (a bad file is reported by name).
0. A file from a translation tool (XLIFF, PO, RESX, CSV or JSON with several cultures) works as it is: BundleCatalogProvider.Read(id, LocalizationExchange.CreateRegistry(), "xliff", text).
1. Or write a class that implements IStringCatalogProvider (Id, Cultures, TryGetTemplate); do not edit the English catalog. Register it with the same PluginRegistry<IStringCatalogProvider> as the built-ins; a later registration overrides an earlier text.
2. Keep every key of DesignerCatalog.RequiredKeys() (designer), and the viewer and engine keys. A test per language fails when a key is missing (DesignerCatalogTests).
3. Keep placeholders such as {file} and {reference} exactly as in English; only move them. Do not translate key names.
4. Keep texts about as short as English: buttons and menu items have a fixed width. The pseudo-locale tests catch texts that break when 30-40 percent longer.
5. Right-to-left languages need no extra key: PaneDirection.Apply mirrors the panes from the culture.
Coverage statement (designer chrome): de, fr, es and ar each cover every key the designer asks for; at most 15 per language may equal the English text (shared words such as "Code", "Type", "Sparkline"; the test limit). Viewer and engine coverage is as in ViewerTranslations and EngineLabelCatalog. Nothing is reviewed; nothing has been shown on screen in any language.
Measure a pack instead of trusting a statement (2026-11-09). PackCoverageReport.For(provider, culture, keys, source) returns a
PackCoverage with total, translated, identical-to-source, missing keys and Percent; PackCoverageReport.All(provider, keys, source)
does it for every culture a pack declares, and PackCoverageReport.Statement(coverage) gives the one-line release note
(de: 100% (0 missing, 3 identical to source)). DesignerCatalogTests and ViewerTranslationsTests assert that the shipped
translations are complete through this API, and DesignerLanguagePackTests shows a partial JSON pack reporting its gap while the
built-in English text still resolves.
Pseudo-locale provider. Localizer already turns any qps-ploc/qps-plocm request into the transformed default-culture text,
so a host renders pseudo text without extra setup. Tools that enumerate a catalogue directly (key-coverage reports, screenshot
gates, translation previews) can wrap it with PseudoCatalogProvider (PseudoCatalogProvider.For(new DesignerCatalog())) and get
exactly the strings the localizer would produce.