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 升上来,有几处不是换个版本号就能过的坎。
三个硬断点
- 数据必须重新生成:内部数据存储换成了 zerovec 的更高效二进制表示,1.5 用 postcard 生成的数据在 2.0 读不了。
- 三个 crate 永久停在 1.5:
icu_locid、icu_locid_transform重组为icu_locale+icu_locale_core;icu_timezone由新 crateicu_time接替,icu_calendar只保留历法计算。 - 数据生成入口换了:
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.5 | 2.0 |
|---|---|
icu_locid、icu_locid_transform | icu_locale、icu_locale_core |
icu_timezone | icu_time |
icu_datagen | icu_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)