XiHan.Framework.Localization.Database 5.0.0-preview.1

Prefix Reserved
.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher.
This is a prerelease version of XiHan.Framework.Localization.Database.
There is a newer prerelease version of this package available.
See the version list below for details. 
dotnet add package XiHan.Framework.Localization.Database --version 5.0.0-preview.1
                    


                    

                
NuGet\Install-Package XiHan.Framework.Localization.Database -Version 5.0.0-preview.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="XiHan.Framework.Localization.Database" Version="5.0.0-preview.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="XiHan.Framework.Localization.Database" Version="5.0.0-preview.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="XiHan.Framework.Localization.Database" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add XiHan.Framework.Localization.Database --version 5.0.0-preview.1
                    


                    

                
#r "nuget: XiHan.Framework.Localization.Database, 5.0.0-preview.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package XiHan.Framework.Localization.Database@5.0.0-preview.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=XiHan.Framework.Localization.Database&version=5.0.0-preview.1&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=XiHan.Framework.Localization.Database&version=5.0.0-preview.1&prerelease
                    


                            Install as a Cake Tool

XiHan.Framework.Localization.Database

localization.resources@1 的数据库 Provider（Ring 3，role: provider，RFC-0010）。翻译以 MessageTranslation（键、区域、模板）经 persistence.relational@1 的仓储读写；数据库里的翻译优先于嵌入的语言文件，没有的键仍走嵌入目录与回退链。装配后顶替默认的 Localization.InMemory。

builder.AddXiHan(x => x
    .UseFeature(new EntityFrameworkCorePersistenceFeature<AppDbContext>(static (binding, o) => o.UseNpgsql(binding.ValueOrThrow().Value)))
    .UseFeature<DatabaseLocalizationFeature>());

// AppDbContext.OnModelCreating：登记实体后应用协议约定，键与区域的唯一索引由实体上的 [EntityIndex] 建出
modelBuilder.Entity<MessageTranslation>();
modelBuilder.ApplyPersistenceConventions(Database);

// 管理操作的 HandleAsync 里（Transaction 阶段内）批量写入；事务在这次调用返回时才提交
var results = await store.UpsertAsync([new MessageTranslationEntry("orders.order.not_found", "zh-CN", "订单 '{id}' 找不到。")], context.CancellationToken);

// 写入的调用成功返回之后（事务已提交）再重载，快照立即生效；在同一个操作里紧接着重载读不到未提交的行
var reloaded = await loader.ReloadAsync(cancellationToken);

{ "XiHan": { "Localization": { "DefaultLocale": "en-US", "Database": { "RefreshIntervalSeconds": 300, "MaxTranslations": 100000 } } } }

规则

  • DatabaseMessageLocalizer：每个回退区域先查数据库快照再查目录，其余语义与内存实现一致（通过 Localization.Conformance）。
  • MessageTranslationLoader：宿主进入服务状态后经完整管道分页加载（按 ID，每页 1000，最多 MaxTranslations 条，超出记警告），整份替换快照；按 RefreshInterval 刷新（0 关闭）；失败保留上一份快照并记到 LastError。
  • 健康项 localization.database.translations（加载器自己实现，以最近一次加载的结果上报，不另起探测循环）：还没加载过为 Started，加载成功为 Ready，最近一次加载失败为 Degraded（错误是那次加载的失败），应用仍在服务。
  • MessageTranslationStore（作用域）：UpsertAsync / RemoveAsync 批量逐项结果（不存在 → LOCALIZATION_NOTFOUND_001），ListAsync 分页；只能在调用的 Transaction 阶段内使用。UpsertAsync 先按 (键, 区域) 查已有的行（键每 1000 个一批、结果按标识分页读完），已有的更新、没有的新增——同一键与区域再写一次是更新，不会写出第二行（早先只读第一页，已有行超过 1000 条时超出的被当成新行再插一遍）。两个调用同时新增同一个键与区域：后插入的撞上唯一索引，那一批新增的项返回 PERSISTENCE_CONFLICT_003、调用回滚，重试即按更新处理（ADR-0072）；内存持久化不建索引、不校验唯一性。
  • 键须符合消息键文法，区域规范化大小写；重复的键与区域由唯一索引 UX_MessageTranslation_Ke_Lo（(Key, Locale)，实体上的 [EntityIndex]，ADR-0072）约束，SqlSugar 的 InitTables 与 EF Core 的 ApplyPersistenceConventions(Database) 都按它建；已有的库按此名字补建（表里有重复行时先去重）。
  • Locale 列长取 LocaleName.MaxLength（35），合法的区域名都能写入。SqlSugar 的 InitTables 与 EF Core 的 EnsureCreated 都不改已有列的长度，已有的表里这一列更窄时要手工放宽（如 PostgreSQL ALTER TABLE <翻译表> ALTER COLUMN <区域列> TYPE varchar(35);）或走一次迁移；SQLite 不校验长度。

依赖方向

依赖 XiHan.Framework.Localization.Abstractions 与 XiHan.Framework.Persistence.Abstractions。

状态

P3：可用，通过 Localization.Conformance。

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
5.0.0-preview.2 0 11/6/2026
5.0.0-preview.1 38 11/4/2026