Sparkdo.Localization 3.0.0-preview.1

Sparkdo.Localization

字典式本地化的运行时包：资源（Resource）→ 贡献者（Contributor）→ 字典（Dictionary）三级模型， 按「精确文化 → 直接父文化 → 资源默认文化 → 基础资源链」回退取值；JSON 字典文件经 Sparkdo.Json 产品域源生成 context 直读 UTF-8（无反射 fallback、AOT 友好），文件来源是标准 IFileProvider。 AddSparkdoLocalization() 一行接线并替换标准 IStringLocalizerFactory，裸 ServiceCollection 零前置注册。

数据流：资源注册（Options）→ 首次 Create 懒初始化贡献者 → FrozenDictionary 文化字典 → 标准 IStringLocalizer 消费。

目录

• 快速开始
• 能做什么、不做什么
• 安装
• 寻址入口矩阵
• 回退链语义
• 全量枚举与支持文化
• DI 接线清单与替换面
• SparkdoLocalizationOptions 逐成员
• JSON 字典文件格式
• 文件贡献者与 IFileProvider
• 枚举本地化
• 主要类型逐成员语义
• 扩展点与实现契约
• 典型用法配方
• 调用期拒绝清单与异常一览
• 线程安全、缓存与生效时机
• 性能特征
• AOT 立场
• 常见坑
• 与其他包的关系

快速开始

资源类 + JSON 文件 + 一行接线

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Localization;
using Sparkdo.Localization;

public sealed class MyResource;                       // 资源标记类，不需要任何成员

services.AddSparkdoLocalization(options =>
{
    options.DefaultResourceType = typeof(MyResource);
    options.Resources.Add<MyResource>("en")            // "en" = 兜底文化
           .AddJsonFiles("Localization/MyResource");   // 相对 IFileProvider 根的目录
});

public sealed class MyService(IStringLocalizer<MyResource> localizer)
{
    public string Greet(string name) => localizer["Order.Greet", name];
}

Localization/MyResource/zh-Hans.json：

{ "culture": "zh-Hans", "texts": { "Order.Greet": "{0}，你好" } }

三个动作缺一不可：注册资源、挂贡献者、声明兜底文化。DefaultResourceType 指向的类型也必须 Add， 否则默认资源寻址直接抛出（fail-closed；见入口矩阵）。

不要文件：自己写贡献者

本域内置的只有 JSON 文件贡献者；内存/数据库来源请实现 ILocalizationResourceContributor （约 20 行，见配方 3）。贡献者的注册顺序就是优先级：后注册者优先。

不走容器

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.FileProviders;
using Microsoft.Extensions.Localization;
using Sparkdo.Localization;
using Sparkdo.Localization.VirtualFiles;

var resource = new NonTypedLocalizationResource("MyApp", "en");
var contributor = new JsonFileLocalizationResourceContributor(
    "Localization/MyApp", new PhysicalFileProvider(AppContext.BaseDirectory));

// 显式传了文件提供器时，这里的 ServiceProvider 只是占位以满足 Initialize 契约
// （只有不传文件提供器时，Initialize 才会从它解析 IFileProvider）
using var services = new ServiceCollection().BuildServiceProvider();
contributor.Initialize(new LocalizationResourceInitializationContext(resource, services));

IStringLocalizer localizer = new SparkdoDictionaryBasedStringLocalizer(
    resource, baseLocalizers: [], localizationOptions: new SparkdoLocalizationOptions());

这条路没有 IStringLocalizer<T> 注入、没有工厂缓存、没有全局贡献者，且必须自己调 Initialize。

能做什么、不做什么

安装

dotnet add package Sparkdo.Localization

目标框架 net10.0;net11.0；契约层见 Sparkdo.Localization.Abstractions（本包已传递引用）。

寻址入口矩阵

同一个资源对象，从不同入口进去能看到的内容不一样——这是本包最高频的误用来源：

四条推论：按名注册的资源类型入口看不见；DefaultResourceType 的类型必须也注册； Create(baseName, location) 是 resx 专用通道；资源名按 Ordinal 区分大小写。

