三剪客 · 出海本地化小组

## ⚠️ 先申请你自己的 API Key
本 Skill 不内嵌任何密钥,也不代付费用。 请到
算力集市 api.a7w.cn 注册并创建你自己的 API Key
(新用户有赠送点数,可以先免费试跑一两条)。
拿到后填进环境变量 A7W_API_KEY,或直接传给 --key 参数。
请勿使用他人提供的 Key —— 用量与费用都记在 Key 所属账号上。

产品线 L3(多智能体协作型)。 与 L1「一稿多平台改写」的分界不是"多了个翻译步骤",
而是三件在单角色改写里结构上不存在的事:跨语言、术语一致、文化风险。

能做什么

给一份源语言材料 + 一个目标市场,四个立场不同的角色各自独立审一遍,
一条命令出成品:译文 + 术语表 + 四席裁决 + 互否全过程记录。

角色目标函数产出物否决权
译审意思准不准、有没有漏译错译译文 + 逐句回译对照能打回(意思错就得重译)
文化适配目标市场的文化能不能接受文化风险清单(禁忌/宗教/颜色/数字/幽默失效/政治敏感)能否决(踩红线必须改)
术语官术语全篇一致、与行业惯例一致术语表 + 不一致清单(全部出现位置)能打回(同词多译必须统一)
合规目标市场的广告法 / 平台规则风险裁决(放行 / 可替换 / 打回 / 一票否决)一票否决

零成本看这张表:

python3 scripts/run.py roles

为什么这不是"一个模型演四个角色"

常见做法本包
一个模型分四次扮演角色,共享同一份上下文四个角色各有字段白名单,看不到什么被写死成结构(ROLES[...]["inputs"])
译审知道文化适配觉得哪里有问题译审的提示词里没有文化适配的任何文字,也没有合规裁决
合规顺着前面几席的结论走合规的提示词里明写「本小组内部没有给出任何风险结论,你不得假设前道已经放行」
口头约定"互相独立"assert_isolation 在每次调用前做文本级扫描,提示词里出现别的席位的结论标记词就退出码 3,一分钱不花
"改了三轮,应该差不多了"轮次用尽仍有打回/否决 → 带未决项产出、退出码 6,逐条写明是哪一席在第几轮否了什么

打回是有向的(本包最关键的设计)

某一席打回时,下一轮重译的提示词里只带它自己的可执行要求(ask),
带的是"改成什么",不带"谁在什么立场上说了什么"、也不带它的理由:

第 1 轮:译审 ─┐  文化适配 ─┐  合规 ─┐   (四席各自独立调用,互相看不到)
               │            │        │
               └── 打回要求(去立场化)──┐
                                         ▼
第 2 轮:译审重译(提示词里只有"要求",没有提要求的席位与理由)

这样两件事同时成立:打回真的生效(要求必须落实,产出里要写 feedback_applied),
下一轮的译审仍然是独立判断(它不知道是谁提的,也就不会顺着别人的结论走)。

本包真正的技术含量:术语一致 + 数字单位

这两件事单角色翻译结构上做不到,也不是"提示词里写一句求模型配合"就能解决的:

术语一致性(本地算,不看模型自报):

  1. 按句子找术语表里每个源词在源文里的出现位置
  2. 用译文返回的逐句对齐(源句 ↔ 译句)定位每一处对应的目标句
  3. 逐处检查该目标句里有没有规范译法的变体
  4. 判定:有≥1处用了规范译法、又有≥1处没用 → 同词多译(硬闸门);

一处都没用但该词出现多次 → 术语表未落地(硬闸门)

归一化必须先做:Short Drama / short-drama / short dramas 在术语一致这件事上
是同一个译法,不归一就会把格式差异报成"同词多译",闸门立刻被刷爆、没人看了。

数字与单位保全:

源文目标市场期望值判什么
3 斤美国(英制)约 3.31 lb(=1.5 kg)数字还在吗?换算对吗?
5 平方米美国约 53.82 sq ft同上
25 摄氏度美国77 ℉同上
88 元美国要 --fx-rate 才换算不给汇率就不猜,只查数字在不在

