feat: 更新 Crowdin 工作流以支持 dashboard WebUI 的本地化文件,添加相关验证逻辑
This commit is contained in:
35
docs/i18n.md
35
docs/i18n.md
@@ -37,6 +37,22 @@ prompts/
|
||||
- 不要把 `zh-CN` 原文整批复制到 `prompts/en-US/` 后直接提交。
|
||||
- 目标语言 prompt 文件应该由 Crowdin 下载生成;在本地还没有目标文件时,运行时会自动回退到 `zh-CN`。
|
||||
|
||||
Dashboard WebUI 的 locale 文件位于 `dashboard/src/i18n/locales/*.json`:
|
||||
|
||||
```text
|
||||
dashboard/src/i18n/locales/
|
||||
zh.json
|
||||
en.json
|
||||
ja.json
|
||||
ko.json
|
||||
```
|
||||
|
||||
注意:
|
||||
|
||||
- `dashboard/src/i18n/locales/zh.json` 是 dashboard 在 Git 中的 source of truth。
|
||||
- dashboard 运行时继续使用 `zh` / `en` / `ja` / `ko` 这组短 locale code,但 Crowdin 侧仍把 `zh.json` 当作仓库里的 `zh-CN` source 资产来同步。
|
||||
- `en.json` / `ja.json` / `ko.json` 是同步产物和可评审输出,不是常规长期手工编辑面。
|
||||
|
||||
## 在代码中使用
|
||||
|
||||
统一从 [`src/common/i18n/__init__.py`](../src/common/i18n/__init__.py) 导入:
|
||||
@@ -88,7 +104,7 @@ Prompt 加载规则:
|
||||
|
||||
## 日常翻译流程
|
||||
|
||||
1. 先在 `locales/zh-CN/*.json` 或 `prompts/zh-CN/**/*.prompt` 添加或修改 source 内容。
|
||||
1. 先在 `locales/zh-CN/*.json`、`prompts/zh-CN/**/*.prompt` 或 `dashboard/src/i18n/locales/zh.json` 添加或修改 source 内容。
|
||||
2. 在代码中用 `t()` / `tn()` / `load_prompt()` 替换硬编码字符串。
|
||||
3. 运行 `python scripts/i18n_validate.py` 校验结构。
|
||||
4. 把 source 变更推送到 `main` 或 `r-dev`,或手动触发 [`crowdin-sync.yml`](../.github/workflows/crowdin-sync.yml)。
|
||||
@@ -100,6 +116,7 @@ Prompt 加载规则:
|
||||
- 下面这两条是本仓库的 repository-specific 校验策略,不是 Crowdin 默认行为。
|
||||
- 不要手工把中文 source 文案直接复制进目标语言文件后提交。
|
||||
- 英文 locale 文件中不应保留中文字符;这类残留会被校验脚本拦截。
|
||||
- `dashboard/src/i18n/locales/en.json` / `ja.json` / `ko.json` 也遵循同样规则。
|
||||
|
||||
### 什么时候可以直接改目标语言文件
|
||||
|
||||
@@ -124,7 +141,9 @@ python scripts/i18n_validate.py
|
||||
- 是否存在重复 key
|
||||
- 是否存在空字符串 key
|
||||
- 各语言 key 集合是否与 `zh-CN` 对齐
|
||||
- dashboard 嵌套 JSON 的 key 集合是否与 `dashboard/src/i18n/locales/zh.json` 对齐
|
||||
- 占位符集合是否一致
|
||||
- dashboard i18next `{{placeholder}}` 占位符集合是否一致
|
||||
- plural 结构是否一致
|
||||
- 非 `zh-CN` locale 是否直接保留了包含中文字符的 source 文案
|
||||
- prompt 模板已存在时,其占位符集合必须与 `prompts/zh-CN/` 对齐
|
||||
@@ -146,12 +165,20 @@ python scripts/i18n_extract_candidates.py
|
||||
|
||||
## Crowdin
|
||||
|
||||
项目根目录的 [`crowdin.yml`](../crowdin.yml) 使用 `locales/zh-CN/*.json` 作为 source。
|
||||
现在也会把 `prompts/zh-CN/**/*.prompt` 作为单文件 Prompt 模板 source 上传到 Crowdin。
|
||||
项目根目录的 [`crowdin.yml`](../crowdin.yml) 现在会上传三类 source:
|
||||
|
||||
- `locales/zh-CN/*.json`
|
||||
- `prompts/zh-CN/**/*.prompt`
|
||||
- `dashboard/src/i18n/locales/zh.json`
|
||||
|
||||
对于 dashboard:
|
||||
|
||||
- Crowdin 下载结果会回写到 `dashboard/src/i18n/locales/en.json`、`ja.json`、`ko.json`
|
||||
- 其中英文文件名保持为 `en.json`,但在 Crowdin 配置里仍映射到 `en-US`
|
||||
|
||||
GitHub Actions 中的 [`crowdin-sync.yml`](../.github/workflows/crowdin-sync.yml) 是日常稳态同步入口:
|
||||
|
||||
- push 到 `main` / `r-dev` 时,只有 `zh-CN` source 资产和 `crowdin.yml` 会触发正常上传。
|
||||
- push 到 `main` / `r-dev` 时,只有 source 资产(包括 dashboard 的 `zh.json` source 文件)和 `crowdin.yml` 会触发正常上传。
|
||||
- workflow 运行时会上传 source,并下载当时 Crowdin 中可用的翻译结果。
|
||||
- 下载结果通过 `l10n_*` pull request 回流,而不是直接写回 `main` / `r-dev`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user