Arkheide.Essential.Culture.Avalonia 1.2.0

Essential.Culture

英文 | 简体中文

Essential.Culture is a JSON-based localization component for .NET.

It manages localization keys in a single Culture.json file, generates strongly typed keys through a Source Generator, and provides runtime culture switching for WPF, Avalonia, and WinUI 3.

Features

• Culture.json is the conventional JSON file name and is detected automatically.
• Source generation provides the CultureKey enum and a unified Localize XAML API for strongly typed keys and compile-time validation.
• KeyBinding allows collection items or runtime state to select localization keys dynamically.
• Localizer.Parse(...) and Localizer.TryParse(...) resolve localization keys and support format arguments.
• Localizer.Current provides runtime culture management.

Quick start

Install the appropriate package from NuGet.

For WPF:

dotnet add package Arkheide.Essential.Culture.Wpf

For Avalonia:

dotnet add package Arkheide.Essential.Culture.Avalonia

For WinUI 3:

dotnet add package Arkheide.Essential.Culture.WinUI

For other project types:

dotnet add package Arkheide.Essential.Culture

The package automatically creates Culture.json with default content. You can then define your own keys and translations:

{
  "Greeting": {
    "en-US": "Hello, World!",
    "zh-CN": "你好，世界！"
  },
  "Welcome_User": {
    "en-US": "Hello, {0}!",
    "zh-CN": "你好，{0}！"
  }
}

Start using it

WPF uses Localize, and format arguments can use bindings directly:

<Window xmlns:culture="clr-namespace:ArkheideSystem.Essential.Culture">
  <TextBlock Text="{culture:Localize Key=Greeting}" />
  <TextBlock Text="{culture:Localize Key=Welcome_User, Arg0={Binding UserName}}" />
  <TextBlock Text="{culture:Localize KeyBinding={Binding CurrentTextKey}}" />
</Window>

Avalonia uses the same API with different namespace syntax:

<Window xmlns:culture="using:ArkheideSystem.Essential.Culture">
  <TextBlock Text="{culture:Localize Key=Greeting}" />
  <TextBlock Text="{culture:Localize Key=Welcome_User, Arg0={Binding UserName}}" />
  <TextBlock Text="{culture:Localize KeyBinding={Binding CurrentTextKey}}" />
</Window>

Use the strongly typed Key= property so the editor can suggest keys from the generated CultureKey enum. When the key comes from the DataContext or runtime state, use KeyBinding=.

WinUI 3 exposes dynamic arguments through attached properties on the same Localize type:

<Window xmlns:culture="using:ArkheideSystem.Essential.Culture">
  <TextBlock Text="{culture:Localize Key=Greeting}" />
  <TextBlock Text="{culture:Localize Key=Welcome_User}"
             culture:Localize.Argument0="{x:Bind ViewModel.UserName, Mode=OneWay}" />
  <TextBlock Text="{culture:Localize}"
             culture:Localize.KeyBinding="{x:Bind ViewModel.CurrentTextKey, Mode=OneWay}" />
</Window>

Key and KeyBinding cannot be used together. Localize resolves the target text again whenever the static key, dynamic key, format arguments, or current culture changes. Applications do not need to subscribe to culture events themselves.

Source generation

The Generator automatically discovers Culture.json and copies it to the output directory during build and publish. By default, it generates the CultureKey enum, Key tokens, and the Localize static entry point used by UI projects:

namespace ArkheideSystem.Essential.Culture;

public enum CultureKey
{
    Greeting,
}

public static class Key
{
    public static string Greeting => "Key.Greeting";
}

using ArkheideSystem.Essential.Culture;
using GeneratedKey = global::ArkheideSystem.Essential.Culture.Key;

// Print the translated text
Console.WriteLine(Localizer.Parse(GeneratedKey.Greeting));

// Change the current culture
Localizer.Current.SetCulture("zh-CN");

// Print the translated text again without managing culture-change events
Console.WriteLine(Localizer.Parse(GeneratedKey.Greeting));

To override the namespace of generated types, add the following project setting:

<PropertyGroup>
  <EssentialCultureNamespace>MyApplication.Localization</EssentialCultureNamespace>
</PropertyGroup>

Automatic creation never overwrites an existing Culture.json. After it is created, edit the file directly to add your own localization keys and translations. To disable automatic creation, add this project setting:

<PropertyGroup>
  <EssentialCultureAutoCreate>false</EssentialCultureAutoCreate>
</PropertyGroup>

Packages

dotnet add package Arkheide.Essential.Culture
dotnet add package Arkheide.Essential.Culture.Wpf
dotnet add package Arkheide.Essential.Culture.Avalonia
dotnet add package Arkheide.Essential.Culture.WinUI

AI assistance

Documentation and examples

• Complete usage guide
• Demo overview
• Console Demo
• WPF Demo
• Avalonia Demo
• WinUI 3 Demo

License

Licensed under the MIT License.