Sparkdo.Localization.Abstractions 3.0.0-preview.1

Sparkdo.Localization.Abstractions

Sparkdo 本地化契约层：可本地化字符串对象模型（ILocalizableString 家族）、 资源命名与继承特性、显示名解析扩展，以及置于 Microsoft.Extensions.Localization 命名空间的工厂扩展缝。它不含任何字典、解析或缓存实现——只定义形状，让库/包能依赖本地化 而不绑架宿主的实现选型。

除本地化生态的公共货币 Microsoft.Extensions.Localization.Abstractions（LocalizedString / IStringLocalizer / IStringLocalizerFactory）外零外部依赖（Microsoft.Extensions.Localization.Abstractions 平台不内置，net10.0 与 net11.0 都显式引用）；IsAotCompatible / IsTrimmable。

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

ILocalizableString title = LocalizableString.Create<MyResource>("Title");  // 按资源类型
string text = title.Localize(localizerFactory);                            // 现在才解析

目录

• 什么时候只引这个包
• 安装
• 类型清单
• ILocalizableString：延迟取值的契约
• LocalizableString 逐成员语义
• FixedLocalizableString
• LocalizableStringExtensions：统一异步入口
• 资源命名：LocalizationResourceNameAttribute
• 资源继承：为什么不在本包
• 显示名解析：IHasNameWithLocalizableDisplayName
• 工厂扩展缝：ISparkdoStringLocalizerFactory
• 实现自己的 ILocalizableString
• 典型用法配方
• 调用期拒绝清单与异常一览
• 设计立场
• 常见坑
• 与其他包的关系

什么时候只引这个包

安装

dotnet add package Sparkdo.Localization.Abstractions

目标框架 net10.0;net11.0。

类型清单

ISparkdoStringLocalizerFactory 及其扩展刻意放在 Microsoft.Extensions.Localization 命名空间： 它们是标准 IStringLocalizerFactory 的扩展位，调用方只需要 using 一个命名空间就能同时拿到标准接口与本包扩展。

ILocalizableString：延迟取值的契约

public interface ILocalizableString
{
    LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory);
}

三条契约义务：

1. 实现自己负责把资源解析完（按类型 / 按名字 / 默认资源），调用方只交出一个工厂。
2. 找不到资源或键返回 ResourceNotFound = true 的标记值（Value == Name），不抛异常—— 兜底文案是调用方的决定，不是取值的失败。
3. 契约不承诺幂等与缓存：同一实例多次 Localize 允许返回不同实例（FixedLocalizableString 每次都新建）。 需要「解析一次长期持有」请自己把结果存成 string。

LocalizedString 到 string 有隐式转换，所以 string s = x.Localize(factory); 取到的是 Value； 想区分「真的取到了」和「兜底回显」必须看 ResourceNotFound。

LocalizableString 逐成员语义

var byType = LocalizableString.Create<MyResource>("Title");            // 推荐：编译期可查
var byTypeObj = LocalizableString.Create(typeof(MyResource), "Title"); // 运行期类型
var byName = LocalizableString.Create("Title", "MyResource");          // 只有名字（跨程序集/无类型可见性）
var bare = new LocalizableString("Title");                              // 无归属 → 直接走默认资源

解析顺序（同步与异步一致）：

ResourceType 非空 → factory.Create(resourceType)
    ↓ 否则
ResourceName 非空 → factory.CreateByResourceNameOrNull(resourceName)   // 本地注册表 → 外部存储
    ↓ 仍为 null 或 ResourceType/ResourceName 都为空
factory.CreateDefaultOrNull()
    ↓ 仍为 null
返回 new LocalizedString(Name, Name, resourceNotFound: true)

拿到本地化器后查 localizer[Name]；若 ResourceNotFound 且本对象有 ResourceName，
再对默认资源查一次（无归属的对象本来就打在默认资源上，没有第二枪）

要点：