判定口径(这里返工过一次,写清楚免得再想错):需要换算时,换算后的值在就等于
这个事实在(3 斤 → 3.31 lb 不该判"丢了 3");需要换算、原数字在、换算值不在
→ 这是没本地化 / 算错,不是丢数字。数字整条消失才是"丢了"。

七道硬闸门

硬闸门 = 命中即拦截 + 标红 + stderr 汇总 + 非 0 退出码。不许只警告。

#闸门判什么
1合规源语言侧 + 目标市场侧分开扫。源文(材料侧)全扫高/中/低;译文与各席裁决文书(产出侧)只查高风险,并排除"引用材料"与"警告语境"两类正常写法,被排除的全部留原因
2占位符残留{} / [待填] / XXX / (此处省略) / TODO
3照抄提示词示例三条判据(去标点相同 / 二元组 Jaccard ≥ 0.75 / 覆盖度 ≥ 0.60)+ 相对长度守卫 max(6, len(示例)//2)
4锚点到句子每条意见必须引用真实原文;本地校验引文能不能在原文里找到,编造的引文剔出;未锚定率 > 40% 判定位失败
5术语一致性(本包核心)同一源词全篇必须同一译法;不一致 → 标红 + 列出全部出现位置
6数字与单位保全(本包核心)数字/日期/货币/规格必须还在且单位正确换算;丢了或没本地化 → 拦
7裁决完整性打回/否决必须留可读理由;不许假装谈拢(四席有人否决而最终写"放行" → 拦;有未决项却出现"综合评估后放行" → 拦)

prompt_echo 的覆盖度判据必须加适用窗口(目标长度 ≤ 示例长度 × 3.0,
且示例归一后 ≥ 8 字):长文对短示例会饱和误报,覆盖度会虚假地冲到 1.0。

合规为什么分"材料侧"与"产出侧"

同族 review-board 踩过一次:合规官写「本稿禁止使用 guaranteed、best 这类绝对化用语」,
这是在要求删除,不是自己在做违规宣称 —— 而 guaranteed / best 都被当成命中拦下了。

所以产出侧收紧成三条能解释的规则:

  1. 只查高风险;中低风险项与 最X 列进 contextual_only 提示人工看,不拦
  2. 该词在源文/译文里本来就有 → 判为引用材料,不计命中
  3. 命中所在的整个小句里有禁止/举证/风险类标记词 → 判为提到/在禁止,不计命中

—— 但标记词必须落在命中词本身之外(否则「本方案必须保证过审」里的"保证"
会把自己豁免掉,闸门就没牙了)

被排除的条目全部保留在案(带 not_counted_reason),不静默丢弃。
材料侧(源文)照查,只豁免登记的普通用法(如「这笔账里最大的一块」)。

退出码(可直接用于 CI)

码含义
0四席全部放行,且没有硬闸门命中
1未预料异常(--json 下给 kind:"internal" 信封 + 完整 traceback 到 stderr)
2用法/配置错误(文件不存在、市场名错、--outdir 在包内、给了 --budget 没给单价、术语表与源文对不上)
3硬闸门命中(合规/占位符/照抄示例/锚点/术语不一致/数字单位/裁决不完整/信息隔离被破坏)
4调用失败(网络 / 鉴权 401 / 点数 402 / 模型名 404)
5预算超限,已就地中止(未发起下一次调用)
6轮次用尽仍有打回/否决(未决项如实报出,产出带未决项落盘)
130用户中断

怎么用(命令行)

第 0 步:获取 API Key

到 api.a7w.cn 注册,创建一个 API Key(形如 sk-...)。

第 1 步:装依赖

零依赖。 只要机器上有 Python 3.7+:

python3 --version

包里自带的 scripts/a7w.py 是零依赖客户端(只用 urllib / json / mimetypes),
scripts/run.py 也只用标准库。

第 2 步:填 Key

# Linux / macOS
export A7W_API_KEY=sk-你的key

# Windows PowerShell
$env:A7W_API_KEY="sk-你的key"

也可以存进配置文件反复用(推荐):

python3 scripts/a7w.py login --key sk-你的key

第 3 步:先做零成本自检(不联网、不花点数)

# 看四个角色的职权、隔离白名单、支持的市场与语言
python3 scripts/run.py roles

# 报价:这一趟大概花多少 token(金额要你自己填单价)
python3 scripts/run.py cost --file 源文.md --rounds 1 --price-in 1000 --price-out 2000

# 只看将发送的提示词,不调模型不花钱
python3 scripts/run.py translate --file 源文.md --target-lang en --market us --dry-run

第 4 步:一条命令出成品

python3 scripts/run.py run --file 源文.md \
    --target-lang en --market us --rounds 1 \
    --outdir /tmp/localize-out --json --out /tmp/localize-out/run.json

--outdir 里会落:final.md(定稿译文)、final.json、glossary.json / glossary.md、
translation.md(逐句回译对照)、REPORT.md(总报告:四席裁决 + 互否轨迹 +
隔离证据 + 两道特色闸门 + 未决项 + 成本)、log.json、localize-state.json(断点)。
同一个 --outdir 重跑,命中断点的步骤只会打印"跳过(零成本)"。

分子命令(每一席都能单独跑)

# 1) 抽术语表(源词 → 目标语规范译法)
python3 scripts/run.py glossary --file 源文.md --target-lang en --market us --outdir /tmp/lc

# 2) 译审出译文 + 逐句回译对照
python3 scripts/run.py translate --file 源文.md --target-lang en --market us \
    --glossary /tmp/lc/glossary.json --outdir /tmp/lc

# 3) 文化适配(能否决)
python3 scripts/run.py culture --file 源文.md --market us \
    --translation /tmp/lc/translation.json

# 4) 术语一致性核对(**纯本地,可零成本重跑**)
python3 scripts/run.py glossary_check --file 源文.md --market us \
    --translation /tmp/lc/translation.json --glossary /tmp/lc/glossary.json

# 4b) 对一份已有译文跑**全部本地闸门**(术语 + 数字单位 + 占位符 + 照抄示例 + 锚点)
#     改完译文反复跑的就是这个 —— 同样零成本
python3 scripts/run.py check --file 源文.md --market us \
    --translation /tmp/lc/translation.json --glossary /tmp/lc/glossary.json

# 5) 合规裁决(可否决 / 一票否决)
python3 scripts/run.py compliance --file 源文.md --market us \
    --translation /tmp/lc/translation.json

# 6) 读回全过程:谁在第几轮打回了什么、引用了哪句
python3 scripts/run.py log --outdir /tmp/lc

完整工作流(含预算控制)

# 1) 先算钱(不调模型)。没给单价就只报 token,不给金额
python3 scripts/run.py cost --file 源文.md --rounds 1

# 2) 给单价后算点数;配上 --budget 就是硬上限
python3 scripts/run.py cost --file 源文.md --rounds 1 --price-in 1000 --price-out 2000 --budget 40

# 3) 带预算跑。超了就地中止,退出码 5,不会把钱花出去
python3 scripts/run.py run --file 源文.md --target-lang en --market us \
    --price-in 1000 --price-out 2000 --budget 40 --outdir /tmp/lc --json

# 4) 用真实 token 数核算(不是估算)
python3 scripts/run.py cost --from-result /tmp/lc/run.json --price-in 1000 --price-out 2000

直接用 curl 调(不依赖本包脚本)

curl -sS -X POST "https://api.a7w.cn/api/v1/chat/completions" \
  -H "Authorization: Bearer $A7W_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "把下面这段翻成英文,只输出 JSON:……"}],
    "temperature": 0.7,
    "max_tokens": 1500,
    "response_format": {"type": "json_object"}
  }'

