DuMes.Component.I18N 6.0.1

DuMes.Component.I18N

多脉本地化组件：按固定目录约定加载 JSON 文案，通过泛型资源类型 + 点号键解析多语言文本，并支持浏览器 Accept-Language。

项目结构

DuMes.Component.I18N/
├── Abstractions/                    # II18NService
├── Context/                        # 当前请求语言（AsyncLocal）
├── Extensions/                     # AddI18N / UseI18N / GetLanguage<T>
│                                   # I18NLibrarySegmentValidator（末段唯一性）
├── Middleware/                     # Accept-Language 解析
├── Options/                        # I18NOptions、I18NLanguageSettings
└── Services/                       # I18NService、I18NAccessor（静态入口）

功能概览

资源目录约定

输出目录（AppContext.BaseDirectory）下：

Resources/I18N/
├── zh-CN/
│   ├── Identity/                    ← DuMes.Module.Identity 的末段
│   │   └── SystemI18N.json          ← GetLanguage<SystemI18N>()
│   └── FastEndpoints/               ← DuMes.Component.FastEndpoints 的末段
│       └── FastEndpointsI18N.json   ← GetLanguage<FastEndpointsI18N>()
└── en/
    ├── Identity/
    │   └── SystemI18N.json
    └── FastEndpoints/
        └── FastEndpointsI18N.json

路径公式：

Resources/I18N/{culture}/{程序集名最后一段}/{标记类型名}.json

示例：

提供资源的项目需将文件复制到输出目录，例如：

<None Include="Resources\**\*.*">
  <CopyToOutputDirectory>Always</CopyToOutputDirectory>
</None>

JSON 示例

{
  "Test": {
    "V1": "测试V1"
  },
  "TestV2": "测试V2",
  // 支持注释与尾逗号
  "Count": 3
}

对应键：Test.V1、TestV2、Count（数字/布尔/null 会转为字符串；数组不参与扁平化）。

接入

1. 引用

Host 或消费方 ProjectReference / NuGet 引用本组件。依赖 DuMes.Component.Serilog（缺失键警告落盘到 logs/language_warning.log）。

建议 Host 同时接入 Serilog 管道（builder.Host.UseComponentSerilog()），否则 WriteWarning 可能无法按预期写文件。

若使用模块宿主 Swagger 语言下拉，还需引用 DuMes.Component.FastEndpoints，并保证 AddI18N 在 AddModules 之前。

2. 配置 appsettings.json

I18N 节与 DefaultLanguage 为必填。SupportedLanguages：

• 用于 Swagger 下拉与运行时匹配
• 未配置或为空时自动回退为仅含 DefaultLanguage
• 若列表不含默认语言，会自动插入到首位
• 每个语言必须存在 Resources/I18N/{culture}/ 目录，否则启动失败

{
  "I18N": {
    "DefaultLanguage": "zh-CN",
    "SupportedLanguages": [ "zh-CN", "en" ]
  }
}

3. Program.cs

using DuMes.Component.I18N.Extensions;

builder.Services.AddI18N(builder.Configuration);   // 须在 AddModules 之前
builder.Services.AddModules(...);

var app = builder.Build();

app.UseI18N();   // 须在业务中间件 / Endpoint 之前

4. 定义资源标记类型

namespace DuMes.Module.Identity;

/// <summary>对应 Resources/I18N/{culture}/Identity/SystemI18N.json</summary>
public abstract class SystemI18N;

5. 使用

using DuMes.Component.I18N.Extensions;

var text = "Test.V1".GetLanguage<SystemI18N>();

必须传入泛型；由类型所在类库末段 + 类型名定位 JSON。

• GetLanguage<T>()：依赖静态入口，须已调用 UseI18N
• 注入 II18NService：仅需 AddI18N 即可

语言匹配规则

1. 解析请求头 Accept-Language（按 q 值降序；* 忽略）
2. 与配置的 SupportedLanguages 及磁盘上额外的语言目录做忽略大小写匹配
3. 匹配顺序：
   • 精确匹配（zh-CN → zh-CN）
   • 请求为裸主语言时（如 zh）→ 可匹配同主语言的区域变体（如 zh-CN；多条时取列表第一个）
   • 请求带区域时（如 zh-TW）→ 不匹配兄弟方言（zh-CN）；仅当存在纯主语言标签 zh 时才回退到 zh
4. 未匹配则使用 I18N:DefaultLanguage
5. 取文案时：当前语言 → 默认语言 → 仍无则回退为键本身
   （若当前语言标签因大小写等原因无法映射到磁盘目录，等同直接走默认语言）

非 HTTP 场景（无请求上下文）直接使用默认语言。

注意事项

1. 路径固定：Resources/I18N/{culture}/{类库末段}/{TypeName}.json。
2. 类库末段唯一：若多个程序集末段名相同，且各自都定义了与 Resources/I18N/*/{末段}/*.json 文件名对应的标记类型，则视为冲突；AddI18N 与 UseI18N 均会校验，重复则直接抛错退出，不写日志。不按程序集业务名称前缀过滤。
3. 类型名 = JSON 文件名：GetLanguage<SystemI18N>() 读取 SystemI18N.json。
4. 复制到输出：未设置 CopyToOutputDirectory 时，配置语言目录缺失会导致启动失败；单个 JSON 文件缺失则回退为键并写 language_warning。
5. 先 Add 再 Use：未调用 UseI18N 时 GetLanguage 会抛未初始化异常；注入 II18NService 不受此限。
6. 中间件顺序：UseI18N 须在 Endpoint 之前；AddI18N 须在 AddModules 之前（否则 Swagger 无语言下拉）。
7. 缺失不抛错：找不到键时返回键本身，详情见 logs/language_warning.log。
8. 键大小写敏感：Test.V1 ≠ test.v1。
9. 数组不支持：JSON 数组不参与扁平化查找；注释、尾逗号、数字/布尔/null 可用。
10. 资源缓存：成功读到的 JSON 会缓存至进程结束；文件不存在不缓存（开发期补文件后下次请求可加载，无需为 miss 重启）。JSON 内容变更仍需重启进程。