BroadRouter

Traduzir strings de app para árabe com LLM: placeholders e plurais

Pela equipe da BroadNet Inference · 7 min de leitura · Publicado em

Envie as strings como JSON com cada placeholder trocado por um marcador, peça as seis formas de plural do árabe (zero, one, two, few, many, other) e monte o plural ICU no código, não no modelo. Valide na CI: mesmas chaves, mesmos argumentos e tags, as seis formas presentes. Envolva os nomes inseridos em isolamentos Unicode para que o texto da direita para a esquerda seja exibido corretamente.

Traduzir os arquivos de strings de um app é um trabalho diferente de traduzir texto corrido. Cada valor é curto, muitas vezes sem contexto, e carrega sintaxe que o modelo não pode tocar: placeholders, tags HTML e regras de plural. Com o árabe, a última fica difícil. Arquivos em inglês têm duas formas de plural; o árabe precisa de seis. Este post monta um pequeno pipeline sobre um LLM compatível com a OpenAI: congela os placeholders, pede seis strings de plural simples, monta a sintaxe ICU no código e depois valida tudo na CI.

Para traduzir documentos, tickets e contratos, veja tradução árabe–inglês com LLMs, que cobre tom, glossários e avaliação para texto corrido.

Por que os plurais do árabe quebram arquivos de strings traduzidos automaticamente?

O Unicode CLDR, que Intl.PluralRules, ICU e i18next seguem, dá ao árabe seis categorias cardinais:

Categoria Regra do CLDR Números de exemplo Exemplo: “arquivo”
zero n = 0 0 لا توجد ملفات
one n = 1 1 ملف واحد
two n = 2 2 ملفان (dual)
few n % 100 = 3..10 3–10, 103–110 5 ملفات (plural)
many n % 100 = 11..99 11–99, 111 11 ملفًا (singular, acusativo)
other todo o resto 100–102, 1000, 0,5 100 ملف (singular)

Dois detalhes pegam as pessoas de surpresa. Primeiro, as categorias não são os números: 103 é few e 111 é many. Segundo, uma fonte em inglês dá ao modelo só one e other, então ele precisa inventar quatro formas apenas com a gramática. A maioria das falhas vem do modelo copiando o par do inglês.

A falha é silenciosa. Renderizamos com o intl-messageformat 12.1.5 uma mensagem em árabe que só tinha one e other: 0, 2 e 11 arquivos saíram todos como “N ملف”. O i18next 27.1.2 se comportou igual quando faltava a chave _many: 11 arquivos mostraram o texto de _other. Nenhum erro, nenhum aviso, só árabe errado.

Como enviar as strings ao modelo?

Em lotes. Uma requisição por string gasta tokens com o system prompt e perde o contexto entre strings relacionadas. Envie de 50 a 200 chaves por vez como um objeto JSON, agrupadas por tela ou funcionalidade, para que “Save” ao lado de “Cancel” seja lido como botão.

Três regras tornam a resposta verificável:

  1. Congele os placeholders. Troque {name}, os placeholders de chave dupla do i18next, %s, %1$s e tags como <b> por marcadores como ⟦0⟧. O modelo vê “Welcome back, ⟦0⟧!” e não consegue traduzir name para اسم.
  2. Peça as formas de plural como strings simples. Envie os textos em inglês de one e other e peça seis strings em árabe. O código monta a sintaxe ICU. O modelo nunca escreve uma chave.
  3. Forneça um glossário e uma lista do que não traduzir. Nomes de produto, nomes de planos e termos que o seu time de suporte usa. A seção de glossário do post sobre tradução explica por que isso importa mais que a escolha do modelo.

O script de tradução

O arquivo-fonte usa ICU MessageFormat, a sintaxe documentada pelo FormatJS. O mesmo congelamento funciona com o formato JSON próprio do i18next, cujas chaves de plural terminam em _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)

Rodamos isso com o SDK Python da OpenAI contra um servidor mock local, não contra a API real, com uma resposta em árabe pronta. A requisição que o modelo veria continha “Welcome back, ⟦0⟧!” e “⟦0⟧⟦1⟧⟦2⟧ invited you to the ⟦3⟧ workspace”, e o script gravou este ar.json:

