Lang.Avalonia.Analysis 12.1.1.2

Lang.Avalonia

Lang.Avalonia 是面向 Avalonia UI 的插件化多语言库。核心包提供 XAML 标记扩展、绑定刷新流程、转换器、I18nManager 和 ILangPlugin 契约；资源加载由 JSON、XML、RESX 插件实现，也可以使用 Source Generator 生成强类型资源 Key。

包	NuGet	下载量
Lang.Avalonia
Lang.Avalonia.Json
Lang.Avalonia.Xml
Lang.Avalonia.Resx
Lang.Avalonia.Analysis

仓库规范

• 当前版本：12.0.3.5，版本号统一维护在根目录 Directory.Build.props 的 <Version> 节点。
• NuGet 包项目统一支持 net8.0;net10.0；Demo、App、测试与内部应用项目统一使用 net11.0 / net11.0-windows。
• 根目录 logo.svg、logo.png、logo.ico 是唯一图标源，子工程只通过 MSBuild Link 引用，不维护图标副本。
• 运行时帮助、Markdown 示例、内置备忘录、设计说明等业务文档按功能保留；仓库级入口文档使用根目录 README.md 和 UpdateLog.md。

功能

• 统一的 XAML 与 C# 多语言入口。
• 通过 I18nManager.Instance.Culture 运行时切换语言。
• JSON、XML、RESX 资源提供器统一实现 ILangPlugin。
• 支持默认文化回退和原始 Key 回退。
• 支持 T4 模板或 Lang.Avalonia.Analysis 生成强类型资源 Key。
• 支持固定文化预览、格式化字符串和动态绑定参数。

选择包

快速开始

安装核心包和一个资源提供器：

dotnet add package Lang.Avalonia.Json

应用启动时注册插件：

using Lang.Avalonia;
using Lang.Avalonia.Json;
using System.Globalization;

I18nManager.Instance.Register(new JsonLangPlugin(), new CultureInfo("en-US"), out var error);
if (!string.IsNullOrWhiteSpace(error))
{
    // 记录或展示初始化错误。
}

在 AXAML 中使用生成的常量：

xmlns:c="https://codewf.com"
xmlns:mainLangs="clr-namespace:Localization.Main"

<SelectableTextBlock Text="{c:I18n {x:Static mainLangs:MainView.Title}}" />
<SelectableTextBlock Text="{c:I18n {x:Static mainLangs:MainView.Title}, CultureName=ja-JP}" />

在 C# 中使用相同 Key：

var title = I18nManager.Instance.GetResource(Localization.Main.MainView.Title);
var englishTitle = I18nManager.Instance.GetResource(Localization.Main.MainView.Title, "en-US");

运行时切换语言：

I18nManager.Instance.Culture = new CultureInfo("zh-CN");

JSON 提供器

安装：

dotnet add package Lang.Avalonia.Json

每个文化一个文件，并将 JSON 文件复制到输出目录：

I18n/en-US.json
I18n/zh-CN.json
I18n/zh-Hant.json
I18n/ja-JP.json

<ItemGroup>
  <None Update="I18n\*.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

每个 JSON 文件都必须包含 language、description、cultureName 元数据：

{
  "language": "English",
  "description": "English resources",
  "cultureName": "en-US",
  "Localization": {
    "Main": {
      "MainView": {
        "Title": "Lang.Avalonia localization workspace",
        "ChangeLanguage": "Language"
      }
    }
  }
}

如果发现无效 JSON 文件，JsonLangPlugin.LoadDiagnostics 会包含被跳过文件的诊断信息。

XML 提供器

安装：

dotnet add package Lang.Avalonia.Xml

每个文化一个文件，并将 XML 文件复制到输出目录：

I18n/en-US.xml
I18n/zh-CN.xml
I18n/zh-Hant.xml
I18n/ja-JP.xml

<ItemGroup>
  <None Update="I18n\*.xml" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

每个 XML 文件都必须在根节点上包含 language、description、cultureName 元数据：

<?xml version="1.0" encoding="utf-8"?>
<Localization language="English" description="English resources" cultureName="en-US">
  <Main>
    <MainView>
      <Title>Lang.Avalonia localization workspace</Title>
      <ChangeLanguage>Language</ChangeLanguage>
    </MainView>
  </Main>
</Localization>

叶子节点路径会成为资源 Key。上面的示例会生成 Localization.Main.MainView.Title。 如果发现无效 XML 文件，XmlLangPlugin.LoadDiagnostics 会包含被跳过文件的诊断信息。

RESX 提供器

安装：

dotnet add package Lang.Avalonia.Resx

使用标准 .NET RESX 命名：

I18n/Resources.resx
I18n/Resources.zh-CN.resx
I18n/Resources.zh-Hant.resx
I18n/Resources.ja-JP.resx