成功响应不带 code 字段。 实测成功时返回的就是标准 OpenAI 形态
(id / object / created / model / choices / usage),
"code" in payload 为 False。code==1 那套信封只用于生成应用的响应,
不适用于本端点 —— 别拿 code 判成败。

查在架模型(免费):

python3 scripts/run.py models

参数说明

全局

参数说明
--key临时指定 Key;优先级最高。别把它写进脚本或文档
--json以 JSON 输出,写在子命令前面或后面都可以;JSON 模式下 stdout 只有一个完整 JSON,进度与人读文案走 stderr
--out <文件>把结果写到文件
--model模型名,默认 deepseek-chat(实测可用)。用 models 现查在架模型
--temperature采样温度,默认 0.7
--max-tokens最大输出 token,默认 8192
--dry-run只打印将发送的提示词,不调模型、不花钱
--no-json-mode不要求上游返回 JSON 对象(个别模型不支持 response_format 时用)

源文与目标

参数说明
--file <文件> / --text "正文"源文。自动剥 UTF-8 BOM;两者同时给时以 --text 为准
--source-lang源语言代码,默认 zh
--target-lang目标语言代码,默认 en。可选:zh / zh-tw / en / ja / ko / es / pt / fr / de / ar / th / vi / id / ru
--market目标市场,默认 us。可选:us / eu / jp / sea / me / br。它同时决定文化适配的规则包与合规的法域,所以进断点 key —— 换市场而复用上一次的合规结论是这类工具最危险的静默复用
--glossary <文件>复用一份术语表。会核对源文摘要与目标语言,对不上直接拒绝(退出码 2)
--fx-rate人民币→目标货币汇率(外部输入)。不给就不换算货币,只查数字在不在