{
  "save": "حفظ",
  "welcome": "مرحبًا بعودتك يا {name}!",
  "invite": "دعاك <b>{inviter}</b> إلى مساحة العمل {workspace}",
  "billing": "ادفع عبر AcmePay",
  "files": "{count, plural, zero {لا توجد ملفات} one {ملف واحد} two {ملفان} few {# ملفات} many {# ملفًا} other {# ملف}}"
}

Observações sobre o código:

  • Os marcadores mudam de lugar, não somem. O árabe muitas vezes põe o verbo primeiro, então ⟦0⟧ pode se mover. A checagem abaixo conta os marcadores; não importa onde eles fiquem.
  • ICU aninhado vai para uma pessoa. Um select dentro de um plural é raro e fácil de quebrar. O script o recusa em vez de chutar.
  • max_tokens=4000 deixa espaço para o raciocínio. A documentação da BroadNet diz que DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e que o raciocínio conta para max_tokens. Veja respostas vazias de modelos de raciocínio.
  • json.loads pode falhar. Envolva a chamada e reenvie uma vez com o erro; como corrigir JSON inválido de um LLM tem uma função de reparo testada. No GLM 5.3 e no Qwen3.8 27B, os dois modelos da BroadNet documentados com saída estruturada, acrescente também um schema em response_format. A checagem abaixo continua valendo de qualquer forma.

Como validar o arquivo em árabe na CI?

Faça o parse de cada mensagem com o mesmo parser que o seu app usa em tempo de execução e compare com a fonte. Este script Node usa o @formatjs/icu-messageformat-parser (versão 3.5.23 no nosso teste):

// 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);

No arquivo acima, ele imprimiu ok. Depois fizemos a resposta do mock perder a forma many e o marcador {workspace}. O script saiu com código 1 e imprimiu:

invite: arguments differ: [<b> {inviter} {workspace}] vs [<b> {inviter}]
files: plural {count} lacks many

A regra “no Arabic letters” aponta strings que o modelo deixou em inglês. Ela também aponta valores que são só um nome de produto ou um número, então mantenha uma allow-list para esses casos. Para o formato próprio do i18next, aplique as mesmas checagens chave por chave: cada par _one/_other em inglês exige em árabe as seis chaves com sufixo, cada uma com os mesmos placeholders, exceto que _zero, _one e _two podem omitir a contagem.

Por fim, passe alguns números pelo seu formatador real. Com o intl-messageformat 12.1.5, a mensagem files acima deu 0 → لا توجد ملفات, 2 → ملفان, 5 → 5 ملفات, 11 → 11 ملفًا, 102 → 102 ملف e 111 → 111 ملفًا. Essa checagem por amostragem pega uma forma que passa no parser mas usa o substantivo errado.

E a exibição da direita para a esquerda?

A tradução acerta as palavras; o navegador ainda precisa ordená-las. Quando um nome em letras latinas ou um número é inserido numa frase em árabe, o algoritmo bidirecional do Unicode pode mover a pontuação ou trocar trechos vizinhos de lugar. A recomendação do W3C é isolar o texto inserido: envolvê-lo em <bdi> ou num elemento com dir="auto" no HTML, ou cercá-lo com U+2068 FIRST STRONG ISOLATE e U+2069 POP DIRECTIONAL ISOLATE em texto puro, como em notificações push.

Faça isso onde você interpola, não na tradução. No nosso teste, formatar a mensagem de boas-vindas com o nome entre U+2068 e U+2069 manteve os dois caracteres na saída e deixou o árabe intacto. Defina também dir="rtl" e lang="ar" na página ou no contêiner. Engenharia de prompt em árabe tem um checklist curto para bugs de exibição RTL.

Dígitos são escolha do formatador, não da tradução. Mantenha # ou o argumento na string. No Node 24 (ICU 78.3), o Intl.NumberFormat escreveu 1234 como 1,234 para ar e como ١٬٢٣٤ para ar-EG e ar-SA. Escolha a tag de locale que corresponde ao seu mercado. Para as questões de produto mais amplas (idioma da interface versus idioma do modelo, balões de chat com direções misturadas, detecção de idioma e custo por idioma), veja como projetar uma experiência de IA em vários idiomas.

Quem deve revisar a saída?