ISparkdoStringLocalizerFactory 与 IStringLocalizerFactory 是两条描述符、同一个单例实例； CreateByResourceName* 等扩展声明在 IStringLocalizerFactory 上，所以注入标准接口再调扩展才是常规写法。

回退链语义

单键取值（localizer[key]）顺序：

• 第 2 档只走一级，CultureInfo.Parent 语义而非字符串切片：zh-Hans-CN → zh-Hans（不是 zh）、tr-TR → tr。 父文化名按文化名缓存（128 条上限），稳态零分配。
• 每档内部都是贡献者倒序扫描：同资源内后注册的先问，先命中即返回。全局贡献者在首次解析时追加到列表末尾， 因而优先级最高（覆盖资源自身贡献者）。
• 第 4 档是「另一个本地化器再走一遍它自己的 1→3」，按 BaseResourceNames 声明顺序； 只有目标文化与当前 CurrentUICulture 不同时才 CultureHelper.Use 换装。
• 基础资源名拼错不会有任何提示，那一级直接不存在（可选继承不该拖垮启动的代价）。
• 命中返回字典内预构建的 LocalizedString，SearchedLocation 恒为 null；未命中标记的 Value 就是键名。
• 带参索引器先查值再 string.Format；零参数时跳过格式化（字面花括号不会炸）。 格式化不带 provider：查值按 CurrentUICulture，占位符按 CurrentCulture。

全量枚举与支持文化

GetAllStrings 的分层覆盖顺序（逐层写进同一个 Ordinal 字典，后写覆盖）：

① includeBaseLocalizers 的基础本地化器（递归）
② includeParentCultures 时的资源默认文化
③ includeParentCultures 且文化名含 '-' 时的直接父文化
④ 精确文化（总是参与）

• 父文化两档由 includeParentCultures 控制，不看 TryToGetFromBaseCulture / TryToGetFromDefaultCulture。
• includeDynamicContributors: false 只在全量枚举里生效；单键取值永远会问动态贡献者。
• 基础本地化器是 resx 时，MissingManifestResourceException 在这里被当作「无内容」吞掉。
• 返回值是本次调用内构建的覆盖字典的值视图（零拷贝），可枚举但别强转写回。

GetSupportedCulturesAsync() 走贡献者层合并，多贡献者对同一文化的重复声明按 Ordinal 集合语义去重 （保留首次出现顺序）；JSON 里声明了 culture 但没有 texts 的文化仍会出现（支持但零键）。 非 Sparkdo 本地化器经扩展方法降级：三参枚举退化为标准 GetAllStrings(includeParentCultures)， GetSupportedCulturesAsync() 返回空集。

DI 接线清单与替换面

• 重复调用幂等：IStringLocalizerFactory 描述符数恒为 1。
• ITemplateLocalizer 与 SparkdoExceptionLocalizationOptions 不在清单内——本包只提供形状，不注册不实现。
• 裸 ServiceCollection 零前置：不需要 AddLocalization()、ILoggerFactory、IFileProvider。

SparkdoLocalizationOptions 逐成员

JSON 字典文件格式

{
  // 注释被接受
  "culture": "zh-Hans",
  "texts": {
    "Hello": "你好",
    "Menu": { "Settings": "设置", "Deep": { "Key": "深层值" } },   // → Menu__Settings / Menu__Deep__Key
    "List": [ "第一项", "第二项" ],                                  // → List__0 / List__1
    "Empty": null,          // → ""
    "Yes": true,            // → "True"
    "No": false,            // → "False"
    "Price": 1.50,          // → "1.50"（原样文本，保留书写形式）
    "Big": 1e3,             // → "1e3"
    "Multi": "a\r\nb\rc"    // → "a\nb\nc"（行尾统一为 \n）
  }
}

解析走 Sparkdo.Json 源生成 context（LocalizationJsonContext，[SparkdoJsonContext] 参与应用级 resolver 聚合）， texts 值先保持 JsonElement 再在构建期展平，成本全在构建路径。

文件贡献者与 IFileProvider

JsonFileLocalizationResourceContributor(directoryPath, fileProvider = null)：

