Tradurre i file di stringhe di un’app è un lavoro diverso dal tradurre testo discorsivo. Ogni valore è breve, spesso senza contesto, e contiene sintassi che il modello non deve toccare: placeholder, tag HTML e regole del plurale. Con l’arabo l’ultima diventa difficile. I file inglesi hanno due forme plurali; l’arabo ne richiede sei. Questo articolo costruisce una piccola pipeline su un LLM compatibile con OpenAI: blocca i placeholder, chiede sei stringhe plurali semplici, compone la sintassi ICU nel codice e poi valida tutto in CI.
Per tradurre documenti, ticket e contratti, vedi traduzione arabo–inglese con gli LLM, che tratta tono, glossari e valutazione per il testo discorsivo.
Perché i plurali arabi rompono i file di stringhe tradotti in automatico?
Unicode CLDR, che Intl.PluralRules, ICU e i18next seguono tutti, dà all’arabo sei categorie cardinali:
| Categoria | Regola CLDR | Numeri di esempio | Esempio: «file» |
|---|---|---|---|
| zero | n = 0 | 0 | لا توجد ملفات |
| one | n = 1 | 1 | ملف واحد |
| two | n = 2 | 2 | ملفان (duale) |
| few | n % 100 = 3..10 | 3–10, 103–110 | 5 ملفات (plurale) |
| many | n % 100 = 11..99 | 11–99, 111 | 11 ملفًا (singolare, accusativo) |
| other | tutto il resto | 100–102, 1000, 0,5 | 100 ملف (singolare) |
Due dettagli traggono in inganno. Primo, le categorie non sono i numeri: 103 è few e 111 è many. Secondo, una fonte inglese dà al modello solo one e other, quindi deve inventare quattro forme partendo dalla sola grammatica. La maggior parte degli errori nasce dal modello che copia la coppia inglese.
L’errore è silenzioso. Abbiamo reso con intl-messageformat 12.1.5 un messaggio arabo che aveva solo one e other: 0, 2 e 11 file uscivano tutti come «N ملف». i18next 27.1.2 si è comportato allo stesso modo quando mancava la chiave _many: 11 file mostravano il testo di _other. Nessun errore, nessun avviso, solo arabo sbagliato.
Come conviene inviare le stringhe al modello?
A lotti. Una richiesta per stringa spreca token sul system prompt e perde il contesto tra stringhe collegate. Invia da 50 a 200 chiavi alla volta come oggetto JSON, raggruppate per schermata o funzionalità, così «Save» accanto a «Cancel» si legge come un pulsante.
Tre regole rendono verificabile la risposta:
- Blocca i placeholder. Sostituisci
{name}, i placeholder di i18next con doppie graffe,%s,%1$se tag come<b>con marcatori come ⟦0⟧. Il modello vede «Welcome back, ⟦0⟧!» e non può tradurrenamein اسم. - Chiedi le forme plurali come stringhe semplici. Invia i testi inglesi
oneeothere chiedi sei stringhe arabe. La sintassi ICU la costruisce il codice. Il modello non scrive mai una graffa. - Fornisci un glossario e un elenco di termini da non tradurre. Nomi di prodotto, nomi dei piani e termini che usa il tuo team di supporto. La sezione sul glossario dell’articolo sulla traduzione spiega perché questo conta più della scelta del modello.
Lo script di traduzione
Il file sorgente usa ICU MessageFormat, la sintassi documentata da FormatJS. Lo stesso blocco dei placeholder funziona con il formato JSON di i18next, le cui chiavi plurali finiscono in _zero, _one, _two, _few, _many e _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)
L’abbiamo eseguito con l’SDK Python di OpenAI contro un server mock locale, non contro l’API reale, con una risposta araba preimpostata. La richiesta che il modello avrebbe visto conteneva «Welcome back, ⟦0⟧!» e «⟦0⟧⟦1⟧⟦2⟧ invited you to the ⟦3⟧ workspace», e lo script ha scritto questo ar.json:
{
"save": "حفظ",
"welcome": "مرحبًا بعودتك يا {name}!",
"invite": "دعاك <b>{inviter}</b> إلى مساحة العمل {workspace}",
"billing": "ادفع عبر AcmePay",
"files": "{count, plural, zero {لا توجد ملفات} one {ملف واحد} two {ملفان} few {# ملفات} many {# ملفًا} other {# ملف}}"
}
Note sul codice:
- I marcatori si spostano, non spariscono. L’arabo mette spesso il verbo all’inizio, quindi ⟦0⟧ può cambiare posizione. Il controllo più sotto conta i marcatori; non gli importa dove stanno.
- L’ICU annidato va a una persona. Un
selectdentro unpluralè raro e facile da rompere. Lo script lo rifiuta invece di tirare a indovinare. max_tokens=4000lascia spazio al ragionamento. Secondo la documentazione di BroadNet, DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il ragionamento conta in max_tokens. Vedi risposte vuote dai modelli di ragionamento.json.loadspuò fallire. Racchiudilo in un try e rimanda la richiesta una volta con l’errore; correggere il JSON non valido di un LLM ha una funzione di riparazione testata. Su GLM 5.3 e Qwen3.8 27B, i due modelli BroadNet documentati con output strutturato, aggiungi anche uno schemaresponse_format. Il controllo qui sotto resta in ogni caso.
Come si valida il file arabo in CI?
Analizza ogni messaggio con lo stesso parser che la tua app usa a runtime e confrontalo con la fonte. Questo script Node usa @formatjs/icu-messageformat-parser (versione 3.5.23 nel nostro test):
// 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);
Sul file qui sopra ha stampato ok. Poi abbiamo fatto in modo che la risposta del mock perdesse la forma many e il marcatore {workspace}. Lo script è uscito con codice 1 e ha stampato:
invite: arguments differ: [<b> {inviter} {workspace}] vs [<b> {inviter}]
files: plural {count} lacks many
La regola «no Arabic letters» segnala le stringhe che il modello ha lasciato in inglese. Segnala anche i valori composti solo da un nome di prodotto o da un numero, quindi tieni una allow-list per quelli. Per il formato proprio di i18next, applica gli stessi controlli chiave per chiave: ogni coppia _one/_other in inglese richiede in arabo tutte e sei le chiavi con suffisso, ciascuna con gli stessi placeholder, salvo che _zero, _one e _two possono omettere il conteggio.
Infine, fai passare qualche numero dal tuo formattatore reale. Con intl-messageformat 12.1.5, il messaggio files qui sopra ha dato 0 → لا توجد ملفات, 2 → ملفان, 5 → 5 ملفات, 11 → 11 ملفًا, 102 → 102 ملف e 111 → 111 ملفًا. Questo controllo a campione intercetta una forma che supera il parser ma usa il sostantivo sbagliato.
E la visualizzazione da destra a sinistra?
La traduzione mette a posto le parole; il browser deve ancora ordinarle. Quando un nome in caratteri latini o un numero viene inserito in una frase araba, l’algoritmo bidirezionale Unicode può spostare la punteggiatura o scambiare segmenti vicini. Il consiglio del W3C è isolare il testo inserito: racchiuderlo in <bdi> o in un elemento con dir="auto" in HTML, oppure circondarlo con U+2068 FIRST STRONG ISOLATE e U+2069 POP DIRECTIONAL ISOLATE nel testo semplice, come nelle notifiche push.
Fallo nel punto in cui interpoli, non nella traduzione. Nel nostro test, formattare il messaggio di benvenuto con il nome racchiuso tra U+2068 e U+2069 ha mantenuto entrambi i caratteri nell’output e lasciato intatto l’arabo. Imposta anche dir="rtl" e lang="ar" sulla pagina o sul contenitore. Prompt engineering in arabo ha una breve checklist per i bug di visualizzazione RTL.
Le cifre sono una scelta del formattatore, non della traduzione. Tieni # o l’argomento nella stringa. In Node 24 (ICU 78.3), Intl.NumberFormat ha scritto 1234 come 1,234 per ar e come ١٬٢٣٤ per ar-EG e ar-SA. Scegli il tag di locale adatto al tuo mercato. Per le questioni di prodotto più ampie (lingua dell’interfaccia contro lingua del modello, fumetti di chat con direzioni miste, rilevamento della lingua e costo per lingua), vedi progettare un’esperienza AI in più lingue.
Chi deve rivedere l’output?
Una pipeline LLM con questi controlli garantisce che il file sia ben formato. Non garantisce che l’arabo sia giusto. Fai rivedere a un madrelingua arabo:
- Solo le stringhe nuove e modificate. Fai il diff di
en.jsonrispetto all’ultimo rilascio e traduci solo ciò che è cambiato. Le revisioni restano piccole e le stringhe approvate non si muovono più. - Le forme plurali, parola per parola. La concordanza con i numeri è il punto in cui il modello sbaglia più spesso, soprattutto l’accusativo dopo i numeri da 11 a 99.
- Il genere. In arabo «tu» e i verbi cambiano con il genere di chi legge. Se la tua interfaccia si rivolge direttamente agli utenti, decidi una convenzione, come una forma fissa o una riformulazione neutra, e mettila nel system prompt.
- La lunghezza. Le stringhe arabe possono essere più lunghe o più corte di quelle inglesi. Controlla pulsanti e schede nel layout reale, a larghezza mobile.
Tieni nel repository un file di glossario revisionato e invialo a ogni richiesta, così i termini approvati restano fissi.
Quanto costa?
I file di stringhe sono piccoli. L’output è lungo più o meno quanto l’input, e l’arabo di solito richiede più token per parola dell’inglese; token per parola in arabo e in inglese riporta rapporti misurati. Incolla un lotto nel contatore di token per l’arabo, moltiplica per il numero di lotti e aggiungi il system prompt a ciascuno. I modelli di ragionamento spendono token anche per pensare; BroadNet li riporta in usage come completion_tokens_details.reasoning_tokens, quindi leggi usage da una richiesta reale prima di estrapolare.
| Modello | Note per questo lavoro | Input / output per 1M di token |
|---|---|---|
| Qwen3.8 27B | Output strutturato documentato | $0.175 / $2.17 |
| GLM 5.3 | Output strutturato documentato; contesto di 1.048.576 token | $0.78 / $3.46 |
| Gemma 4 VL 26B | Funziona con il credito iniziale di $5; JSON solo tramite prompt, quindi il validatore conta di più | $0.10 / $0.22 |
| DeepSeek V4.1 Flash | Disponibile anche con piani a prezzo fisso, come $15 a settimana per sessione, una richiesta alla volta per sessione | $0.175 / $0.52 |
I prezzi vengono dal feed prezzi di BroadNet, sincronizzati 2026-11-14. Traduci le stesse 100 stringhe con due modelli e fai confrontare i risultati al tuo revisore prima di sceglierne uno; il prezzo per token conta meno del numero di correzioni. Per migliaia di chiavi in molte lingue, elaborazione in batch senza una Batch API tratta concorrenza e nuovi tentativi.
Dove si colloca BroadNet Inference
BroadRouter è il sito di BroadNet. BroadNet Inference dà accesso compatibile con OpenAI ai modelli qui sopra, quindi lo script funziona con l’SDK Python di OpenAI cambiando base URL e ID del modello; controlla nel riferimento API i parametri supportati da ciascun modello. Non ha un endpoint di traduzione e non pubblica un benchmark di localizzazione, quindi il validatore e un revisore umano restano il tuo controllo di qualità. Le piattaforme di localizzazione dedicate aggiungono memoria di traduzione, flussi di revisione e screenshot nel contesto; se ti servono, usane una e tieni il controllo in CI qui sopra come seconda linea.
