89 lines
7.2 KiB
Markdown
89 lines
7.2 KiB
Markdown
# v0.26 通用国际化验收（2026-09-29）
|
||
|
||
交付范围：独立不可变词典、可选 HTTP/错误适配、CLI 检查/提取/导出、TypeScript 类型和独立浏览器运行时。普通消息、错误源文案、启用语言、用户偏好、资源提供方式均由项目维护；示例不依赖数据库或其他项目。
|
||
|
||
## 已通过的验证
|
||
|
||
环境：macOS / Apple M2 Max，Go 1.27.1，Node.js 22.15.1，TypeScript 5.6.3；最低版本另用 Go 1.22.12 核验。TypeScript 编译器通过 npm 临时缓存使用，没有添加项目 npm 依赖。
|
||
|
||
| 验证 | 结果 |
|
||
| --- | --- |
|
||
| `go test -race ./...` | 54 个有测试的包通过；未启用集成环境变量的生成消费者单独执行如下 |
|
||
| `go vet ./...`、`go build ./...`、`git diff --check` | 通过 |
|
||
| `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test ./cmd/go-omni/apigen -run 'TestI18nGeneratedConsumer\|TestErrorInheritance\|TestErrorParamsConsumer' -count=1 -v` | 3 组真实生成项目生成、重复生成、check 和消费者 race 测试通过 |
|
||
| Go 1.22.12：`go test ./i18n/... ./app ./errors ./response ./httpx ./config ./cmd/go-omni ./examples/i18n` | 全部通过 |
|
||
| Go 1.22.12：开启集成测试，`go test ./cmd/go-omni/apigen -run TestI18n -count=1 -v` | translation 元数据边界、真实生成消费者通过 |
|
||
| `node --test i18n/browser/runtime.test.mjs` | 4 组通过，包含覆盖、并发切换、最新失败/过期请求、坏包与读取上限 |
|
||
| `TestPinnedCLDRSamples` | 5,777 个上游普通基数规则样例端点通过；不把省略号和紧凑数字样例计入 |
|
||
| `TestBrowserConformance`、`TestSourceLocaleCanBeFallbackOnly` | Go 导出包在 Node 中执行，中文/英文/俄文/阿拉伯文/法文、精确 int64、小数、回退与源语言未启用通过；cmn 别名及私用标签不由浏览器改写 |
|
||
| `TestTypeScriptConsumer`（PATH 提供 tsc） | strict / ES2022 / NodeNext 编译通过；缺参、错类型、多余参数、未知键/命名空间必须产生编译诊断 |
|
||
| `go test ./i18n -run '^$' -fuzz FuzzDecodeJSON -fuzztime 10s` | 419,121 次执行通过 |
|
||
| 示例 CLI、词典 check、示例 HTTP 测试 | 通过；示例中英文输出及中文错误 HTTP 409 / code 400001 保持 |
|
||
|
||
最后的 TypeScript 类型修正后，重新执行了 `i18n/...`、CLI、示例 race 测试及对应 Go 1.22 验证。核心一致性及类型验证可复现为：
|
||
|
||
```sh
|
||
npm exec --yes --package typescript@5.6.3 -- go test ./i18n \
|
||
-run 'TestTypeScriptConsumer|TestPinnedCLDRSamples|TestBrowserConformance|TestSourceLocaleCanBeFallbackOnly' \
|
||
-count=1 -v
|
||
```
|
||
|
||
原始日志见 [i18nValidation.txt](i18nValidation.txt)。
|
||
|
||
## 兼容和隔离覆盖
|
||
|
||
- 多 Bundle、多 App、并发请求与多个命名空间不共享可变语言状态；构建输入与导出快照修改不影响实例。
|
||
- 项目目录和路由独立目录同名错误正确选取各自翻译；固定旧文案的字面花括号保留。
|
||
- 翻译仅进入展示层。HTTP 200 业务失败、HTTP 409/401/500、int64 业务码、嵌套响应模板、旧 Messages 校验、RawJSON 错误、认证提前返回、panic、缺参数和缓冲桥接均有回归。
|
||
- 参数值不重新解释为模板，内部 cause 不进入响应；Localizer 或偏好 Resolver panic 不把语言故障传播成新的业务执行结果。
|
||
- 自定义固定回执由原 Encoder 控制；直接 Text/JSON 等输出不自动改写。自定义 Encoder 可显式采用 PublicMessage。
|
||
- 本地/共享幂等重放保留首次响应，即使后续请求语言不同也只执行业务一次。
|
||
- 资源严格校验、循环回退、参数契约不一致、缺键诊断、显式覆盖、CLI 输入不被改写、旧 runtime 能力门槛均有测试。
|
||
|
||
## 浏览器实测
|
||
|
||
使用独立示例启动本机 `127.0.0.1:8098`，执行了：
|
||
|
||
1. 输入测试草稿，从英文切为中文：草稿保留，提交次数为 0。
|
||
2. 点击提交：次数变为 1。切回英文：草稿保留，次数仍为 1。
|
||
3. 停止示例服务后再选择中文：显示加载失败，仍停留在英文，草稿和一次提交保留。
|
||
|
||
示例服务和临时浏览器页面已关闭。乱序和快速重复选择由浏览器运行时自动测试验证。
|
||
|
||
## Go 1.22 发布前兼容性修复
|
||
|
||
初轮全仓 Go 1.22 验收暴露了两处旧问题，发布准备阶段已修复：
|
||
|
||
- 共享 Go 目录测试工程的 go.mod 从 1.24.0 调整为框架声明支持的 1.22.0，远程验收的同类测试工程同步调整。
|
||
- JSON 对象/数组结束定界符读取失败时保留底层错误，外层 MaxBytesReader 的限额错误继续被识别为 HTTP 413。新增对象、数组、嵌套结构的 reader cause 回归，原有 limit=0/1/4 测试保留。
|
||
|
||
最初发现问题的日志仍保留在 i18nValidation.txt 中，便于追溯；发布前的最终结果单独记录在 i18nReleaseValidation.txt 中。
|
||
|
||
## 发布前最终验收
|
||
|
||
- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./...`：54 个有测试的包通过，包含实际生成消费者；PATH 提供 TypeScript 5.6.3，跨端和类型测试实际执行。
|
||
- `GOTOOLCHAIN=go1.22.12 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test ./...`：全仓通过，先前两处失败已消除。
|
||
- `go vet ./...`、`go build ./...`、浏览器运行时测试、发布脚本语法检查、`git diff --check`：通过。
|
||
- `python3 scripts/verifyManagedProject.py --report reports/i18nManagedLocal.json`：真实生成项目运行、构建、重复生成、nethttp/native 信号退出、上传下载与故障清理通过；临时进程已清理。[机器记录](i18nManagedLocal.json)。
|
||
|
||
完整最终输出见 [i18nReleaseValidation.txt](i18nReleaseValidation.txt)。发布后从空 module 缓存安装固定标签的验收也已通过，见文末；远程报告独立提交，不移动发布标签。
|
||
|
||
## 性能与发布边界
|
||
|
||
`BenchmarkRender` 对俄文基数复数、22 参数的单条消息，当前机器一次测量为 3,753 ns/op、1,040 B/op、27 allocs/op；这只是开发机样本，不代表 SLA 或与旧实现的性能对比。
|
||
|
||
本次按 Go module 标签 `v0.26.0-preview` 发布；浏览器运行时随 module 分发，没有单独发布 npm 包。CLDR 46.1.0 数据随源码和导出包携带许可，启动不下载规则。v1 支持普通文本、命名参数、select 和基数复数；不是完整 ICU MessageFormat，不自动处理金额、日期、时区、RTL 布局或业务字段翻译。
|
||
|
||
## 已发布远程产物验收
|
||
|
||
`v0.26.0-preview` 标签固定在 `d1a747c36f15d964dd445d661623b68a45892adf`；远程 Go module 校验和为 `h1:9Ao/6+8jdqXf4Ia++rhgorTrYclAgrWgXw3U+AWtB4I=`。发布代码与标签已推送，验收记录独立提交，标签没有移动。
|
||
|
||
使用空 module 缓存安装已发布 CLI，10 组真实生成消费者、87 项发布检查通过，耗时 83.76 秒。CLI 与框架固定同版，所有消费者均确认无本地 replace。新检查覆盖下载模块中的独立 i18n、HTTP 错误不变量、源语言仅回退、CLDR 及 Go/浏览器一致性、TypeScript strict 消费者、四个 CLI 子命令和浏览器切换竞态/失败保留。详见 [i18nRemote.json](i18nRemote.json)。
|
||
|
||
复验命令（需要 Node.js，TypeScript 由 npm 临时缓存提供）：
|
||
|
||
```sh
|
||
npm exec --yes --package typescript@5.6.3 -- python3 scripts/verifyManagedRelease.py \
|
||
--version v0.26.0-preview --report reports/i18nRemote.json
|
||
```
|