翻译应用的字符串文件与翻译文章是两回事。每个值都很短,往往没有上下文,还带着模型绝不能碰的语法:占位符、HTML 标签和复数规则。阿拉伯语让最后一项变得困难:英语文件只有两种复数形式,阿拉伯语却需要六种。本文基于 OpenAI 兼容的大模型搭建一条小流水线:冻结占位符,要求六个纯文本复数字符串,用代码拼装 ICU 语法,然后在 CI 中全面校验。
翻译文档、工单和合同,参见用大模型做阿拉伯语与英语互译,那篇文章讲的是文章类文本的语气、术语表和评估。
为什么阿拉伯语复数会搞坏机器翻译的字符串文件?
Intl.PluralRules、ICU 和 i18next 都遵循 Unicode CLDR,而 CLDR 为阿拉伯语定义了六个基数类别:
| 类别 | CLDR 规则 | 示例数字 | 示例:“文件” |
|---|---|---|---|
| zero | n = 0 | 0 | لا توجد ملفات |
| one | n = 1 | 1 | ملف واحد |
| two | n = 2 | 2 | ملفان(双数) |
| few | n % 100 = 3..10 | 3–10、103–110 | 5 ملفات(复数) |
| many | n % 100 = 11..99 | 11–99、111 | 11 ملفًا(单数宾格) |
| other | 其余所有数 | 100–102、1000、0.5 | 100 ملف(单数) |
有两个细节容易让人栽跟头。第一,类别不等于数字本身:103 属于 few,111 属于 many。第二,英语源文件只给模型 one 和 other,模型只能单凭语法编出另外四种形式。大多数失败都来自模型照抄英语的那一对。
这种失败是无声的。我们用 intl-messageformat 12.1.5 渲染一条只有 one 和 other 的阿拉伯语消息:0、2 和 11 个文件全都显示为“N ملف”。缺少 _many 键时,i18next 27.1.2 的表现也一样:11 个文件显示的是 _other 的文本。没有错误,没有警告,只有错误的阿拉伯语。
应该怎样把字符串发给模型?
分批发送。每个字符串一个请求,会在系统提示词上浪费 token,还会丢失相关字符串之间的上下文。每次以 JSON 对象发送 50 到 200 个键,按页面或功能分组,这样“Save”挨着“Cancel”,模型就知道它是一个按钮。
三条规则让回复变得可检查:
- **冻结占位符。**把
{name}、i18next 的双花括号占位符、%s、%1$s以及<b>这样的标签换成 ⟦0⟧ 之类的标记。模型看到的是“Welcome back, ⟦0⟧!”,就没法把name翻译成 اسم。 - **以纯字符串索取复数形式。**发送英语的
one和other文本,要求六个阿拉伯语字符串。ICU 语法由代码构建,模型一个花括号都不用写。 - **提供术语表和不翻译清单。**产品名、套餐名,以及你的客服团队使用的术语。翻译文章中的术语表一节解释了为什么这比选哪个模型更重要。
翻译脚本
源文件使用 FormatJS 文档中描述的 ICU MessageFormat 语法。同样的冻结方法也适用于 i18next 自己的 JSON 格式,其复数键以 _zero、_one、_two、_few、_many 和 _other 结尾。
{
"save": "Save",
"welcome": "Welcome back, {name}!",
"invite": "<b>{inviter}</b> invited you to the {workspace} workspace",
"billing": "Pay with AcmePay",
"files": "{count, plural, one {# file} other {# files}}"
}
import json, os, re
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
FORMS = ["zero", "one", "two", "few", "many", "other"]
# ICU arguments, double-brace and printf placeholders, HTML-style tags
PH = re.compile(r"\{\{\s*\w+\s*\}\}|\{\w+\}|%(?:\d+\$)?[sdif@]|</?\w+[^>]*>")
PLURAL = re.compile(r"^\{(\w+), plural,(.*)\}$", re.S)
def freeze(text):
"""Replace each placeholder with ⟦n⟧ so the model cannot translate or break it."""
found = PH.findall(text)
for i, p in enumerate(found):
text = text.replace(p, f"⟦{i}⟧", 1)
return text, found
def thaw(text, found):
for i, p in enumerate(found):
text = text.replace(f"⟦{i}⟧", p)
return text
def branches(body):
"""'one {# file} other {# files}' -> {'one': '# file', 'other': '# files'}."""
out, i = {}, 0
while i < len(body):
m = re.compile(r"\s*([=\w]+)\s*\{").match(body, i)
if not m:
break
depth, j = 1, m.end()
while depth:
depth += {"{": 1, "}": -1}.get(body[j], 0)
j += 1
out[m.group(1)] = body[m.end():j - 1]
i = j
return out
SYSTEM = """You translate app interface strings from English to Modern Standard Arabic.
Reply with one JSON object only: {"STRINGS": {key: Arabic}, "PLURALS": {key: {six forms}}}.
Rules:
- ⟦0⟧, ⟦1⟧ ... are placeholders. Keep every one exactly once and unchanged; move it if Arabic word order needs it.
- # stands for the number. Keep it where the number should appear.
- Interface style: short, no full stops on buttons or labels.
- Never translate terms in DO_NOT_TRANSLATE. Use GLOSSARY translations exactly.
- For each PLURALS key, return all six Arabic forms: zero, one, two, few, many, other.
zero = none; one = singular without a number; two = dual without a number;
few = 3-10: # + plural noun; many = 11-99: # + singular noun in the accusative;
other = 100, 1000 and also 0.5 and 1.5: # + singular noun."""
def translate(src, glossary=None, dnt=(), model="broadnet/qwen3.8-27b"):
strings, plurals, frozen = {}, {}, {}
for key, text in src.items():
m = PLURAL.match(text)
if m:
b = branches(m.group(2))
fone, ph = freeze(b.get("one", b["other"]))
fother, _ = freeze(b["other"])
plurals[key] = {"one": fone, "other": fother}
frozen[key] = (m.group(1), ph)
elif "{" in PH.sub("", text):
raise ValueError(f"{key}: nested ICU, send to a human")
else:
strings[key], ph = freeze(text)
frozen[key] = (None, ph)
payload = {"STRINGS": strings, "PLURALS": plurals,
"GLOSSARY": glossary or {}, "DO_NOT_TRANSLATE": list(dnt)}
r = client.chat.completions.create(
model=model, max_tokens=4000, temperature=0.2,
messages=[{"role": "system", "content": SYSTEM},
{"role": "user", "content": json.dumps(payload, ensure_ascii=False)}])
out = json.loads(r.choices[0].message.content)
ar = {k: thaw(v, frozen[k][1]) for k, v in out.get("STRINGS", {}).items() if k in frozen}
for k, forms in out.get("PLURALS", {}).items():
if k not in frozen:
continue
arg, ph = frozen[k]
ar[k] = "{%s, plural, %s}" % (arg, " ".join(
f + " {" + thaw(forms[f], ph) + "}" for f in FORMS if f in forms))
return ar
en = json.load(open("en.json"))
ar = translate(en, glossary={"workspace": "مساحة العمل"}, dnt=["AcmePay"])
json.dump(ar, open("ar.json", "w"), ensure_ascii=False, indent=2)
我们用 OpenAI Python SDK 在本地模拟服务器上运行了它(不是线上 API),使用一条预设的阿拉伯语回复。模型看到的请求中是“Welcome back, ⟦0⟧!”和“⟦0⟧⟦1⟧⟦2⟧ invited you to the ⟦3⟧ workspace”,脚本写出了这个 ar.json:
{
"save": "حفظ",
"welcome": "مرحبًا بعودتك يا {name}!",
"invite": "دعاك <b>{inviter}</b> إلى مساحة العمل {workspace}",
"billing": "ادفع عبر AcmePay",
"files": "{count, plural, zero {لا توجد ملفات} one {ملف واحد} two {ملفان} few {# ملفات} many {# ملفًا} other {# ملف}}"
}
关于这段代码:
- **标记会移动,但不会消失。**阿拉伯语常常把动词放在前面,所以 ⟦0⟧ 可能会移位。下面的检查只统计标记数量,不关心它们的位置。
- 嵌套 ICU 交给人处理。
plural里面嵌套select很少见,也很容易弄坏。脚本直接拒绝,而不是去猜。 - **
max_tokens=4000为思考留出空间。**BroadNet 的文档说明,DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 会先思考再作答,思考内容计入 max_tokens。参见思考模型返回空响应。 - **
json.loads可能失败。**把它包起来,出错时附上错误信息重发一次;修复大模型返回的无效 JSON 里有一个经过测试的修复函数。在 GLM 5.3 和 Qwen3.8 27B 这两个文档注明支持结构化输出的 BroadNet 模型上,还可以加上response_formatschema。无论哪种情况,下面的检查都要保留。
如何在 CI 中校验阿拉伯语文件?
用应用运行时所用的同一个解析器解析每条消息,并与源文件比较。这个 Node 脚本使用 @formatjs/icu-messageformat-parser(我们测试时为 3.5.23 版):
// node check-ar.mjs en.json ar.json -> exits 1 on any problem
import { readFileSync } from "node:fs";
import { parse, TYPE } from "@formatjs/icu-messageformat-parser";
const AR_FORMS = ["zero", "one", "two", "few", "many", "other"];
const [en, ar] = process.argv.slice(2).map((p) => JSON.parse(readFileSync(p, "utf8")));
const errors = [];
// Collect argument and tag names; return the plural elements too.
function walk(nodes, names = [], plurals = []) {
for (const n of nodes) {
if (n.type === TYPE.literal || n.type === TYPE.pound) continue;
names.push(n.type === TYPE.tag ? `<${n.value}>` : `{${n.value}}`);
if (n.type === TYPE.tag) walk(n.children, names, plurals);
if (n.type === TYPE.plural) plurals.push(n);
if (n.options) for (const o of Object.values(n.options)) walk(o.value, [], plurals);
}
return { names: names.sort().join(" "), plurals };
}
for (const key of Object.keys(en)) {
if (!(key in ar)) { errors.push(`${key}: missing`); continue; }
let src, dst;
try { src = walk(parse(en[key])); dst = walk(parse(ar[key], { requiresOtherClause: true })); }
catch (e) { errors.push(`${key}: ICU syntax error ${e.message}`); continue; }
if (src.names !== dst.names) errors.push(`${key}: arguments differ: [${src.names}] vs [${dst.names}]`);
for (const p of dst.plurals) {
const missing = AR_FORMS.filter((f) => !(f in p.options));
if (missing.length) errors.push(`${key}: plural {${p.value}} lacks ${missing.join(", ")}`);
}
if (!/[-ۿ]/.test(ar[key])) errors.push(`${key}: no Arabic letters`);
if (/⟦\d+⟧/.test(ar[key])) errors.push(`${key}: placeholder marker left in text`);
}
for (const key of Object.keys(ar)) if (!(key in en)) errors.push(`${key}: not in source`);
console.log(errors.join("\n") || "ok");
process.exit(errors.length ? 1 : 0);
对上面的文件,它输出 ok。然后我们让模拟回复丢掉 many 形式和 {workspace} 标记。脚本以退出码 1 结束,并输出:
invite: arguments differ: [<b> {inviter} {workspace}] vs [<b> {inviter}]
files: plural {count} lacks many
“no Arabic letters”规则会标出模型留在英语里没翻译的字符串。它也会标出只有产品名或数字的值,所以要为这些值准备一份白名单。对于 i18next 自己的格式,按键做同样的检查:英语中每一对 _one/_other,在阿拉伯语中都需要全部六个带后缀的键,而且每个键的占位符都要相同,只是 _zero、_one 和 _two 可以不带计数。
最后,用你真正的格式化器渲染几个数字。用 intl-messageformat 12.1.5,上面的 files 消息得到 0 → لا توجد ملفات、2 → ملفان、5 → 5 ملفات、11 → 11 ملفًا、102 → 102 ملف、111 → 111 ملفًا。这种抽查能发现能通过解析、却用错了名词形式的情况。
从右到左显示怎么办?
翻译解决的是用词,浏览器还得把它们排好顺序。当拉丁字母的名称或数字插入阿拉伯语句子时,Unicode 双向算法可能挪动标点,或者调换相邻的文本段。W3C 的建议是隔离插入的文本:在 HTML 中用 <bdi> 或带 dir="auto" 的元素包裹;在推送通知这类纯文本中,用 U+2068 FIRST STRONG ISOLATE 和 U+2069 POP DIRECTIONAL ISOLATE 把它括起来。
这一步要在插值的地方做,而不是在翻译里做。在我们的测试中,把名字用 U+2068 和 U+2069 包裹后格式化欢迎消息,输出保留了这两个字符,阿拉伯语部分完全不受影响。页面或容器上也要设置 dir="rtl" 和 lang="ar"。阿拉伯语提示词工程有一份 RTL 显示问题的简短检查清单。
数字由格式化器决定,而不是由翻译决定。字符串里保留 # 或参数。在 Node 24(ICU 78.3)中,Intl.NumberFormat 对 ar 把 1234 写成 1,234,对 ar-EG 和 ar-SA 则写成 ١٬٢٣٤。请选择与你的市场匹配的语言区域标签。更广泛的产品问题(界面语言区域与模型语言、混合方向的聊天气泡、语言检测和各语言成本),参见为多语言设计 AI 体验。
谁来审校输出?
带有这些检查的大模型流水线能保证文件格式正确,但不能保证阿拉伯语正确。请阿拉伯语母语者审校:
- **只审新增和改动的字符串。**把
en.json与上一个版本做 diff,只翻译有变化的部分。审校量小,已批准的字符串也不会再变。 - **逐词检查复数形式。**与数字的一致关系是模型最常出错的地方,尤其是 11 到 99 之后的宾格。
- **性别。**在阿拉伯语中,“你”和动词会随读者的性别变化。如果你的界面直接称呼用户,就要定一个约定,比如固定用一种形式,或改用中性表述,并写进系统提示词。
- **长度。**阿拉伯语字符串可能比英语长,也可能比英语短。在移动端宽度的真实布局中检查按钮和标签页。
在代码仓库里保留一份审校过的术语表文件,并随每个请求一起发送,让已批准的术语保持固定。
成本是多少?
字符串文件很小。输出与输入长度相当,而阿拉伯语每个词通常比英语需要更多 token;阿拉伯语与英语每词 token 数给出了实测比值。把一批字符串粘贴到阿拉伯语 token 计数器,乘以批次数,再给每批加上系统提示词。思考模型还会在思考上消耗 token;BroadNet 在 usage 中以 completion_tokens_details.reasoning_tokens 报告这部分,所以外推之前,先从一个真实请求中读取 usage。
| 模型 | 本任务说明 | 每百万 token 输入 / 输出 |
|---|---|---|
| Qwen3.8 27B | 文档注明支持结构化输出 | $0.175 / $2.17 |
| GLM 5.3 | 文档注明支持结构化输出;1,048,576 token 上下文 | $0.78 / $3.46 |
| Gemma 4 VL 26B | 可以用 $5 的初始额度运行;JSON 只能靠提示词约束,所以校验器更重要 | $0.10 / $0.22 |
| DeepSeek V4.1 Flash | 也有固定价格套餐,例如每个会话每周 $15,每个会话一次一个请求 | $0.175 / $0.52 |
价格来自 BroadNet 的价格数据,更新于 2026-11-14。用两个模型翻译同样的 100 个字符串,请审校者比较之后再做选择;每 token 价格不如需要修改的数量重要。如果是多种语言、成千上万个键,没有 Batch API 时的批量处理介绍了并发和重试。
BroadNet Inference 的定位
BroadRouter 是 BroadNet 自己的网站。BroadNet Inference 以 OpenAI 兼容方式提供上述模型,所以只要改一下 base URL 和模型 ID,脚本就能用 OpenAI Python SDK 运行;各模型支持哪些参数,请查看 API 参考。它没有翻译端点,也没有发布本地化基准,所以校验器和人工审校仍然是你的质量关卡。专门的本地化平台还提供翻译记忆、审校工作流和上下文截图;如果你需要这些功能,就用这样的平台,并把上面的 CI 检查作为第二道防线。