• 按类型构造只走类型入口，因此它看不见按名注册的资源，也不查外部存储； 按名构造才能命中这两者。
• 「目标资源未命中 → 再兜默认资源」这一步只在 ResourceName != null 时发生。 这是同步与异步共同的行为，不存在"异步更严格"的分支（源实现的 LocalizeAsync 在造不出本地化器时抛异常， 移植时统一为标记返回）。
• 本类型是引用类型且不重写相等性：别把它当值放进字典键或用它做 == 比较。
• 没有 ToString() 重载，隐式转换只存在于 LocalizedString → string 一侧。

FixedLocalizableString

var fixedText = new FixedLocalizableString("MIT License");
fixedText.Localize(anyFactory);   // new LocalizedString("MIT License", "MIT License")

• 完全不经资源查找，也不接收 null（ArgumentNullException，参数名 value）。
• 产出的 LocalizedString 里 Name 与 Value 同为该文本，ResourceNotFound 恒为 false—— 哪怕文本长得像未命中的键。
• 不做任何修剪/规范化，也不会被格式化："{0}" 就返回 "{0}"。 需要占位符请走 IStringLocalizer 索引器（那是宿主的格式化决定）。
• 每次 Localize 新建一个 LocalizedString（未缓存）。高频调用请自己解析一次存成 string。
• 适用场景：配置里直接给出的字面量、第三方系统传回的不该被本地化的文本、序列化的 F: 兜底。

LocalizableStringExtensions：统一异步入口

public static Task<LocalizedString> LocalizeAsync(
    this ILocalizableString localizableString,
    IStringLocalizerFactory stringLocalizerFactory);

• 调用方不需要知道实现是不是 IAsyncLocalizableString：是就转给它，否则同步取值再包 Task.FromResult （不额外起线程、不 Task.Run）。
• localizableString 为 null 抛 ArgumentNullException；stringLocalizerFactory 的 null 检查 在实现侧（同步 Localize 里）而非扩展里。
• 这是本包唯一把「同步/异步」两条路收敛成一个入口的地方；自己写实现时建议同时实现 IAsyncLocalizableString，否则异步调用点只是白转一圈。

资源命名：LocalizationResourceNameAttribute

[LocalizationResourceName("MyApp")]        // 稳定资源名，跨版本重命名类型不影响资源键
public sealed class MyAppResource;

三个必须知道的推导细节：

