アプリの文字列ファイルの翻訳は、文章の翻訳とは別の仕事です。値はどれも短く、文脈がないことが多いうえ、モデルが触れてはならない構文(プレースホルダー、HTML タグ、複数形のルール)を含んでいます。アラビア語では最後の 1 つが難題です。英語のファイルには複数形が 2 つしかありませんが、アラビア語には 6 つ必要です。この記事では、OpenAI 互換の LLM で小さなパイプラインを作ります。プレースホルダーを固定し、6 つのプレーンな複数形の文字列を求め、ICU 構文をコードで組み立て、最後に CI ですべてを検証します。
文書、チケット、契約書の翻訳については、文章の口調、用語集、評価を扱ったLLM によるアラビア語と英語の翻訳を参照してください。
なぜアラビア語の複数形は機械翻訳した文字列ファイルを壊すのですか?
Intl.PluralRules、ICU、i18next はいずれも Unicode CLDR に従っており、CLDR はアラビア語に 6 つの基数カテゴリーを定めています。
| カテゴリー | 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 ملف(単数) |
つまずきやすい点が 2 つあります。1 つ目は、カテゴリーは数そのものではないことです。103 は few、111 は many です。2 つ目は、英語の原文はモデルに one と other しか与えないので、モデルは文法だけを頼りに 4 つの形を作り出さなければならないことです。失敗の多くは、モデルが英語の 2 つをそのまま写すことから起こります。
この失敗は表に出ません。one と other しかないアラビア語のメッセージを intl-messageformat 12.1.5 で表示したところ、0、2、11 ファイルはすべて「N ملف」になりました。i18next 27.1.2 も、_many キーがないと同じ挙動で、11 ファイルに _other のテキストが表示されました。エラーも警告もなく、ただアラビア語が間違っているだけです。
文字列はどうやってモデルに送ればよいですか?
まとめて送ります。文字列ごとに 1 リクエストでは、システムプロンプトでトークンを無駄にし、関連する文字列の文脈も失われます。50〜200 キーずつ JSON オブジェクトとして、画面や機能ごとにまとめて送れば、「Cancel」の隣の「Save」はボタンだとわかります。
返答を検証可能にするルールは 3 つです。
- プレースホルダーを固定する。
{name}、i18next の二重波かっこのプレースホルダー、%s、%1$s、<b>などのタグを ⟦0⟧ のようなマーカーに置き換えます。モデルが見るのは「Welcome back, ⟦0⟧!」なので、nameを اسم と翻訳することはできません。 - **複数形はプレーンな文字列で求める。**英語の
oneとotherのテキストを送り、アラビア語の文字列を 6 つ求めます。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)
本番の API ではなく、ローカルのモックサーバーに対して OpenAI Python SDK で実行し、用意したアラビア語の返答を使いました。モデルが受け取るリクエストには「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は失敗することがあります。**try で囲み、エラー内容を付けて 1 回だけ再送してください。LLM の不正な JSON を直す方法にテスト済みの修復関数があります。構造化出力がドキュメント化されている BroadNet の 2 モデル、GLM 5.3 と Qwen3.8 27B では、response_formatのスキーマも追加してください。どちらの場合も、下のチェックは残します。
アラビア語ファイルは 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 の組ごとに、アラビア語では接尾辞付きの 6 キーすべてが必要で、それぞれ同じプレースホルダーを持たなければなりません。ただし _zero、_one、_two では count を省いてもかまいません。
最後に、実際のフォーマッターでいくつかの数を表示してみます。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 は 1234 を ar で 1,234、ar-EG と ar-SA で ١٬٢٣٤ と出力しました。市場に合ったロケールタグを選んでください。より広い製品上の課題(UI のロケールとモデルの言語、方向が混在するチャットの吹き出し、言語検出、言語ごとのコスト)は、多言語の AI 体験をデザインするを参照してください。
出力は誰がレビューすべきですか?
これらのチェックを備えた LLM パイプラインは、ファイルの形式が正しいことは保証しますが、アラビア語が正しいことまでは保証しません。アラビア語話者に次の点をレビューしてもらってください。
- 新規と変更のあった文字列だけ。
en.jsonを前回のリリースと比較し、変わった部分だけを翻訳します。レビューは小さく保たれ、承認済みの文字列は変わりません。 - **複数形は 1 語ずつ。**数との一致はモデルが最も間違えやすいところで、特に 11〜99 の後の対格が要注意です。
- **性別。**アラビア語では「あなた」や動詞が読み手の性別で変わります。UI がユーザーに直接呼びかけるなら、固定の形にするか中立的な言い回しにするかなどの方針を決め、システムプロンプトに書いてください。
- **長さ。**アラビア語の文字列は英語より長くなることも短くなることもあります。ボタンやタブは、モバイル幅の実際のレイアウトで確認してください。
レビュー済みの用語集ファイルをリポジトリに置き、毎回のリクエストで送れば、承認された用語が固定されます。
コストはどのくらいですか?
文字列ファイルは小さなものです。出力は入力とほぼ同じ長さで、アラビア語は通常、英語より 1 語あたりのトークンが多くなります。実測の比率はアラビア語と英語の 1 語あたりのトークン数にあります。1 バッチ分をアラビア語トークンカウンターに貼り付け、バッチ数を掛け、各バッチにシステムプロンプトの分を加えます。推論モデルは考える分のトークンも使います。BroadNet はそれを usage の completion_tokens_details.reasoning_tokens として報告するので、見積もりを広げる前に実際のリクエストで usage を確認してください。
| モデル | この作業での注意点 | 100 万トークンあたり入力/出力 |
|---|---|---|
| Qwen3.8 27B | 構造化出力がドキュメント化されている | $0.175 / $2.17 |
| GLM 5.3 | 構造化出力がドキュメント化されている。コンテキストは 1,048,576 トークン | $0.78 / $3.46 |
| Gemma 4 VL 26B | $5 の初回クレジットで使える。JSON はプロンプト頼みなので検証ツールがより重要 | $0.10 / $0.22 |
| DeepSeek V4.1 Flash | 定額プランもある(例:1 セッション 1 週間 $15、セッションごとに一度に 1 リクエスト) | $0.175 / $0.52 |
料金は BroadNet の料金フィードに基づき、2026-11-14 に更新されたものです。選ぶ前に、同じ 100 個の文字列を 2 つのモデルで翻訳し、レビュー担当者に比べてもらってください。トークン単価より、必要な修正の数のほうが重要です。多数の言語にわたる数千のキーを扱うなら、Batch API なしでのバッチ処理で並列処理と再試行を扱っています。
BroadNet Inference の位置づけ
BroadRouter は BroadNet 自身のサイトです。BroadNet Inference は上記のモデルを OpenAI 互換で提供しているので、ベース URL とモデル ID を変えれば、スクリプトは OpenAI Python SDK で動きます。各モデルが対応するパラメーターは API リファレンスで確認してください。翻訳用のエンドポイントはなく、ローカライズのベンチマークも公開していないので、品質のゲートは引き続き検証ツールと人のレビュー担当者です。専用のローカライズプラットフォームには、翻訳メモリ、レビューのワークフロー、文脈付きスクリーンショットなどがあります。それらが必要ならプラットフォームを使い、上記の CI チェックを第 2 の防衛線として残してください。