• 目录路径相对文件提供器根；构造期归一（\ → /、剥首尾 /）为「无前导斜杠」形态。 于是 Loc、/Loc、Loc/、\Loc 对 Physical / Manifest / Composite / VFS 各提供器一致可见 （前导斜杠形态对 PhysicalFileProvider 不可见，这是移植时修掉的一处行为差异）。 归一只处理反斜杠与首尾斜杠：./Loc 这类点段前缀不会被剥掉，原样交给提供器，能否可用取决于提供器自己的规范化。 归一后为空（" "、"/"、"\\"）抛 ArgumentException（参数名 directoryPath），null 抛 ArgumentNullException。
• 文件来源优先级：显式传入的 IFileProvider > DI 注册的 IFileProvider > PhysicalFileProvider(AppContext.BaseDirectory)。 Sparkdo.VirtualFileSystem 注册的 IFileProvider 直接可用。
• 只扫一层，只认扩展名 .json（大小写不敏感）；子目录与其他文件忽略。
• 同文化多文件按文件名 Ordinal 升序合并，靠后者覆盖同键——排序是显式做的，不依赖提供器枚举序 （物理目录在 Linux 上是哈希序，靠枚举序会让覆盖关系漂移）。
• 懒构建 + 双检锁 + volatile 换出：首次访问才读目录并冻结，之后读路径无锁零分配。
• 热更新：首次构建注册一次 ChangeToken.OnChange(provider.Watch($"{dir}/*.*"))，触发即作废、下次访问重建。 目录直接子级的任何增删改都会触发，不只是 .json。
• 目录不存在 → 空集合，不抛。
• 必须先 Initialize（走工厂/AddJsonFiles 时自动）：否则取值抛 InvalidOperationException。
• 坏文件在首次取值时才炸：异常从 localizer[key] 冒出。启动期主动跑一遍配方 8。

AddJsonFiles(directoryPath) 与 AddJsonFiles(directoryPath, fileProvider) 是两个挂贡献者的糖， 后者不经 DI 解析（嵌入资源、组合根、测试替身优先用它），两个重载都返回资源对象本身以便继续链式配置。

枚举本地化

ISparkdoEnumLocalizer（已注册为单例），三阶键序、首个命中即返回：

Enum:{Type}.{Member}  →  {Type}.{Member}  →  {Member}  →  字面量兜底

public enum OrderStatus { Pending = 1, Shipped = 2 }

enumLocalizer.GetString(OrderStatus.Pending);                       // 默认资源；不装箱
enumLocalizer.GetString(OrderStatus.Pending, moduleLocalizer);      // 指定本地化器（元素可为 null，跳过）
enumLocalizer.GetString(typeof(OrderStatus), (object)status);       // 非泛型形态（值会被装箱）

• 第三阶只对已定义成员查表。未定义值与 [Flags] 组合直接回退其文本形式（(OrderStatus)7 → "7"、 Read|Write → "Read, Write"），永不返回 null。
• 整条链最多两个键串分配（裸成员名复用已到手的名串）。
• GetString(Type, object) 对非枚举类型抛 ArgumentException；泛型重载由 where TEnum : struct, Enum 编译期挡住。
• 默认资源不可得时最终只会拿到成员名本身——看起来"没本地化"，但不抛。

主要类型逐成员语义

AddSparkdoLocalization(this IServiceCollection, Action<SparkdoLocalizationOptions>? configure = null)

services 为 null 抛 ArgumentNullException；configure 允许为 null（等价于只接线不配置）。 返回同一个 services 引用。见上面的注册清单。

SparkdoStringLocalizerFactory

懒初始化做的事，按序：追加全局贡献者 → 逐个 contributor.Initialize(context) → 按 BaseResourceNames 递归创建基础本地化器（解析不到的名字跳过）→ 产出 SparkdoDictionaryBasedStringLocalizer。 环检测只针对当前执行流的重入（AsyncLocal 初始化栈），重入即抛带完整环路径的 InvalidOperationException； 跨线程的并发首次解析由工厂缓存的 Lazy(ExecutionAndPublication) 串行化，不会误判成环。

