编程 ICU4X 1.5 升 2.0:postcard 数据作废,icu_locid 与 icu_timezone 停在 1.5

2026-11-20 00:05:37

ICU4X 1.5 升 2.0:postcard 数据作废,icu_locid 与 icu_timezone 停在 1.5

ICU4X 是 Unicode 的 Rust i18n 实现,带 C++/JS/TS 接口,二进制体积与内存占用比 ICU4C 小 50–90%。2.0 于 2025 年 5 月发布(GitHub release 2025-05-07,tag icu@2.0.0)。从 1.5 升上来,有几处不是换个版本号就能过的坎。

三个硬断点

  1. 数据必须重新生成:内部数据存储换成了 zerovec 的更高效二进制表示,1.5 用 postcard 生成的数据在 2.0 读不了。
  2. 三个 crate 永久停在 1.5:icu_locid、icu_locid_transform 重组为 icu_locale + icu_locale_core;icu_timezone 由新 crate icu_time 接替,icu_calendar 只保留历法计算。
  3. 数据生成入口换了:icu_datagen 拆成多个子 crate,直接依赖它的项目要改到 icu_provider_source / icu_provider_export / icu4x-datagen 二进制 crate。

数据面

postcard 不兼容是存储格式变更的直接后果。2.0-beta1 里 icu_provider_blob 移除 Blob schema v1、v2,新增 v3(#5608);同时移除 AnyProvider(#6086),BufferProvider trait 换成 DynamicDataProvider(#4992),data key 改称 data marker(#5003)。旧 blob 文件不是"读出来有偏差",是根本没有可用的 schema 版本。

datagen 的拆分范围比想象中散:icu_provider_export(#5172)、icu4x-datagen(#5011)、icu_provider_registry(#5010/#5177)、icu_provider_source(#5016/#5173),icu_provider_baked 从 icu_datagen 拆出(#5009),icu_testdata 直接删除(#4960)。改法是把 icu_datagen 的依赖按用途分别换成 source / export 侧,生成动作交给 icu4x-datagen 命令行。

cargo install icu4x-datagen

# baked:产出 Rust 源码形式的数据
icu4x-datagen --markers all --locales ja --format baked --pretty --out my_data

# blob:产出 postcard 文件
icu4x-datagen --markers all --locales ja --format blob --out my_data_blob.postcard

baked 数据可以在编译期用环境变量替换:

ICU4X_DATA_DIR=$(pwd)/my_data cargo run

体积上,全量 blob 约 5MB。按二进制实际用到的 marker 裁剪:

cargo build --release && \
icu4x-datagen --markers-for-bin target/release/myapp --locales ja \
--format blob --out my_data_blob.postcard --overwrite

5MB 降到 19KB。但裁剪结果里仍带着 DatetimeNamesMonthPersianV1 这类无关 marker,因为 DateTimeFormatter 支持多历法。换成 FixedCalendarDateTimeFormatter 后再跑一次,得到 8KB、只含 7 个 marker 的 blob,其中 5KB 是 locale fallback 数据,与 datetime 无关。

fallback 由谁负责

BakedDataProvider 内置 fallback。BlobDataProvider 与 FsDataProvider 不做 locale fallback:只有 en 数据时请求 en-US 会失败,需要自己包一层 LocaleFallbackProvider。baked 数据可以用 Options::skip_internal_fallback 关掉内置 fallback。

缺数据时的表现也不同:baked 缺 marker 是编译错误,blob 缺 marker 是运行时错误。

2.0.1 修了一个和这里直接相关的 bug:单 locale 数据生成会跳过 fallback(icu_provider_baked,#6582)。用 2.0.0 生成过单 locale baked 数据的,升到 2.0.1 后需要重新生成。

crate 冻结与替代

1.52.0
icu_locid、icu_locid_transformicu_locale、icu_locale_core
icu_timezoneicu_time
icu_datagenicu_provider_source / icu_provider_export / icu4x-datagen
# 1.5
icu_locid = "1.5"
icu_locid_transform = "1.5"
icu_timezone = "1.5"
icu_datagen = "1.5"

# 2.0
icu_locale = "2.0"
icu_locale_core = "2.0"
icu_time = "2.0"
icu_provider_source = "2.0"
icu_provider_export = "2.0"
# 数据生成本身改用 icu4x-datagen 二进制(cargo install icu4x-datagen)

重命名同样会撞到编译错误:Language / LanguageIdentifier / Locale 去掉 Default 实现(#6529),is_default() 改名 is_unknown()(#6507),icu_locale 移除 HourCycle::H24(#6426),日历 Islamic → Hijri 等一批改名,data marker 大量改名。所有 crate 已更新到 CLDR 47 与 Unicode 16。

API 面

locale 相关 API 大部分改为接收类型安全的 preferences 对象(preference bag),可以从 locale 得到,也可以手写 enum 组合。preference bag 按值传入,多数调用点要从 &locale.into() 改成 locale.into() 或 (&locale).into()。

很多 Rust 类型现在有 owned / borrowed 两套,例如 Collator 与 CollatorBorrowed;borrowed 更省,可以从编译期数据静态创建,也可从 owned 派生。

formatter 的输入类型改为从 formatter crate 重新导出,显式写在 Cargo.toml 里的依赖可以少一些。DateTime 组件完全重写,官方建议按新 API 从头写,而不是逐个替换调用点。

FFI 大改:C/C++ 侧用命名空间(icu4x::DateTimeFormatter),类型以 std::unique_ptr 返回,ABI 与头文件对 non_exhaustive struct 做版本化;JS 侧 enum 从字符串改成 class,构造时仍可传字符串,struct 可以用普通对象,ICU4X 发布为 NPM 包 icu。

MSRV 是 Rust 1.82(#6413)。

2.1 里还有几处值得一并安排:icu_provider_baked 默认改用 Index32(#7310,属 breaking,MaybeEncodeAsVarULE 增加关联类型),baked data 暴露 const struct(#6652);icu4x-datagen 增加 --attribute-filter(#7236),不再要求必须设置 sources(#6892);datagen 数据更新到 TZDB 2025c(#7306)。

升级检查清单

  • 工具链升到 Rust 1.82+
  • 丢弃全部 1.5 生成的 postcard 数据,重新生成
  • 确认 blob 使用的是 schema v3
  • icu_locid / icu_locid_transform / icu_timezone 依赖改到 icu_locale / icu_locale_core / icu_time
  • 直接依赖 icu_datagen 的改为 icu_provider_source / icu_provider_export,生成用 icu4x-datagen
  • preferences 调用点去掉多余引用:&locale.into() → locale.into() 或 (&locale).into()
  • is_default() 改 is_unknown(),处理去掉 Default 实现的类型
  • 日历名(Islamic → Hijri 等)、data marker 改名同步
  • 检查 HourCycle::H24 的使用点
  • BlobDataProvider / FsDataProvider 外面补 LocaleFallbackProvider
  • 用 2.0.0 生成过单 locale baked 数据的,升 2.0.1 后重新生成
  • DateTime 调用点按新 API 重写
  • C/C++/JS 侧按新 FFI 形态调整

与站内 ICU4C / ICU4J 的边界

ICU4X 和 ICU4C 不共用数据文件。ICU4C 读 .dat / icudt,ICU4X 用的是 datagen 产出的 baked Rust 代码或 postcard blob,两条数据链路互不相通。它们可以在同一台 CI 机器上共存,符号与 SONAME 互不影响。

站内已有文章覆盖的是另外两条栈:#8649 讲 ICU4C 的符号后缀 _79、pkg-config、U_MISSING_RESOURCE_ERROR 与 u_setDataDirectory;#8612 讲 ICU4J 的 LocaleServiceProvider / SPI 兜底;#8099 是 ICU 79 升级;#8277 记录 MF2 各实现的版本差异。

项目信息

  • GitHub:
  • 文档站点:icu4x.unicode.org,提供 2.0 / 2.1 / 2.2 / 2.3 / 2.4 各版本教程
  • crates.io 与 docs.rs 上有对应的 Rust 包
  • 2.0 发布信息见 GitHub release(tag icu@2.0.0)
复制全文 生成海报 ICU4X ICU Rust i18n 国际化 CLDR 升级迁移

推荐文章

程序员茄子在线接单