Overseas Tool

小游戏出海本地化命令行工具。一条命令完成游戏项目的文本与图片扫描、翻译、应用与验证。

简介

Overseas Tool 面向小游戏开发者，自动化完成游戏项目的国际化（i18n）翻译，处理流程如下：

扫描（文本 + 图片） -> 计划 -> 翻译 -> 应用替换 -> 验证

主要特性：

• 一键全自动：从扫描到落盘只需一条命令
• 图文一体：同时处理代码中的文本与图片资源
• 断点续跑：每个阶段产物落盘，失败后可从断点恢复
• 安全替换：基于语法树识别字符串边界，失败自动回滚
• 可视化报告：内置 Markdown / HTML 报告生成

系统要求

| 依赖 | 版本要求 | | --- | --- | | Node.js | >= 18.18.0 | | 操作系统 | macOS / Linux / Windows |

安装

全局安装：

npm install -g @weadmin/overseas-tool

验证安装：

overseas --version

安装成功后，系统会注册全局命令 overseas，可在任意目录下使用。

获取凭据

使用前需要从微信公众平台获取一对 APPID 与 Token：

1. 登录微信公众平台：https://mp.weixin.qq.com/
2. 依次进入：游戏能力地图 -> 特色能力 -> 出海服务 -> 研发工具箱 -> 一键翻译
3. 在工具使用步骤区域复制 APPID 与 Token

安全提示：Token 具有时效性，且与你的小游戏账号强关联，请勿将其上传到代码仓库或公开页面。

快速开始

1. 登录

overseas login

按提示输入上一步获取的 APPID 与 Token。凭据会被加密保存到本机。

2. 环境自检

overseas doctor

该命令会检查运行环境与凭据是否就绪，全部通过即可开始使用。

3. 运行本地化流水线

在游戏项目根目录运行：

overseas run

或使用绝对路径指定项目：

overseas run --project /absolute/path/to/your/game

CLI 会以交互方式引导完成扫描、计划、翻译、应用与验证，并在关键节点请求确认。

CI 或自动化场景建议：

overseas run --project /absolute/path/to/your/game --yes --no-markdown --no-ink

命令参考

overseas run

启动本地化流水线。

overseas run [options]

| 选项 | 说明 | | --- | --- | | -p, --project <path> | 目标项目绝对路径，跳过交互式询问 | | -y, --yes | 跳过启动前的二次确认（CI 模式） | | --fast | 快速模式：自动通过阶段确认并连续执行到验证阶段 | | --run-mode <mode> | 显式指定运行模式：full / incremental / resume | | --lang-concurrency <n> | 翻译阶段同时处理的目标语言数 | | --concurrency <n> | 翻译阶段 AI 请求总并发上限 | | --enable-poison-ddmin | 模型稳定拒绝后允许用有界 ddmin 定位最小失败集合（默认关闭） | | --no-markdown | 关闭 Markdown 渲染，输出纯文本（便于 CI / 重定向） |

overseas login / logout

overseas login     # 登录（已登录则显示当前账号，不重复弹窗）
overseas logout    # 登出并清理本地凭据

overseas doctor

环境自检：检查 Node 版本、配置、凭据、运行组件与本地化服务连通性。失败时以非零退出码结束，可直接接入 CI。

overseas doctor

overseas status

读取项目 i18n/ 目录下的产物，打印各阶段进度。仅读取本地文件，不连接服务，适合排查长流水线断点。

overseas status /absolute/path/to/your/game

overseas report

把替换与验证产物渲染为 Markdown 或 HTML 报告。

overseas report /absolute/path/to/your/game [options]

| 选项 | 说明 | 默认 | | --- | --- | --- | | -f, --format <fmt> | 输出格式：md 或 html | md | | -o, --out <file> | 输出文件路径 | <project>/i18n/report.{md,html} | | --diff | 附加替换前后的 unified diff | false | | --lang <lang> | 只生成指定语言的报告 | 全部语言 |

overseas ignore init

在项目根目录初始化 .overseasignore 忽略规则文件，用于排除不需要扫描或翻译的文件。

overseas ignore init [-p, --project <path>]

overseas apply / verify（进阶）

当项目 i18n/ 目录已有产物时，可跳过编排器单独执行替换或验证：

overseas apply /absolute/path/to/your/game [options]   # 执行替换 / 语言包写入
overseas verify /absolute/path/to/your/game [options]  # 执行验证

apply 常用选项：

| 选项 | 说明 | | --- | --- | | --lang <lang> | 只对单语言执行；不传则按配置全量执行 | | --strategy <s> | replace 或 langpack | | --key-mode <m> | langpack 模式下 key 取值方式：hash 或 cn | | --apply-images | 同时回写图片 | | --mode <m> | full 或 incremental |

verify 常用选项：

| 选项 | 说明 | | --- | --- | | --strict | 验证结果不为 pass 时以退出码 1 结束（CI 友好） |

全局选项

| 选项 | 说明 | | --- | --- | | --no-ink | 关闭终端交互式渲染（spinner / Markdown 退化为纯文本） | | -V, --version | 显示版本号 | | -h, --help | 显示帮助 |

输出产物

执行完整流水线后，工具会在项目目录下生成 i18n/ 子目录，包含各阶段产物：

<your-game>/
├─ i18n/
│  ├─ 00-config/            # 流水线配置
│  ├─ 01-scan/              # 扫描结果（文本 + 图片）
│  ├─ 02-plan/              # 翻译计划与术语模板
│  ├─ 03-glossary/          # 各语言术语表
│  ├─ 04-translation/       # 翻译结果与翻译后的图片
│  ├─ 05-replace/           # 替换报告、语言包与源文件备份
│  ├─ 06-verify/            # 验证报告
│  ├─ tm/                   # 翻译记忆库（跨次复用）
│  └─ report.md             # （可选）导出的可读报告
└─ ...                      # 你的游戏源文件

流水线中途中断时，已落盘的产物依然有效，下次运行会自动从断点继续。

常见问题

Token 过期怎么办

Token 由微信公众平台签发，具有较短有效期。过期后重新到平台获取新的 Token，然后依次执行：

overseas logout
overseas login

如何切换小游戏账号

overseas logout
overseas login

能否在 CI 流水线中运行

可以，建议使用：

overseas run --project /absolute/path --yes --no-markdown --no-ink

CLI 会自动检测非交互式环境并降级为纯文本输出。

流水线中途失败怎么办

1. 执行 overseas status <project> 查看进度并定位失败阶段
2. 查看日志目录 ~/.overseas-tool/logs/ 获取详细信息
3. 修复问题后重新执行 overseas run，会自动从断点继续
4. 如需放弃当前进度，删除 <project>/i18n/ 后重新开始

替换出错如何恢复源文件

每次替换前都会在 i18n/05-replace/backup/ 下保留原始备份。工具会自动检测失败并整文件回滚；也可手动将备份文件覆盖回原位置。

许可证

UNLICENSED