SparkdoDictionaryBasedStringLocalizer（公开、可继承，成员多为 protected virtual）

LocalizationResourceBase / LocalizationResource / NonTypedLocalizationResource

LocalizationResourceContributorList 是 List<ILocalizationResourceContributor> 的派生： GetOrNull 逆序索引扫描（零分配）、Fill / FillAsync 正序覆盖写入、 GetSupportedCulturesAsync 单贡献者透传 / 多贡献者去重合并。

JsonLocalizationDictionaryBuilder（静态）

StaticLocalizationDictionary

FrozenDictionary<string, LocalizedString> + Ordinal；值在构造期即预构建，读路径零分配。 CultureName 原样保留（不做大小写归一）。Fill 逐项写入目标字典（同键覆盖）。

ILocalizableStringSerializer / LocalizableStringSerializer

L:{resource},{name} / F:{value} 文本协议；Serialize(null) → null； 不认识的 ILocalizableString 实现抛 InvalidOperationException；反序列化用 Span 切片，不合规输入按固定文本兜底。 L:/F: 是文本协议而非查询语言：不做转义、不做版本协商；边界见配方 6 的表。

CultureHelper（静态）

LanguageInfo / ILanguageProvider / LanguageInfoExtensions / SparkdoLocalizationOptionsExtensions

LanguageInfo(cultureName, uiCultureName?, displayName?)：省略项回落为 cultureName， 派生 TwoLetterISOLanguageName；文化名非法即抛 CultureNotFoundException，空白抛 ArgumentException。 ChangeCulture(...) 同样不保留旧值。 ILanguageProvider.GetLanguagesAsync() 默认实现返回 options.Languages 的同一实例（零分配、非快照）。 FindByCulture(cultureName, uiCultureName?)：双向精确 → 仅 CultureName → 仅 UiCultureName，全不中 null。 AddLanguagesMapOrUpdate / GetLanguagesMap / GetCurrentUICultureLanguagesMap（LanguageFilesMap 同构）： 按 Name 就地更新既有 NameValue，查询未命中原样返回入参语言。

LocalizationSettingHelper / LocalizationSettingNames

ParseLanguageSetting("en-US;en") → (CultureName, UiCultureName)；单段合法则两段同值； 任一段非法、段数不为 2、或段内带空格（不修剪）都整体回退默认文化（"en"）；入参空白抛 ArgumentException。 LocalizationSettingNames.DefaultLanguage 值是移植保留的 "Abp.Localization.DefaultLanguage"， 本包只做常量与纯函数，不绑定任何设置存储。

预留缝

• ITemplateLocalizer：只有接口，无实现、无注册，留给模板处理产品。
• ExceptionHandling.SparkdoExceptionLocalizationOptions：错误码命名空间前缀 → 资源类型的映射表 （MapCodeNamespace 返回自身可链式；键按 Ordinal），供异常转 HTTP 一类消费者使用，本包不消费。
• NullExternalLocalizationStore：未注册外部存储时的默认实现，四个查询全部快速返回空。

扩展点与实现契约

典型用法配方

1. 一个资源的多种来源（覆盖顺序可控）

var resource = options.Resources.Add<MyResource>("en");
resource.AddJsonFiles("Localization/MyResource");        // ① 包内置（先注册 = 优先级低）
resource.Contributors.Add(new TenantContributor(...));    // ② 租户覆盖（后注册 = 优先级高）

单键取值与全量枚举都是后注册者赢，不会出现"查得到但枚举里没有"。

2. 默认资源 + 领域资源双层

options.DefaultResourceType = typeof(DefaultResource);
options.Resources.Add<DefaultResource>("en").AddJsonFiles("Localization/Default");
options.Resources.Add<IdentityResource>("en")
       .AddJsonFiles("Localization/Identity")
       .AddBaseResources("Default");

AddBaseResources 声明链 + LocalizableString 的默认资源兜底是两套独立机制，会同时生效。

3. 内存字典贡献者（最小实现）

using System.Collections.Frozen;
using Microsoft.Extensions.Localization;
using Sparkdo.Localization;

