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)

  1. Language tags are BCP 47; lookup is RFC 4647 truncation. fr-CA → fr → default, computed by our own CultureFallback (not CultureInfo.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).
  2. 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.
  3. 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.
  4. 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).
  5. 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-DE to catch accidental culture dependence (the Turkish-i case).
  6. Nothing silent. Missing translation, unknown key, malformed tag, invariant-globalization mode and malformed message templates are diagnostics (BR1301…BR1305), reported through IOperationReporter like every other failure.
  7. Pseudo-localization from day one. qps-ploc (accented, +35% length) and qps-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.
  8. 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 (default auto = from culture via rtlCultures) and item-level direction. RTL mirrors band content order, table/crosstab column order, alignment start/end (never left/right in 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 SKShaper shapes a single run with a single font: no bidi reordering and no fallback, so ITextMeasurer builds on Beep.Skia's TextLayout (HarfBuzz + bidi per run, observed in SDD §2) and adds script itemization with the fontFallback chain; a missing glyph yields diagnostic BR4xxx instead of silent tofu boxes (P04.A.2).
  • Measurement and drawing must use the same shaper (S-02: measuring with SKFont.MeasureText but 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 through ILocalizer.Describe (catalogue key diag.<Code>, positional arguments); notifications carry MessageKey. Logs and audit stay invariant English so operations can search them; users see localized text with the same reference id.
  • Providers (plug-and-play): IStringCatalogProvider implementations — 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 as Microsoft.Extensions.Localization.IStringLocalizer for ASP.NET Core hosts.
  • Shipped languages: en (source), pseudo qps-ploc/qps-plocm, and ar (RTL proof) in the first release; further languages as separate packages Beep.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) provide DisplayNameKey/DescriptionKey/ CategoryKey instead 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 at qps-ploc and qps-plocm show 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.