• 只允许标注在类上（AttributeTargets.Class，AllowMultiple = false）——接口、结构、枚举标不上。
• inherit: true 会沿基类找：class TenantResource : CommonResource 而 CommonResource 标了名字时， 子类型推导出的资源名就是基类的名字，两者注册会撞名（Add 抛 InvalidOperationException）。
• 未标注时用 Type.FullName，包含命名空间；所以重构命名空间会改变资源名。想稳定就必须显式标注。 DefaultResource（在运行时包）自带标注，名字是 "Default"。
• 开放泛型类型（typeof(List<>)）有全名，得到 "System.Collections.Generic.List1"这种能用的名字； **真正的泛型参数**（方法内typeof(T)）没有全名，抛 InvalidOperationException("资源类型 T 是泛型参数或开放泛型，无法推导资源名，请标注 LocalizationResourceNameAttribute。")`。
• 缓存按 Type 为键且永不清理：正常应用的类型数量有限，无需担心；但它意味着 标注错误的名字一旦解析过就被记住。

资源继承：为什么不在本包

资源继承（InheritResourceAttribute、IInheritedResourceTypesProvider、AddBaseTypes / AddBaseResources） 属于运行时包 Sparkdo.Localization：声明继承只是往资源的 BaseResourceNames 里加名字， 而把名字解析成本地化器、按链回退取值都需要资源注册表与工厂，本包没有也不该有这些。

本包只负责链条上的最小一环：「资源类型 → 稳定资源名」（LocalizationResourceNameAttribute.GetName）。 库侧给资源类型标注名字就够了；是否继承、继承谁，由接了运行时包的宿主决定。

显示名解析：IHasNameWithLocalizableDisplayName

public interface IHasNameWithLocalizableDisplayName
{
    string Name { get; }
    ILocalizableString? DisplayName { get; }
}

这是权限定义、设置定义、功能定义这类对象在 Sparkdo 各域共享的形状。解析扩展：

string displayName = definition.GetLocalizedDisplayName(localizerFactory);
string bareNameOnly = definition.GetLocalizedDisplayName(localizerFactory, localizationNamePrefix: null);

解析链（自上而下，首个成立即返回）：

① 显式 DisplayName（非 null）→ DisplayName.Localize(factory)
② 默认资源 CreateDefaultOrNull() 不可得 → 直接返回 source.Name（一次查表都不做）
③ defaultStringLocalizer["{prefix}{Name}"]（默认 prefix = "DisplayName:"）未命中则继续
④ defaultStringLocalizer[source.Name]

工厂扩展缝：ISparkdoStringLocalizerFactory

public interface ISparkdoStringLocalizerFactory
{
    IStringLocalizer? CreateDefaultOrNull();
    IStringLocalizer? CreateByResourceNameOrNull(string resourceName);
    Task<IStringLocalizer?> CreateByResourceNameOrNullAsync(string resourceName);
}

它不继承 IStringLocalizerFactory——它是"能力探针"式的附加缝，由实现方同时实现两个接口。 调用侧一律经 SparkdoStringLocalizerFactoryExtensions 在标准 IStringLocalizerFactory 上使用：

三条纪律：

1. 入参校验在实现侧。resourceName 为 null/空白时：标准（非 Sparkdo）工厂返回 null， Sparkdo 工厂抛 ArgumentException——这是刻意的降级方向（库侧不因宿主实现不同而抛异常）， 但意味着你不能指望扩展方法替你校验参数。
2. OrNull 用于「问一问」，非 OrNull 用于「必须要」。库代码优先用 OrNull 再自己兜底文案。
3. 异步只服务于外部存储的资源发现。本地字典资源的实现是同步完成的快速路径， 调用方仍应 await（别 .Result），以便实现方将来换成真异步。

localizerFactory 为 null 时五个扩展方法都抛 ArgumentNullException——两个非空断言版本经内部转调 OrNull 版本，因此也是先参数校验、后资源判定。

实现自己的 ILocalizableString

典型动机：资源归属要运行期决定、需要远程取词、或者想给"未命中"绑定业务兜底文案。

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

/// 按「租户资源 → 公共资源 → 默认资源」顺序取值，全不中给业务兜底。
public sealed class TieredLocalizableString(string name, string? tenantResource)
    : ILocalizableString, IAsyncLocalizableString
{
    public LocalizedString Localize(IStringLocalizerFactory factory)
    {
        ArgumentNullException.ThrowIfNull(factory);

        foreach (var resourceName in CandidateResources())
        {
            var localizer = factory.CreateByResourceNameOrNull(resourceName);
            if (localizer is null)
            {
                continue;                       // 该层不存在：跳过，不是失败
            }

            var result = localizer[name];
            if (!result.ResourceNotFound)
            {
                return result;
            }
        }

        return new LocalizedString(name, DefaultText);
    }

    public Task<LocalizedString> LocalizeAsync(IStringLocalizerFactory factory)
        => Task.FromResult(Localize(factory));   // 无外部存储时保持同步完成

    private IEnumerable<string> CandidateResources()
    {
        if (tenantResource is not null)
        {
            yield return tenantResource;
        }

        yield return "Common";
    }
}

实现清单（8 条，来自本包契约与运行时包的实现约定）：

1. Localize 不因未命中抛异常；未命中要么返回标记，要么返回你自己的兜底值。
2. 同步与异步同时实现时，两条路径语义必须一致（同一入参、同一层的兜底顺序）。
3. 只做一次工厂解析就返回；不要把 IStringLocalizer 缓存在实例字段里（工厂与资源注册表都可能换）。
4. 实现 IAsyncLocalizableString 时，没有真异步来源就用 Task.FromResult，别 Task.Run 包同步。
5. 需要构造期校验就把校验放在构造器（本包的 LocalizableString 就是这样：空白 name 立即抛）。
6. 别重写 ToString() 来"返回文本"——调用方用的是 Localize，重写只会制造两种真相。
7. 类要保持不可变（readonly/init）；实例可能被抓进配置或缓存里长期持有。
8. 若你的实现要能被序列化（ILocalizableStringSerializer），运行时包只认它的两种类型， 其它实现会抛 InvalidOperationException——那种场景请自己提供序列化器实现。

典型用法配方

1. 库侧暴露"可本地化的东西"而不绑架实现

public sealed class MyFeatureDefinition
{
    public string Name { get; init; } = string.Empty;
    public ILocalizableString? DisplayName { get; init; }      // 宿主决定怎么本地化
}

// 消费端（宿主）
var shown = definition.DisplayName?.Localize(factory) ?? definition.GetLocalizedDisplayName(factory);

ILocalizableString 出现在公共 API 上时，调用方只需要一个 IStringLocalizerFactory 就能取文本， 不需要注册任何资源。

2. 判"是否真取到了值"必须看 ResourceNotFound

var result = value.Localize(factory);
if (result.ResourceNotFound)
{
    logger.LogWarning("本地化键缺失：{Name}", result.Name);
    return Fallback;                    // 隐式转 string 会拿到回显的键名
}

return result;

Value == Name 就是未命中的信号，但用 ResourceNotFound 判定才不会被「键名恰好等于译文」骗过去。

3. 只要名字、跨程序集寻址

var text = LocalizableString.Create("Menu.Settings", "Acme.Ui").Localize(factory);

按名寻址会同时命中「按名注册的资源」和外部存储提供的资源；按类型寻址则要求类型对宿主可见。

4. 给不可见类型准备兜底：默认资源

ILocalizableString any = new LocalizableString("Some.Key");    // 无归属 → 直接打在默认资源上

无归属对象没有「第二枪」（本来就打在默认资源）；有归属的对象未命中时会再兜一次默认资源。

5. 固定文本参与同一套模型

ILocalizableString license = new FixedLocalizableString("MIT");
string shown = license.Localize(factory);      // "MIT"，与有没有默认资源、什么文化都无关

这让「一部分字段要本地化、一部分不该」的模型保持单一类型。

6. 异步取值（外部存储场景）

var text = await someValue.LocalizeAsync(factory);   // 扩展方法：有异步实现就走，没有就同步包一层

调用方永远写 LocalizeAsync，实现方按需实现 IAsyncLocalizableString。

7. 标准工厂宿主下的安全降级

// 宿主只调了 AddLocalization()（工厂不是 Sparkdo 实现）
var localizer = factory.CreateDefaultOrNull();          // null，不抛
var text = localizer is null ? key : localizer[key];

本包扩展的设计目标就是：在任意 IStringLocalizerFactory 上都能编译并安全运行， 能力缺失表现为 null，不是异常。

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

不会抛的情况：任何「资源或键未命中」的取值路径——返回 ResourceNotFound 标记。

设计立场

• 契约不抛异常：未命中是数据状态，不是错误；兜底文案由调用方决定。
• 能力探针而非继承：ISparkdoStringLocalizerFactory 不继承标准工厂，标准实现上安全降级为 null， 库代码因此不依赖宿主接了哪一套本地化实现。
• 同步/异步语义必须一致：源实现的 LocalizeAsync 在工厂造不出本地化器时抛异常而同步路径返回标记， 移植时统一为标记返回（决策记录见运行时包的移植分析文档）。
• 名字推导按类型缓存，热路径零反射；inherit: true 保持与生态一致（子类可共享基类资源名）。
• 扩展缝放进生态的标准命名空间（Microsoft.Extensions.Localization），与扩展方法的目标类型同域， 调用侧少一个 using。
• 零运行时依赖：不引 DI、不引 Options、不引文件系统；只有 LocalizedString 这套生态货币。

常见坑

与其他包的关系

• 依赖：仅 Microsoft.Extensions.Localization.Abstractions（LocalizedString / IStringLocalizer / IStringLocalizerFactory；net11.0 的平台隐式引用不覆盖该包，故显式登记）。
• 实现层：Sparkdo.Localization（字典式本地化器与文化回退链、JSON 字典解析、IFileProvider 文件贡献者、 枚举本地化、语言模型、序列化器、AddSparkdoLocalization() 接线）。它引用本包，方向不可逆。
• 消费方：任何「公共 API 里有 ILocalizableString 或 IHasNameWithLocalizableDisplayName」的 Sparkdo 域 只依赖本包即可发布，宿主是否接运行时包由宿主决定。