public sealed class DictionaryContributor(
    string cultureName,
    IReadOnlyDictionary<string, string> entries) : ILocalizationResourceContributor
{
    private readonly FrozenDictionary<string, LocalizedString> _entries =
        entries.ToFrozenDictionary(StringComparer.Ordinal);   // 预构建值，读路径直接复用

    public bool IsDynamic => false;

    public void Initialize(LocalizationResourceInitializationContext context) { }

    public LocalizedString? GetOrNull(string cultureName, string name)
        => cultureName == this.cultureName && _entries.TryGetValue(name, out var v) ? v : null;

    public void Fill(string cultureName, Dictionary<string, LocalizedString> dictionary)
    {
        if (cultureName == this.cultureName)
        {
            foreach (var entry in _entries)
            {
                dictionary[entry.Key] = entry.Value;
            }
        }
    }

    public Task<IEnumerable<string>> GetSupportedCulturesAsync()
        => Task.FromResult<IEnumerable<string>>([cultureName]);
}

4. 只在一段代码里换文化

using (CultureHelper.Use("zh-Hans"))
{
    RenderEmail();          // 期间的 localizer[...] 与 string.Format 都按 zh-Hans
}

AsyncLocal 语义，await 之后仍生效，Dispose 还原；不要跨并发工作项共享这个句柄的可见范围。

5. ASP.NET Core：让文化跟着请求走

app.UseRequestLocalization(new RequestLocalizationOptions()
    .AddSupportedCultures(["en", "zh-Hans", "tr-TR"])
    .AddSupportedUICultures(["en", "zh-Hans", "tr-TR"]));

中间件设好 CurrentCulture / CurrentUICulture，本包只认 CurrentUICulture.Name，不需要再包一层。

6. 可本地化字符串持久化

var serializer = provider.GetRequiredService<ILocalizableStringSerializer>();
string column = serializer.Serialize(LocalizableString.Create<MyResource>("Title"))!;   // "L:MyResource,Title"
entity.Title = serializer.Deserialize(column);
string shown = entity.Title.Localize(factory);

7. 语言下拉框与语言映射

var languages = await provider.GetRequiredService<ILanguageProvider>().GetLanguagesAsync();
var chosen = languages.FindByCulture(requestCulture, requestUiCulture);      // 可能为 null
var mapped = options.GetCurrentUICultureLanguagesMap("LeptonX");             // 未命中即原样返回当前语言
var (culture, uiCulture) = LocalizationSettingHelper.ParseLanguageSetting(settingValue);

DefaultLanguageProvider 返回的是 options.Languages 同一实例，UI 层别原地改。

8. 启动即校验资源，而不是等第一个请求

foreach (var name in options.Resources.Keys)
{
    var localizer = factory.CreateByResourceName(name);
    var cultures = (await localizer.GetSupportedCulturesAsync()).ToArray();   // 空 = 目录没找到或文件全被跳过
    _ = localizer["Startup.Probe"];                                           // 触发构建，坏文件在这里暴露
}

做完这一步，后续取值路径不会再碰文件。

9. 导出整份字典给工具链

var snapshot = localizer.GetAllStrings(includeParentCultures: true)
    .ToDictionary(s => s.Name, s => s.Value, StringComparer.Ordinal);

包含父文化与基础资源链的合并结果；只要当前文化的原文就传 includeParentCultures: false。

10. 只要契约层（不引本包）

库/包只依赖 ILocalizableString、IHasNameWithLocalizableDisplayName、ISparkdoStringLocalizerFactory 时， 只引 Sparkdo.Localization.Abstractions。工厂不是 Sparkdo 实现时 OrNull 系列安全降级为 null， 所以库侧写 factory.CreateDefaultOrNull()?.["Key"] 才不绑架宿主。

调用期拒绝清单与异常一览

本包不定义自定义异常类型，全部用 BCL 参数异常 + 中文诊断消息（以源码为准）。

线程安全、缓存与生效时机