Um pipeline de LLM com essas checagens garante que o arquivo está bem formado. Não garante que o árabe está certo. Peça a um falante de árabe para revisar:

  • Só as strings novas e alteradas. Faça o diff do en.json contra o último lançamento e traduza só o que mudou. As revisões ficam pequenas, e as strings aprovadas não mudam mais.
  • As formas de plural, palavra por palavra. A concordância com números é onde o modelo mais escorrega, principalmente o acusativo depois de 11 a 99.
  • O gênero. Em árabe, “você” e os verbos mudam com o gênero de quem lê. Se a sua interface fala diretamente com o usuário, defina uma convenção, como uma forma fixa ou uma reformulação neutra, e coloque-a no system prompt.
  • O comprimento. Strings em árabe podem ficar mais longas ou mais curtas que em inglês. Confira botões e abas no layout real, na largura de celular.

Mantenha no repositório um arquivo de glossário revisado e envie-o em toda requisição, para que os termos aprovados fiquem fixos.

Quanto custa?

Arquivos de strings são pequenos. A saída tem mais ou menos o tamanho da entrada, e o árabe costuma precisar de mais tokens por palavra que o inglês; tokens por palavra em árabe e inglês traz proporções medidas. Cole um lote no contador de tokens para árabe, multiplique pelo número de lotes e some o system prompt a cada um. Modelos de raciocínio também gastam tokens pensando; a BroadNet os informa em usage como completion_tokens_details.reasoning_tokens, então leia o usage de uma requisição real antes de extrapolar.

Modelo Observações para este trabalho Entrada / saída por 1M de tokens
Qwen3.8 27B Saída estruturada documentada $0.175 / $2.17
GLM 5.3 Saída estruturada documentada; contexto de 1.048.576 tokens $0.78 / $3.46
Gemma 4 VL 26B Roda com o crédito inicial de $5; JSON só via prompt, então o validador pesa mais $0.10 / $0.22
DeepSeek V4.1 Flash Também em planos de preço fixo, como $15 por semana por sessão, uma requisição por vez por sessão $0.175 / $0.52

Os preços vêm do feed de preços da BroadNet, sincronizados 2026-11-14. Traduza as mesmas 100 strings com dois modelos e peça ao seu revisor para compará-las antes de escolher; o preço por token importa menos que o número de correções. Para milhares de chaves em muitos idiomas, processamento em lote sem uma Batch API cobre concorrência e novas tentativas.

Onde a BroadNet Inference entra

O BroadRouter é o site da própria BroadNet. A BroadNet Inference dá acesso compatível com a OpenAI aos modelos acima, então o script roda com o SDK Python da OpenAI depois de trocar a base URL e o ID do modelo; confira na referência da API os parâmetros que cada modelo aceita. Ela não tem endpoint de tradução e não publica benchmark de localização, então o validador e um revisor humano continuam sendo o seu controle de qualidade. Plataformas dedicadas de localização acrescentam memória de tradução, fluxos de revisão e capturas de tela em contexto; se você precisa disso, use uma e mantenha a checagem de CI acima como segunda linha.

Perguntas frequentes

Quantas formas de plural o árabe tem?

Seis categorias cardinais no Unicode CLDR: zero (0), one (1), two (2), few (números que terminam de 03 a 10, como 3 a 10 e 103), many (que terminam de 11 a 99) e other (100 a 102, 1000 e decimais como 0,5). Um arquivo em inglês só tem one e other.

O ChatGPT ou outro LLM consegue traduzir meu arquivo JSON de i18n para árabe?

Sim, se você controlar o formato. Envie só os valores, troque os placeholders por marcadores, peça seis formas de plural e confira o resultado no código: chaves, argumentos, tags e categorias de plural. Peça a um falante de árabe para revisar as strings novas antes do lançamento.

O que acontece se faltar uma forma de plural na tradução para árabe?

Normalmente nada quebra de forma visível. O i18next e o intl-messageformat caem na forma other, então 2 arquivos aparecem como "2 ملف" em vez do dual ملفان. Só um validador que exige as seis formas pega isso antes dos usuários.

O LLM deve escrever a sintaxe ICU MessageFormat sozinho?

Melhor não. Peça seis strings simples por mensagem de plural e monte a sintaxe ICU no código. De vez em quando os modelos perdem uma chave ou traduzem o nome do argumento, e aí um erro de parser derruba o bundle inteiro em tempo de execução.

Quais dígitos as strings de interface em árabe devem usar?

Deixe o formatador de números decidir, não a tradução. Mantenha # ou o argumento na string. No nosso teste com Node 24, o Intl.NumberFormat formatou 1234 como 1,234 para ar e como ١٬٢٣٤ para ar-EG e ar-SA, ou seja, a tag de locale define os dígitos.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity