Localization

[maikebing]

Thanks for the PR.

I think this should start as an Issue or Discussion first.

According to CONTRIBUTING, PRs that affect public API surface, architecture, or project direction require prior agreement. However, this PR does not link a related Issue or Discussion, and the PR template is mostly unfilled.

This is not just a localized string update. It introduces a ResourceManager-based string system, new public API surface, and a resource deployment model that may affect package layout, runtime behavior, and NativeAOT publish output.

Please move this to a proposal Issue or Discussion first. Before implementation, we need to agree on whether localization belongs in core, whether ResourceManager/resx is an appropriate direction, and what validation is required.

ResourceManager-based localization is especially relevant to MewUI’s NativeAOT direction because it can involve resource probing, culture fallback, and satellite resource deployment. Before adding this to the core library, we need to evaluate its effect on the actual NativeAOT publish result and whether that matches MewUI’s intended deployment model.

I will keep this as draft / not merge it in its current form.

Originally posted by @al6uiz in #155 (comment)

[al6uiz]

Proposal: NativeAOT-friendly Core Localization Model for MewUI

I would like to propose a core localization model for MewUI that works well with NativeAOT, small deployment size, and explicit package-based configuration.

The main idea is:

Use .resx files as the localization definition format, but do not use satellite assemblies at runtime.
Instead, selected .resx files are converted at build time into generated localization code and included directly in the NativeAOT output.

This proposal covers two related stages:

1. A MewUI package build model that produces MewUI and MewUI.Localization.{culture} packages from MewUI core resources.
2. An application build model where installed localization packages select which core and application .resx resources are integrated into the final NativeAOT output.

---

Goals

The proposed localization model has the following goals:

1. Default English resources are included in the MewUI core package.
2. Non-English MewUI core resources are separated into corresponding MewUI.Localization.{culture} packages.
3. An application explicitly selects which cultures are included in the final output by installing the required localization packages.
4. Application .resx resources can also be integrated into the same localization build infrastructure.
5. Satellite resource assemblies are not used.
6. Runtime ResourceManager lookup is not required.
7. Runtime XML or .resx parsing is not required.
8. Runtime dynamic assembly loading is not required.
9. NativeAOT builds include only the selected cultures.
10. Multiple localization packages can be registered to support runtime culture switching.

---

High-level Model

The proposed model can be summarized as:

resx-defined
package-produced
package-selected
source-generated
NativeAOT-included
satellite-free

The normal .NET localization model is usually:

.resx
  -> .resources
  -> satellite assembly
  -> ResourceManager

The proposed MewUI localization model has two stages:

MewUI package build
  -> MewUI
  -> MewUI.Localization.{culture}

Application build
  -> installed localization packages select cultures
  -> selected core and app .resx files become generated localization code
  -> generated code is included directly in the NativeAOT output

---

MewUI Package Build Flow

The MewUI source repository contains the canonical .resx files for core localization.

Example:

src/MewUI/Resources/Strings.resx
src/MewUI/Resources/Strings.ko-KR.resx
src/MewUI/Resources/Strings.ja-JP.resx
src/MewUI/Resources/Strings.zh-CN.resx

When MewUI packages are built, these core .resx files are used to produce the following NuGet packages:

MewUI
MewUI.Localization.ko-KR
MewUI.Localization.ja-JP
MewUI.Localization.zh-CN

The MewUI package contains:

localization infrastructure
build target / source generator
default English core resources
runtime localization API

Each MewUI.Localization.{culture} package is produced from the corresponding core .resx file for that culture.

Example:

Strings.ko-KR.resx
  -> MewUI.Localization.ko-KR

Each localization package contains:

culture marker
localized MewUI core resource payload
registration helper

The package does not rely on runtime satellite assemblies.

flowchart TD
    subgraph Repo["MewUI source repository"]
        SRC[Core source code]
        EN[Default English core .resx]
        KR[Core ko-KR .resx]
        JA[Core ja-JP .resx]
        CN[Core zh-CN .resx]
    end

    subgraph Pack["MewUI package build"]
        PACK[Pack targets]
    end

    subgraph Packages["Produced NuGet packages"]
        CORE[MewUI package]
        LKR[MewUI.Localization.ko-KR package]
        LJA[MewUI.Localization.ja-JP package]
        LCN[MewUI.Localization.zh-CN package]
    end

    SRC --> PACK
    EN --> PACK
    KR --> PACK
    JA --> PACK
    CN --> PACK

    PACK --> CORE
    PACK --> LKR
    PACK --> LJA
    PACK --> LCN

Loading

---

Runtime Package Roles

MewUI

The MewUI core package provides the localization infrastructure:

• MewUIString API
• localization runtime / registry
• default English strings
• optional CultureChanged notification
• build target / source generator integration point

The core localization scope is:

MewUI

Core strings are identified by scope and key:

MewUI / OK
MewUI / Cancel
MewUI / Apply

Internally, MewUI can use an SR wrapper so that code does not repeatedly use raw string keys.

Example concept:

SR.OK
SR.Cancel
SR.Apply

The SR wrapper resolves values through the MewUI localization runtime.

MewUI.Localization.{culture}

Non-English core localization is provided as culture-specific packages.

Package naming:

MewUI.Localization.{culture}

Examples:

MewUI.Localization.ko-KR
MewUI.Localization.zh-CN
MewUI.Localization.zh-TW
MewUI.Localization.ja-JP

For example, installing MewUI.Localization.ko-KR means:

1. The ko-KR culture marker is provided to the application build.
2. The MewUI core ko-KR resource payload is provided.
3. MewUI core ko-KR localization code can be included in the final NativeAOT output.
4. Application ko-KR .resx resources can also be integrated into the build using the same culture selection.
5. ko-KR can be registered as a runtime localization culture.

---

Application Resource Integration

Although this proposal is centered on MewUI core localization, the final NativeAOT output is produced by the application that references MewUI.

Therefore, application-defined resources should be able to participate in the same localization build infrastructure.

An application can define its own language resources using .resx files.

The installed MewUI.Localization.{culture} packages determine which cultures are enabled for the application build.

For example, if an application installs:

MewUI.Localization.ko-KR
MewUI.Localization.ja-JP

then the build enables:

ko-KR
ja-JP

The application may provide matching .resx files for those cultures.

Resources/Strings.resx
Resources/Strings.ko-KR.resx
Resources/Strings.ja-JP.resx
Resources/Strings.zh-CN.resx

In this case, only application .resx files matching the selected cultures are converted at build time.

Resources/Strings.ko-KR.resx -> included
Resources/Strings.ja-JP.resx -> included
Resources/Strings.zh-CN.resx -> not included

The application resource flow is:

Application .resx files
  -> selected by installed localization packages
  -> converted by MewUI.Localization build infrastructure
  -> included directly in the NativeAOT output

This allows application resources and MewUI core resources to share the same package-selected, source-generated, NativeAOT-friendly inclusion model.

Satellite assemblies, runtime .resx parsing, dynamic assembly loading, and runtime ResourceManager lookup are not required.

---

Application Build Flow

The application references the MewUI package and the required MewUI.Localization.{culture} packages.

Example:

MewUI
MewUI.Localization.ko-KR
MewUI.Localization.ja-JP

At application build time, the following inputs are used:

MewUI package
  -> localization infrastructure
  -> default English core resources

MewUI.Localization.ko-KR package
  -> ko-KR culture marker
  -> ko-KR MewUI core resource payload

MewUI.Localization.ja-JP package
  -> ja-JP culture marker
  -> ja-JP MewUI core resource payload

Application project
  -> application .resx files

As a result, the final NativeAOT output includes core localization code and application localization code for the selected cultures.

flowchart TD
    subgraph Packages["Referenced packages"]
        CORE[MewUI package]
        LKR[MewUI.Localization.ko-KR package]
        LJA[MewUI.Localization.ja-JP package]
    end

    subgraph App["Application project"]
        AR[Application .resx files]
        BUILD[Application build]
        OUT[NativeAOT output]
    end

    CORE --> BUILD
    LKR --> BUILD
    LJA --> BUILD
    AR --> BUILD
    BUILD --> OUT

Loading

Detailed flow:

flowchart TD
    A[MewUI.Localization.ko-KR installed] --> B[ko-KR culture marker provided]
    B --> C[ko-KR selected for application build]

    C --> D1[ko-KR core resource payload selected]
    C --> D2[ko-KR application .resx selected if present]

    D1 --> E1[ko-KR core localization code generated]
    D2 --> E2[ko-KR application localization code generated]

    E1 --> F[Included in NativeAOT output]
    E2 --> F

    F --> G[Runtime culture = ko-KR]
    G --> H[Core and application strings available]

Loading

---

Culture Marker

Each localization package provides a build-time culture marker through buildTransitive.

Conceptually:

MewUI.Localization.ko-KR
  buildTransitive/
    MewUI.Localization.ko-KR.props

The package provides:

MewUILocalizationCulture = ko-KR

If an app installs multiple localization packages:

MewUI.Localization.ko-KR
MewUI.Localization.zh-CN

Then the build sees:

MewUILocalizationCulture:
  ko-KR
  zh-CN

This culture list determines:

