Перевод строковых файлов приложения — другая задача, чем перевод связного текста. Каждое значение короткое, часто без контекста и несёт синтаксис, который модель не должна трогать: плейсхолдеры, HTML-теги и правила множественного числа. Последнее в арабском и есть главная сложность. В английских файлах две формы числа, арабскому нужно шесть. В этой статье мы собираем небольшой конвейер на OpenAI-совместимой LLM: замораживаем плейсхолдеры, просим шесть простых строк для форм числа, собираем синтаксис ICU в коде и проверяем всё в CI.
О переводе документов, тикетов и договоров — в статье арабско-английский перевод с LLM: там разобраны тон, глоссарии и оценка для связного текста.
Почему арабские формы числа ломают машинный перевод строковых файлов?
Unicode CLDR, которому следуют Intl.PluralRules, ICU и i18next, даёт арабскому шесть количественных категорий:
| Категория | Правило 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, поэтому четыре формы ей приходится придумывать по одной грамматике. Большинство сбоев — это модель, скопировавшая английскую пару.
Сбой беззвучный. Мы отрендерили арабское сообщение только с one и other через intl-messageformat 12.1.5: 0, 2 и 11 файлов вышли как «N ملف». i18next 27.1.2 вёл себя так же при отсутствии ключа _many: для 11 файлов показывался текст _other. Ни ошибки, ни предупреждения — просто неправильный арабский.
Как отправлять строки модели?
Пакетами. Один запрос на строку тратит токены на системный промпт и теряет контекст между связанными строками. Отправляйте от 50 до 200 ключей за раз в виде JSON-объекта, сгруппированного по экранам или функциям, чтобы «Save» рядом с «Cancel» читалось как кнопка.
Три правила делают ответ проверяемым:
- Заморозьте плейсхолдеры. Замените
{name}, плейсхолдеры i18next в двойных фигурных скобках,%s,%1$sи теги вроде<b>маркерами вроде ⟦0⟧. Модель видит «Welcome back, ⟦0⟧!» и не может перевестиnameкак اسم. - Просите формы числа простыми строками. Отправьте английские тексты
oneиotherи попросите шесть арабских строк. Синтаксис ICU строит код. Модель никогда не пишет фигурных скобок. - Дайте глоссарий и список того, что не переводить. Названия продуктов, тарифов и термины, которыми пользуется ваша поддержка. Раздел о глоссарии в статье о переводе объясняет, почему это важнее выбора модели.
Скрипт перевода
Исходный файл использует ICU MessageFormat — синтаксис, который документирует FormatJS. Та же заморозка работает и с собственным JSON-форматом i18next, где ключи форм числа оканчиваются на _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 на локальном mock-сервере, а не на реальном 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 отдаётся человеку.
selectвнутриpluralвстречается редко и легко ломается. Скрипт отказывается его обрабатывать, а не гадает. max_tokens=4000оставляет место для рассуждений. Документация BroadNet говорит, что DeepSeek V4.1 Flash, GLM 5.3 и Qwen3.8 27B рассуждают перед ответом и рассуждения учитываются в max_tokens. См. пустые ответы от моделей с рассуждениями.json.loadsможет упасть. Оберните его и один раз отправьте запрос повторно с текстом ошибки; в статье как исправить невалидный JSON от LLM есть проверенная функция починки. На GLM 5.3 и Qwen3.8 27B — двух моделях BroadNet, для которых задокументирован структурированный вывод, — добавьте ещё и схему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. Затем мы заставили mock-ответ потерять форму 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 могут обходиться без count.
Наконец, пропустите несколько чисел через ваш настоящий форматтер. С intl-messageformat 12.1.5 сообщение files выше дало 0 → لا توجد ملفات, 2 → ملفان, 5 → 5 ملفات, 11 → 11 ملفًا, 102 → 102 ملف и 111 → 111 ملفًا. Такая выборочная проверка ловит форму, которая разбирается парсером, но использует не то существительное.
А что с отображением справа налево?
Перевод даёт правильные слова, но упорядочить их ещё должен браузер. Когда латинское имя или число вставляется в арабское предложение, двунаправленный алгоритм Unicode может переместить пунктуацию или поменять местами соседние фрагменты. W3C советует изолировать вставленный текст: оборачивать его в <bdi> или элемент с dir="auto" в HTML, а в простом тексте, например в push-уведомлениях, окружать символами 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 как 1,234 для ar и как ١٬٢٣٤ для ar-EG и ar-SA. Выбирайте тег локали, подходящий вашему рынку. О более широких продуктовых вопросах (язык интерфейса против языка модели, пузыри чата со смешанными направлениями, определение языка и стоимость по языкам) — в статье как спроектировать ИИ-продукт для нескольких языков.
Кто должен проверять результат?
Конвейер на LLM с этими проверками гарантирует, что файл корректно сформирован. Он не гарантирует, что арабский правильный. Пусть носитель арабского вычитает:
- Только новые и изменённые строки. Сравните
en.jsonс последним релизом и переводите только изменения. Проверки остаются небольшими, а одобренные строки никогда не меняются. - Формы числа, слово за словом. Согласование с числами — место, где модель ошибается чаще всего, особенно винительный падеж после 11–99.
- Род. «Ты» и глаголы в арабском меняются в зависимости от пола читателя. Если интерфейс обращается к пользователю напрямую, выберите правило, например фиксированную форму или нейтральную перефразировку, и впишите его в системный промпт.
- Длину. Арабские строки бывают длиннее или короче английских. Проверьте кнопки и вкладки в реальной вёрстке на ширине мобильного экрана.
Держите проверенный файл глоссария в репозитории и отправляйте его с каждым запросом, чтобы одобренные термины не менялись.
Сколько это стоит?
Строковые файлы маленькие. Вывод примерно такой же длины, как вход, а арабскому обычно нужно больше токенов на слово, чем английскому; измеренные соотношения — в статье токены на слово в арабском и английском. Вставьте пакет в счётчик токенов для арабского, умножьте на число пакетов и добавьте системный промпт к каждому. Модели с рассуждениями тратят токены ещё и на размышления; BroadNet показывает их в usage как completion_tokens_details.reasoning_tokens, поэтому посмотрите usage реального запроса, прежде чем экстраполировать.
| Модель | Заметки для этой задачи | Вход / выход за 1 млн токенов |
|---|---|---|
| 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 | Есть и на тарифах с фиксированной ценой, например $15 в неделю за сессию, один запрос за раз на сессию | $0.175 / $0.52 |
Цены взяты из фида цен BroadNet, обновлено 2026-11-14. Переведите одни и те же 100 строк двумя моделями и попросите рецензента сравнить их, прежде чем выбирать; цена за токен важна меньше, чем число правок. Для тысяч ключей на многих языках параллелизм и повторы разбирает статья пакетная обработка без Batch API.
Где здесь BroadNet Inference
BroadRouter — собственный сайт BroadNet. BroadNet Inference даёт OpenAI-совместимый доступ к моделям выше, поэтому скрипт работает с OpenAI Python SDK после смены базового URL и ID модели; какие параметры поддерживает каждая модель, смотрите в справочнике API. Эндпоинта перевода у неё нет, и бенчмарков локализации она не публикует, так что контролем качества остаются валидатор и рецензент-человек. Специализированные платформы локализации добавляют память переводов, процессы рецензирования и скриншоты в контексте; если вам это нужно, используйте такую платформу, а проверку в CI выше оставьте второй линией защиты.