各子命令

子命令关键参数
roles零成本;--out 落盘
glossary抽术语表;--outdir 落 glossary.json / glossary.md
translate--target-multiple(译文目标长度 ≈ 源文 × 该系数,默认 1.0;英译中可给 1.6)
culture--translation(必填)
glossary_check--translation + --glossary;纯本地零成本,判定不看模型自报
check--translation(--glossary 可选);纯本地零成本,一次跑全部本地闸门(术语 + 数字单位 + 占位符 + 照抄示例 + 锚点 + 篇幅),改完译文反复跑的就是它
compliance--translation(必填)
run--rounds(默认 1,上限 5)、--target-multiple、--outdir(默认 %TEMP%/localize-out)、--force
log--outdir(必填)
cost--file / --text / --from-result、--rounds、--price-in / --price-out / --budget
models--type(默认 text,传 all 看全部)

成本口径

  • 只出 token,不编金额:文本模型网关不公布单价,/api/v1/models 里也没有价格字段,

chat/completions 的成功响应里 usage 只有 prompt_tokens / completion_tokens /
total_tokens,没有点数。所以拿不到可信的文本模型单价,本包拒绝凭空编一个 ——
token 数我们估(实测标定),金额必须由你给单价。

  • 字符 → token 标定(同族实测值,是估算不是账单):输入 1 token ≈ 1.61 字符;

输出 1 字符 ≈ 1.11 token。平台口径:1 元 = 100 点。

  • 真机实测(本包):187 字中文材料 → 英文(美国市场)、--rounds 1,

4 次调用共 6871 token(入 4925 / 出 1946),单席耗时 2.2~3.5 秒。

排错

