Skip to content

Latest commit

 

History

History
115 lines (74 loc) · 6.86 KB

localization_cn.md

File metadata and controls

115 lines (74 loc) · 6.86 KB

插件译文构建与维护

English | 简体中文

以下命令在独立的 OpenTest-Plugins 仓库执行。每个插件维护自己的英文源和目标语言 JSON,前端和 Java 后端共用这些资源。插件构建入口默认在编译前从 Crowdin(译文管理服务)下载所选插件的译文,完成名称键、参数和语言映射校验后应用,再继续检查、编译和组包。云端尚未翻译的条目保留本地有效译文和默认语言回退。

构建时下载

# 默认下载,再执行原有完整构建
pnpm build fft-tools
pnpm build:signed fft-tools --platform windows
# 使用与宿主后端相同的参数跳过下载
pnpm build fft-tools "-Dskip.crowdin.download=true"
# 显式启用,与默认行为一致
pnpm build fft-tools "-Dskip.crowdin.download=false"
# 仅同步所选插件,校验后应用,不编译也不上传
node tools/crowdin.mjs sync fft-tools

PowerShell 中需将带点的 -D 参数整体加引号。

插件单侧构建也默认同步;只重新组包的 package / package:signed 沿用已有资源,不重新下载。宿主默认独立构建和打包,显式 --plugins-dir 只接收已有插件包,不触发此下载流程。独立插件构建使用自己的跳过参数;宿主打包中的 MAVEN_ARGS 只影响该流程实际执行的后端构建。

需自行安装 Crowdin CLI,并在环境变量或 Git 忽略的 .local/crowdin.env 中配置 CROWDIN_PROJECT_ID、CROWDIN_API_TOKEN。环境变量优先;工具不会安装软件或上传源文案。下载、鉴权、网络或译文校验失败会停止编译;远端未提供的插件/语言会报告缺译并保留本地资源。未配置凭据的离线构建应明确使用跳过参数。

构建下载复用下面的快照与导入逻辑,只准备本次选择的插件,不覆盖英文源或其他插件。快照和报告位于 .runtime/crowdin/,下载后产生的语言资源差异应按正常流程审查。

译文变化也属于插件内容变化,正式发布仍须遵守插件版本递增规则。下载和构建不会自动调整 plugin.json 的版本。

准备单个插件

从插件仓库根目录执行:

pnpm crowdin:check -- --plugin fft-tools
pnpm crowdin:prepare -- --plugin fft-tools

需要准备全部插件时,将 --plugin fft-tools 换成 --all。输出包含快照文件、源文案副本、Crowdin 配置和缺译报告。默认保存到 Git 忽略的 .runtime/crowdin/。也可用 --output <尚不存在的目录> 指定输出。

Crowdin 源文件映射固定为 plugins/<插件目录名>.json,用插件名区分文件。源副本来自该插件现有默认语言资源,本地语言文件仍使用 en-US.json 等语言名。生成的配置只包含选定插件的语言资源,不包含宿主、独立云服务的语言资源或许可文本。源文案和插件清单摘要保存在快照中,后续同步若发现它们变化,会要求重新准备。

以 FFT 为例,上传、下载与导入的对应关系如下:

用途 路径
本地英文源 plugins/fft-tools/frontend/locales/en-US.json
准备目录中的源副本 sources/plugins/fft-tools/en-US.json
Crowdin 文件 plugins/fft-tools.json
下载暂存(相对于命令输出的 translations 目录) fft-tools/zh-CN.json
校验后导入 plugins/fft-tools/frontend/locales/zh-CN.json

旧的远端 plugins/<插件目录名>/en-US.json 应移动并重命名为上述路径,保留原文件 ID;不要删除后重传。移动后只删除已经确认为空的旧插件目录。之后重新 prepare,并使用新配置上传或下载,避免直接运行旧准备目录中的 crowdin.yml。

上传源文案

安装 Crowdin CLI,在终端或 .local/crowdin.env 中设置 CROWDIN_PROJECT_ID 和 CROWDIN_API_TOKEN,然后使用 prepare 输出的快照路径:

pnpm crowdin:upload -- --snapshot <准备目录>/snapshot.json

命令只上传源文案,不翻译、不自动批准译文。源文案更改后保留已有译文,相关译文需要重新人工确认。配置中的环境变量字段、远端路径和语言映射遵循 Crowdin 配置说明。真实凭据不要写入配置产物或提交。

也可以在 Crowdin 网页手动创建对应插件目录并上传准备目录中的源 JSON。宿主继续使用原来的 client-en.js 和 messages.properties,本工具不会更新它们。

下载并核对译文

云端翻译完成后执行:

pnpm crowdin:download -- --snapshot <准备目录>/snapshot.json

这个手动下载命令写入新的暂存目录,检查名称键、参数和语言映射,并输出差异与缺译报告,不直接改写插件资源。构建入口的 sync 则在同样校验通过后自动应用。需要本地构建时,可以用 -Dskip.crowdin.download=true 跳过下载。

云端尚无可导出的译文时,下载结果会将对应插件列入 skipped,保留本地已有语言文件。

确认差异后,使用下载命令输出的 translations 目录:

pnpm crowdin:import -- --snapshot <准备目录>/snapshot.json --from <translations目录>
pnpm crowdin:import -- --snapshot <准备目录>/snapshot.json --from <translations目录> --apply

第一条只检查。第二条在全部输入校验通过后应用。空译文和未下载的条目不会清除本地已有译文;未下载的语言保持原样。下载内容不能覆盖英文源、加入未知名称或修改未选中的插件。准备后发生的本地译文修改也会阻止覆盖。应用后审查 Git 差异,并按正常流程提交。

从网页下载的文件导入

网页导出时选择跳过未翻译条目,避免将英文回填当作已完成译文。将下载 ZIP 在工具外解压,整理成下列结构后使用同一 import 命令:

translations/
  fft-tools/
    zh-CN.json
    ja-JP.json

语言文件名必须对应插件清单声明的 locale。工具拒绝未知语言和符号链接。未选中的插件目录不参与导入。不要从 ZIP 直接覆盖工作树。

首次复用旧译文

复用已有译文时,先按插件的实际名称键转换文件。相同英文或相同前缀不能代替明确的归属映射。转换后使用 import 检查各语言文件,再在 Crowdin 对应插件源文件中手动导入这些译文,并重新确认其含义与参数。

消息参数类型只在插件清单的稀疏 parameters 声明中维护,不上传翻译。默认语言资源决定合法名称集合,不再维护消息索引。

验证工具

node --test tools/test/crowdin.test.mjs

测试使用本地快照和模拟下载文件,验证选择范围、缺译报告、预览与应用、过期输入拒绝及参数校验。它不连接 Crowdin,也不代表远端导入已经完成。