1. Which MewUI core resource payloads are converted into generated localization code.
2. Which application .resx files are converted into generated localization code.
3. Which cultures are included in the final NativeAOT output.

---

Registry Model

MewUI maintains a localization runtime / registry.

Providers are registered by:

culture + scope

Core examples:

ko-KR / MewUI
zh-CN / MewUI

A provider exposes:

1. culture name
2. scope
3. key-based string lookup

If the same culture + scope provider is registered more than once, the default behavior should be to fail.

Explicit replacement can be supported for advanced override scenarios.

---

Builder Registration Method Naming

The builder extension method should not repeat the MewUI prefix.

Recommended:

UseLocalizationKoKR()
UseLocalizationZhCN()
UseLocalizationJaJP()

The package name and infrastructure names may still keep the MewUI prefix:

MewUI.Localization.ko-KR
MewUIString
MewUILocalizationCulture
MewUILocalizationResource

For example, UseLocalizationKoKR() registers the MewUI core ko-KR provider.

---

Multiple Cultures

An app can install and register multiple localization packages.

Example:

MewUI.Localization.ko-KR
MewUI.Localization.zh-CN

Registration:

UseLocalizationKoKR()
UseLocalizationZhCN()

The final NativeAOT output includes generated localization code for both ko-KR and zh-CN.

At runtime, the active culture determines which provider is selected.

---

Runtime Culture Switching

Newly created UI can resolve strings using the current culture.

For already-created UI, MewUI needs a notification mechanism.

sequenceDiagram
    participant App
    participant Localization as MewUILocalization
    participant Binding as LocalizedString / Binding
    participant Runtime as MewUI localization runtime
    participant UI

    App->>Localization: SetCulture("ko-KR")
    Localization->>Binding: CultureChanged
    Binding->>Runtime: Resolve localized value
    Runtime-->>Binding: localized text
    Binding-->>UI: update text

Loading

For simpler applications, rebuilding the affected UI after changing the culture can also be acceptable.

---

Summary

The proposed model keeps .resx as the authoring format while avoiding runtime satellite assemblies.

The MewUI repository contains the source .resx files for core localization and produces the following packages during the MewUI package build:

MewUI
MewUI.Localization.{culture}

The MewUI package provides the localization infrastructure and default English resources.

Each MewUI.Localization.{culture} package provides the MewUI core resource payload and culture marker for that culture.

An application explicitly selects which cultures are included in the final NativeAOT output by installing the required localization packages.

Selected MewUI core resources and application .resx resources are converted at build time into generated localization code and included directly in the final NativeAOT output.

For example, installing:

MewUI.Localization.ko-KR

can include:

MewUI core ko-KR strings
Application ko-KR strings

as long as the corresponding .resx files exist.

This allows MewUI core localization and application resource integration to remain NativeAOT-friendly, explicit, and small by default.

[al6uiz]

I think the current work mixes two different concerns:

1. Moving core library string resources to MewUIString
2. Introducing the Localization System

The second item still needs more discussion around policy and structure.

Therefore, I think this work should be split into two separate PRs rather than included in a single PR.

In other words:

PR 1:
Move core library string resources to MewUIString as much as possible.

PR 2:
Introduce the Localization System based on the localization policy agreed in the Discussion.

Until the localization policy is finalized, localization can still be handled from outside the core by updating MewUIString values directly.

This keeps the first PR as a clear string-resource refactoring step, while leaving the policy and structure of the Localization System to be designed in the Discussion and handled in the second PR.

[lextm]

Just want to report that no other change is required in MewUI main repo except #154 when I tried to apply localization of this app with ProTranslate.

So, I wonder if there is really a need to modify MewUI itself, or at which degree the change should be.

[al6uiz]

Thanks for sharing your experience.

I think this is also why it would be better to split the PR. Since MewUI already has an exposure path for internal strings through MewUIString, I do not think introducing a full localization system is immediately urgent.

However, the hard-coded strings currently used in built-in UI elements exposed to application users, such as prompt dialogs and BusyIndicator, should still be cleaned up. Routing those strings through MewUIString would make them externally controllable without committing the core library to a full localization design yet.

I also think it is reasonable for MewUI to provide translations for the languages used by its main user base, at least for these built-in user-facing strings.

So my current suggestion is to separate the work into two parts:

1. First, move built-in user-facing strings in the core library to MewUIString as much as possible.
2. Then continue discussing whether MewUI should introduce an official localization system, and if so, what package/runtime/build model it should use.

That keeps the immediate PR focused and practical, while leaving the larger localization design open for proper discussion. As mentioned earlier, I do not think a ResourceManager-based approach fits well with the direction MewUI is trying to take. I would prefer to take more time here and collect more opinions before deciding on the official localization model.