现象原因怎么办
Missing or invalid relay API key(HTTP 401)Key 无效、过期或写错到 https://api.a7w.cn/ 重新领取;确认没把 Bearer 重复写进环境变量
点数不足(HTTP 402)账号点数用完到 https://api.a7w.cn/ 充值后重试
模型不存在(HTTP 404)模型名写错或已下架run.py models 现查在架模型名
译审返回里没有可用的译文外层 JSON 坏了 / 模型换了键名脚本已把原始返回存到 <outdir>/raw/,直接看它;报错信息里也会打出顶层键是哪几个与 finish_reason
!! 信息隔离被破坏某一席的提示词里出现了别的席位的结论标记词这是代码 bug(模板串了上下文),不是模型问题。报出来
术语表针对的不是这一版源文(退出码 2)拿别的源文的术语表来续跑这就是它该做的:拒绝静默复用。重新跑 glossary
术语一致性标红同一源词在不同位置用了不同译法看 glossary_check 输出的全部出现位置;改术语表或改译文后重跑(这个子命令零成本)
数字与单位标红「丢数字」译文里数字整条消失看报告里的上下文;真丢就重跑,或把数字写进 --glossary 之外的要求里
数字与单位标红「未本地化」原数字还在,但没按目标市场换算(3 斤 → 3 kg)提示词里已要求换算;模型没做就给 --market 明确的市场,或人工改
成本超过 --budget(退出码 5)预估或真实累计超了预算跑单席、调低 --max-tokens,或提高预算
退出码 6轮次用尽仍有席位打回/否决这是设计行为:分歧如实报出,没有假装谈拢。看 REPORT.md 的未决项,人工决定是改还是不发
unrecognized arguments: --out本包不允许长选项前缀缩写(故意的:--out 曾被静默吃成 --outdir)写全
Windows 下中文乱码控制台代码页不是 UTF-8chcp 65001,或加 PYTHONIOENCODING=utf-8
原稿第一个字是乱码UTF-8 BOM脚本已自动剥掉 BOM;若仍异常,另存为「UTF-8 无 BOM」

收集排错信息时请附上:完整命令、--dry-run 的输出、原始报错文本、退出码、
以及 <outdir>/raw/ 里的原始返回。不要在报错信息或截图里带上你的 API Key。

文件结构

sanjianke-localize-crew/
├── SKILL.md                          本文件
├── README.md                         给人看的说明(含 L3 定位与分界表)
├── LICENSE.md                        MIT,署名三剪客
├── references/
│   ├── 角色与职权.md                   四席的目标函数、产出物、否决权、隔离白名单
│   ├── 本地化与文化风险.md             术语一致判定、单位换算表、六个市场的文化红线
│   └── 成本与排错.md                   成本口径、退出码、断点 key、真机踩过的坑
└── scripts/
    ├── a7w.py                        api.a7w.cn 零依赖客户端(逐字节与全族一致)
    └── run.py                        十一个子命令(零第三方依赖)

端点速查

用途方法地址
大模型对话(本包全部能力都走这个)POSThttps://api.a7w.cn/api/v1/chat/completions
在架模型清单GEThttps://api.a7w.cn/api/v1/models

协议是 OpenAI 兼容:Authorization: Bearer <Key>,请求体用
model / messages / temperature / max_tokens / response_format。

--json 输出契约

  • 成功:结果对象里多一个 "ok": true;顶层是数组时包成 {"ok": true, "data": [...]}
  • 已经吐出结果之后才出问题(例如闸门命中):"ok": false 写在那个结果对象里,

退出码语义不变

  • 失败且本次还没吐过结果:stdout 输出一个 JSON 信封,形如

{"ok": false, "exit": 3, "error": {"kind": "gate", "message": "…"}},
kind 取 gate / usage / budget / call / unresolved / interrupt / internal

  • internal 是没预料到的异常(代码 bug)的兜底:stdout 给信封、

完整 traceback 原样打到 stderr、退出码固定 1 —— 报 bug,不藏 bug

  • --json 写在子命令前面或后面都可以

主动偏离(与同族模板不一致的地方)