• 工厂：ConcurrentDictionary<string, Lazy<IStringLocalizer>> + ExecutionAndPublication—— 同资源名的首次初始化只执行一次，之后读路径无锁零分配；同一资源反复解析返回同一实例。
• 环守卫：AsyncLocal 初始化栈（ImmutableStack<string>），只记录当前执行流正在初始化的资源名， 先于 Lazy.Value 判定，同执行流重入即抛（异常带完整环路径）；结束（含异常）恢复原栈，线程上下文无残留。 跨线程并发首次解析同一资源是合法的——由 Lazy(ExecutionAndPublication) 串行化，不会误报成环。
• 贡献者列表：List 派生，非线程安全。配置期改完再首次解析；首次解析时工厂会向它追加全局贡献者， 因此运行期不要再改已注册资源的贡献者列表。
• 文件贡献者：volatile 引用 + 双检锁构建；变更令牌触发即整体作废、下次访问重建。读并发安全。
• Options：IOptions<T> 首次解析即固定，之后的 Configure 不重放；Resources / GlobalContributors / Languages / LanguagesMap 是可变集合（改注册表不生效），而 DefaultResourceType 与两个回退开关每次现读。
• 本地化器：无状态（三个只读引用），可长期持有、跨线程共享。

性能特征

BenchmarkDotNet（ShortRun、InProcessEmitToolchain、MemoryDiagnoser；Intel i9-10900K、.NET 11 RC、Release；200 键字典）：

• 命中路径 = FrozenDictionary 查表 + 返回预构建实例，零分配且与键规模无关； 父文化回退多出的 ~10 ns 是一次缓存查名 + 二次查表。
• 未命中比命中贵 3 倍（48 B / 55 ns），别把未命中当常态控制流。
• 全量枚举与 JSON 解析都在构建/工具路径，不进热路径。JSON 解析走 Sparkdo.Json 源生成 context， 比第一版手写 Utf8JsonReader 慢约四成（决策记录 36 → 53 µs / 200 键，本次实测 55 µs，JsonElement 树物化的代价）， 换到的是 json 域策略统一与「无反射 fallback」。它只在首次访问或缓存作废时发生。
• 零分配回归门禁：LocalizationAllocationTests 断言精确命中、父文化回退命中、工厂缓存解析、文件贡献者命中为 0 B。

AOT 立场

• JSON 解析走 Sparkdo.Json 产品域源生成 context（[SparkdoJsonContext] 参与应用级 resolver 聚合）： 无反射序列化器、无 Dictionary<string, object> 装箱、无反射 fallback。
• 全局贡献者为委托工厂（AddGlobalContributor<T>()），无 Activator.CreateInstance。
• 反射仅剩资源名/继承特性的特性读取（按类型缓存、配置与首次解析期一次性）。
• IsAotCompatible + IsTrimmable，分析器零告警。

常见坑

与其他包的关系

• 依赖：Sparkdo.Localization.Abstractions（契约）、Microsoft.Extensions.Localization （ResourceManagerStringLocalizerFactory，标准 resx 回退所在包）、 Microsoft.Extensions.FileProviders.Physical（宿主未注册 IFileProvider 时的物理回退）、 Sparkdo.Json（JSON 字典解析与应用级 resolver 聚合）。 DI / Options / FileProviders.Abstractions / Logging.Abstractions 由 net11.0 隐式提供；net10.0 分支按框架条件显式声明。
• 与 Sparkdo.VirtualFileSystem 组合：VFS 注册的 IFileProvider 直接作为 JSON 字典文件来源，无需适配层。
• 与 Sparkdo.Localization.Abstractions 的分工：ILocalizableString 家族、资源命名与继承特性、 显示名扩展、ISparkdoStringLocalizerFactory 工厂缝在契约包；本包是字典、工厂、本地化器、 JSON 与文件贡献者、枚举、语言模型、序列化器与 DI 接线。
• 与 ABP（Volo.Abp.Localization）的关系：本包是其产品化移植（非 1:1）——模块系统 → DI 接线、 VFS 依赖 → 标准 IFileProvider 缝、Settings/EventBus/动态代理裁剪、Activator → 委托工厂、 反射序列化 → 源生成 UTF-8 直解析；行为修正与完整决策记录见仓库 src/localization/docs/port-analysis.md。