建议使用完整资源 Key 作为 RESX 数据名称：

<data name="Localization.Main.MainView.Title" xml:space="preserve">
  <value>Lang.Avalonia localization workspace</value>
</data>

ResxLangPlugin 按文化同步资源，并通过与 JSON、XML 提供器相同的 ILangPlugin 契约对外提供资源。裁剪发布时建议显式传入生成的 ResourceManager，这样应用不需要为了 Lang.Avalonia.Resx 额外配置链接器 Root 文件：

using MyApp.I18n;

I18nManager.Instance.Register(
    new ResxLangPlugin(Resources.ResourceManager),
    new CultureInfo("zh-CN"),
    out var error);

也可以传入生成的资源 Designer 类型：

I18nManager.Instance.Register(
    new ResxLangPlugin(typeof(Resources)),
    new CultureInfo("zh-CN"),
    out var error);

ResxLangPlugin.Mark 默认值为 i18n。请让生成的资源 Designer 类型位于包含 I18n 的命名空间或文件夹下，或者显式设置 Mark：

I18nManager.Instance.Register(
    new ResxLangPlugin { Mark = "Resources" },
    new CultureInfo("en-US"),
    out var error);

按约定扫描保留用于兼容旧用法，但裁剪应用推荐使用显式注册。

强类型 Key

支持两种生成路径：

• 示例项目中的 T4 模板会从 JSON、XML 或 RESX 资源生成 I18n/Language.cs。
• Lang.Avalonia.Analysis 会从 AdditionalFiles 在编译期生成 Language.g.cs。

在应用项目中建议将 Lang.Avalonia.Analysis 作为私有构建期分析器：

<PackageReference Include="Lang.Avalonia.Analysis" Version="*" PrivateAssets="all" />

将 JSON、XML 或 RESX 语言文件注册为 AdditionalFiles：

<ItemGroup>
  <AdditionalFiles Include="I18n\*.json" />
  <AdditionalFiles Include="I18n\*.xml" />
  <AdditionalFiles Include="I18n\*.resx" />
</ItemGroup>

生成字段的值会保留原始资源 Key，只有 C# 标识符名称会被清洗。

对于以下资源 Key：

Localization.Main.MainView.Title

生成器会输出类似常量：

namespace Localization.Main;

public static class MainView
{
    public static readonly string Title = "Localization.Main.MainView.Title";
}

示例和设计说明

仓库包含四个示例：

设计文档和 SVG 图示见 docs/设计文档.md。

回退规则

资源查找顺序如下：

1. 显式 CultureName；未提供时使用 I18nManager.Instance.Culture。
2. Register 时传入的默认文化。
3. 原始资源 Key。

注意事项

• JSON 和 XML 提供器默认扫描 AppDomain.CurrentDomain.BaseDirectory。
• JSON 和 XML 提供器也可以通过 AddResource 读取嵌入资源。
• RESX 提供器在显式注册 ResourceManager 或资源 Designer 类型时，裁剪发布不需要为 Lang.Avalonia.Resx 配置 Root.xml。
• 资源 Key 和格式化参数均支持动态 Avalonia Binding。

第三方开源组件审计（2026-05-20）

检查方式：dotnet restore Lang.Avalonia.slnx、dotnet list package --include-transitive、NuGet .nuspec、NuGet.org 与源码仓库信息。优先接受 MIT / Apache-2.0 / BSD；其它开源协议在源码与传递依赖均可追溯时单独标注。

整改：

• 四个 Demo 已移除 AvaloniaUI.DiagnosticsSupport。
• Avalonia / Avalonia.Desktop 从 12.0.2 升级到 12.0.3。
• System.Drawing.Common 固定到 10.0.8。
• System.Text.Json 从 10.0.2 升级到 10.0.8。
• Prism.Avalonia、Prism.DryIoc.Avalonia 以及配套的 Irihi.Ursa.PrismExtension 继续保留在当前 8.x 兼容开源线，不升级到 Prism 9.x 商业化版本线。

传递依赖检查结论：Avalonia / Ursa / Semi / Prism / ReactiveUI / Roslyn / .NET 运行时与类库链路均有公开源码；有效项目文件中不再包含 AvaloniaUI.DiagnosticsSupport 或其它黑盒组件。

包版本维护约定

XML 文件统一使用两个空格缩进。Directory.Packages.props 统一承载 NuGet 中央包管理开关和包版本变量，包括 AvaloniaVersion 等共享版本属性；Directory.Build.props 仅保留项目构建、编译选项和 NuGet 元数据。仓库如引用 VC-LTL、YY-Thunks，这两个兼容旧版操作系统的特殊包必须使用最新预览版。