Engineering reference · 04

Add a language once.
The catalog follows the application.

Framework components, generated entity metadata, and authored application text converge into one catalog. A new culture is seeded from English, may be translated in resumable AI batches, and remains reviewable by a human.

Discoverable stringsPlaceholder-safe AIHuman review states

LanguagesContent.razor · simplifiedOne administrative action

var languageId = await operations
    .CreateLanguageAsync(new LanguageEditModel
    {
        Code = "de-DE",
        Name = "Deutsch",
        IsEnabled = true,
        SortOrder = 30
    }, ct);

await localization.SyncEntriesAsync(languageId, ct);

Seed sourceEnglish catalog

00 · COMPLETE FLOW

A language is configuration—not a rewrite.

The system discovers what can be translated before translators start. Adding a language creates the missing entries; it does not require rebuilding every page.

Localization workflow from framework, generated and application source catalogs through culture creation, translation review, and safe runtime fallback. — **Localization workflow**A new culture is synchronized and reviewed without rewriting application pages.

Discover catalog

Framework, generated, and application-owned sources contribute localizable keys.

Add culture

Store BCP-47 code, display name, enabled/default state, and ordering.

Seed & sync

Missing target entries are created from the English source catalog.

Translate & review

Edit manually or run resumable AI batches, then approve reviewed output.

01 · THREE SOURCE FAMILIES

The catalog knows where UI language originates.

Localization is not limited to resource files an engineer remembered to create. The framework derives keys from the same sources that define the application.

Framework

Component language

Connected components use their English text as the key for standard unkeyed strings such as paging and dialog labels.

Generated

Entity and page metadata

Display names, validation messages, entity labels, and generated page text receive stable keyed entries.

Application

Authored literals

Localizable component parameters and application UI text are discovered and checked by analyzers.

Design rule

English remains a readable source and safe fallback. The catalog layers translations over it instead of replacing meaning with opaque identifiers everywhere.

02 · SERVER + CLIENT

One culture crosses both rendering hosts.

The server localizer resolves catalog entries during server rendering. At client startup, the active culture is loaded from the authenticated application endpoint so WebAssembly continues with the same language.

Composite formats stay structured

Parameterized messages keep placeholders intact while translating the surrounding sentence. The runtime applies values only after selecting the localized format.

Server and browser share catalog meaning.
Missing translations safely display English.
Culture selection is application state, not duplicated page logic.
Catalog reconciliation adds newly discovered keys without erasing reviewed work.

Localized application text · conceptual examplePLACEHOLDER SAFE

var format = localizer[
    "Department {0} has {1} employees."];

var message = string.Format(
    CultureInfo.CurrentCulture,
    format,
    department.Name,
    employeeCount);

// Client startup obtains the active culture from:
"api/localization/current"

03 · REVIEWABLE STATES

Automation never hides translation provenance.

Each entry has an operational state. Teams can distinguish a fallback from machine output and distinguish machine output from reviewed business language.

State 01

Untranslated

The English source remains visible. Nothing becomes blank because a target value is missing.

State 02

Machine translated

AI output is stored as awaiting review, not silently presented as approved terminology.

State 03

Customized / reviewed

A person has approved or refined the phrase for the business and locale.

04 · AI TRANSLATION

Large catalogs translate in safe, resumable batches.

ICxAITranslator accelerates the mechanical first pass while retaining the safeguards needed for business software.

Batching

Resume instead of restart

Translation runs in bounded batches and continues from remaining entries.

Formats

Preserve placeholders

Tokens such as {0} must survive; suspicious output stays in English for correction.

Review

Approve deliberately

Machine status remains visible until a person accepts the result.

Safety

No blank failure mode

Rejected or unavailable AI output does not destroy the readable source.

Operations

Track remaining work

Administrators see translated, pending, and reviewed counts.

Terminology

Business language wins

Human edits preserve factory-specific meaning when a generic translation is insufficient.

05 · LOCALIZATION ANALYZERS

New features cannot quietly bypass the catalog.

Localization diagnostics turn common omissions into actionable engineering feedback while the author still has the code open.

Rule	What it finds	Required correction
CWE0209	Unlocalized user-facing text.	Route the string through the supported localization surface.
CWE0210	Interpolated runtime text used where a localizable composite format is required.	Localize the format and preserve structured placeholders.
CWE0211	A localizable parameter or usage with an incomplete localization shape.	Use the framework-supported key/value contract.
CWE0212	A localization composition that cannot be discovered or reconciled reliably.	Move the text into a catalog-visible source.

06 · ADDING A LANGUAGE

The operational checklist stays short.

The framework handles catalog breadth; the team remains responsible for culture choice, terminology quality, and release approval.

Create the language

Enter a valid BCP-47 code, name, enabled/default state, and sort order.

Synchronize entries

Seed all discovered source strings from the English catalog.

Translate

Work manually or run the resumable AI batch assistant.

Review terminology

Confirm placeholders, domain language, tone, and factory-specific vocabulary.

Enable and verify

Test server and client rendering in the target culture before release.

Next engineering page

See what the framework guarantees—and what remains developer responsibility.

Open evidence →

Add a language once.The catalog follows the application.