Skip to content

Localization

Jump to bottom
Edgar Mesquita edited this page Aug 12, 2026 · 15 revisions

Localization

Multi-language in eQuantic.UI follows one law: the developer localizes with what .NET itself offers — .resx, the strongly-typed accessor, CultureInfo — and never sees a JavaScript catalog or a framework DSL. The full design (Track L: how eqc bridges ResourceManager into the browser, per-culture catalogs, the formatting subset, the honest fences) lives in the repo at docs/I18N-PLAN.md. This page documents what is shipped today and what is still design.

Shipped

The SDK's own strings live behind one seam

Since 0.2.0-preview.24

Components never hardcode a user-facing string. Every built-in label — the toggle announcements a screen reader hears ("Checked", "On"), the dismiss affordances, the search placeholder, the code editor's find bar — reads SdkStrings, a static class of properties (never consts: a const crosses assemblies by VALUE, and inlined call sites would keep announcing the build machine's language after the seam learns cultures). The transpiled twins confirm the choke point survives on the web too: eqc emits static getters and the components reference them. When Track L lands, the property bodies swap to the resx-backed accessor and no component changes.

Photon windows adopt the machine's locale at launch

Since 0.2.0-preview.24

A GUI process launched from Finder carries no LANG/LC_*, so .NET starts invariant even on a pt-BR machine. The shells resolve the platform's locale truth before the first frame — NSLocale.preferredLanguages[0] as the UI culture and currentLocale as the format culture on Apple (the same split .NET models as CurrentUICulture vs CurrentCulture), Locale.getDefault() feeding both on Android — and PhotonCultureController copies the pair onto the process statics, repainting on a later Apply exactly as the theme controller repaints on a mode flip. Because Photon runs real .NET with no transpilation, ResourceManager and satellite assemblies already work there: a native app localizes today with ordinary resx.

A page speaks resx on the web, end to end

Since 0.2.0-preview.26

Track L's M0: an app writes localization exactly as any .NET app does — a Resources/Strings.resx plus Strings.pt-BR.resx, the ordinary Designer accessors, string.Format(Strings.Greeting, name) — and the page answers in the request's culture on BOTH halves of the web target.

The pieces, mirroring the theme bridge shape for shape:

  • eqc rewrites accessors, never inlines them. Strings.Hero_Title compiles to $eq.str("Strings", "Hero.Title") — inlining would bake the build machine's culture into the bundle. Detection is by SHAPE (the Designer's static ResourceManager + Culture properties), so any resx anywhere in the project works, whatever the developer named it.
  • The build emits catalogs from the keys the app actually uses. wwwroot/_equantic/strings/neutral.json plus one {culture}.json per authored variant, each FLATTENED against the .NET fallback chain at emit time — the server picks a file, it never merges.
  • The server inlines the answer. UseRequestLocalization (the APP wires negotiation, the SDK only reads what the middleware set) drives <html lang> and a window.__EQ_CULTURE__ = { name, formatName, strings } shell slot; boot installs it BEFORE hydration, so the client resolves exactly the strings the server rendered.
  • string.Format over an accessor is validated at build. EQ2100 rejects non-string arguments, format specifiers and arity drift against the neutral resx — the M0 subset of the plan's D7.

Still design (Track L, docs/I18N-PLAN.md)

Shipped above: the accessor rewrite, catalog emission, and the culture half of the shell bridge. Still ahead: setCulture re-rendering without a reload (M1), the CultureInfo → Intl formatting subset with its cross-culture arity diagnostic (M2 — culture-aware formatting in transpiled code today follows the browser's locale, not the request's; the divergence is named in the plan), satellites under AOT/trimming, and the SDK's own strings riding satellite resources behind the SdkStrings seam. RTL and per-script font coverage are explicitly other tracks.

🌐 English · Português

🏁 Start here

📱 Write-once

🏗️ Architecture

⚙️ Compilation

⚡ Runtime

🔌 Server

🎨 Ecosystem

🚀 Development

Clone this wiki locally