偏离为什么
parse_first_json 先按括号配平切第一个完整的顶层值,再退回逐个 { 试真机踩到:外层 JSON 坏掉时,旧实现从 "pairs": [ 里的句子对象解出一个 dict 交出去,上层报"返回里没有译文",真因(外层 JSON 坏了)被"成功解出一个对象"盖住了 —— 报错指向了错误的方向,比坏响应本身更麻烦
记录并打出 finish_reason(进 REPORT.md 的成本表、进报错文案)它是区分"该加大 max-tokens"(length)与"模型写错了 / 响应在路上断了"(stop / None)的唯一判据。本包最初没记它,于是只能拿长度去凑解释 —— 那次错误归因就是这么来的
模型返回形状不对时把原始返回存到 <outdir>/raw/那次调用已经花钱了,不存下来等于白花;而且只有原始返回 + finish_reason 能区分"max_tokens 截断 / 模型语法错 / 传输被切断 / 键名不同 / 空返回"
合规产出侧加一条标记词不许落在命中词自己身上「本方案必须保证过审」被判成"在禁止承诺"而放过 —— 因为 保证 既是命中词又是标记词。这正是闸门失去牙的那种误报
_ctx_window 从固定 24 字改成整个小句(不跨句末标点)24 字对「本稿禁止使用 guaranteed 这类绝对化用语」不够(命中词与标记词隔了 8 个字左右,长一点就超出),会把"在禁止"误判成"在主张"
各席输出强制写短(最多 6 条、每条 ≤30 字)输出越长,越容易撞上 max_tokens(finish_reason=length),也越容易碰上坏 JSON。上限不是越大越好
back_translation 只要求含数字/单位/术语的句子填全篇回译会让响应变长(更容易撞上限或出坏 JSON);而它的用途(核对漏译与数字)本来就只需要那几句
glossary_check / check 是纯本地子命令,不花钱术语判定与数字单位判定本来就该是确定性的:靠模型自报"我觉得不一致"不可复现,也没法零成本重跑

没能确认的事(诚实标注)

① max_tokens 截断已确证(实测 finish_reason=length,content 停在字符串中间);
② 模型语法错已由外部对照实测确认(finish_reason=stop,content 有正常收尾、坏在中间);
③ 传输被切断只是推断 —— 本包留下过两份"内容没写完"的原始返回
(EOF 处 depth=1, in_str=True,长度 2739 / 2781),但当时没有记录 finish_reason,
所以分不清它是 ② 的另一面还是 ③。现在 finish_reason 已进台账,下次能判。

⚠️ 本轮撤回的一个错误归因:我曾写过"网关在 2600~2900 字符处有固定上限",
并把它当实测写进文档。那是错的 —— 同一端点实测能拿到 3984 字符的完整内容
(finish_reason='stop',以 }]} 正常收尾),而本包自己失败的那几次长度各不相同
(1921~2781),根本没有固定长度这条线。那个说法来自"只看到解析失败就去猜长度",
已从全部文档与代码注释里撤掉。

  • 货币换算只做了"数字还在不在"这一层:不给 --fx-rate 就不换算(不猜汇率)。

给了汇率也只对 us / eu / jp 三个市场做 CNY 换算,其余组合仍只查数字。

  • 术语一致性的"合理意译"识别有限:只出现一次且译法不同的判为提示、不拦;

同一源词在 3 处以上出现两种译法才会稳定判为不一致。更细的语义等价判断没做。

  • 文化风险清单的本地闸门只覆盖可枚举项(宗教/政治/颜色/数字/禁售品类)。

"幽默失效"这类只能靠那一席的模型判断,本地没有兜底。

  • 违禁词表与六个市场的规则都是启发式自检,来自公开经验整理,

不构成法律意见,也不等于任何平台的官方审核标准。医疗、保健食品、金融、
儿童、化妆品等高风险类目必须人工复核。

联系我们

  • 技术微信:9872659 —— 加好友时说一下是从哪个 Skill 找过来的,直接给你配套的 API Key 与能跑的示例。
  • 要算力 / 要 API Key:算力集市 · 注册领 API Key —— 一个 Key 调用全部 AI 算力,注册、充值、创建 Key 都在这里。
  • 更多 AI 插件与接口:AI 插件市场。

相关链接

  • 算力集市 api.a7w.cn(注册领 Key):https://api.a7w.cn/
  • 四席的职权与隔离白名单:references/角色与职权.md
  • 术语判定、单位换算表、六个市场的文化红线:references/本地化与文化风险.md
  • 成本口径、退出码、断点 key、真机踩过的坑:references/成本与排错.md

免责声明:本包内置的违禁词表、市场规则与文化风险口径是启发式自检工具,
来自公开经验整理,不构成法律意见,也不代表任何平台的官方审核标准
(官方标准不公开、且会变)。内容的使用与合规责任由使用者承担;
医疗、保健食品、金融、母婴、特殊化妆品等高风险类目必须人工复核。

同类文章