Translate a JSON i18n File into Arabic

What Arabic changes in your strings

A string that needs two forms in English often needs six in Arabic. Arabic plurals distinguish zero, one, two, a small number (3 to 10), a large number (11 to 99) and everything else (100, 101…). A source ICU message such as {count, plural, one {# message} other {# messages}} becomes:

{count, plural, zero {لا توجد رسائل} one {رسالة واحدة} two {رسالتان} few {# رسائل} many {# رسالة} other {# رسالة}}

The dual (رسالتان, ‘two messages’) is a full grammatical form written without a digit, which is why the two category cannot fall back to other.

Other differences affect values directly:

• Gender: verbs and adjectives agree with the person being addressed. ‘You are signed in’ is أنتَ متصل for a man and أنتِ متصلة for a woman. If your app knows the user's gender, a {gender, select, female {…} other {…}} message avoids defaulting to the masculine.
• Punctuation: the Arabic comma ،, semicolon ؛ and question mark ؟ replace the Latin ones. ‘Delete this file?’ becomes حذف هذا الملف؟.
• No capitals: Arabic script has no case. text-transform: uppercase on a button does nothing, and letter-spacing breaks the joins between letters.
• Register: interfaces are usually written in Modern Standard Arabic, understood across the Arabic-speaking world. If your audience expects something else, check the free sample.

Right-to-left text, placeholders and digits in JSON

Opened in a code editor, an Arabic file often looks scrambled: a value mixing Arabic with a Latin placeholder, such as "deleted": "تم حذف {count} ملفات", may show the brace somewhere unexpected. That is the editor's bidirectional rendering, not a fault in the file. Do not move placeholders by hand to ‘fix’ the order: the logical character order is correct, and that is what your library reads.

Placeholder position also genuinely changes: Arabic builds the sentence differently, so {name}, at the start of an English sentence, may end up in the middle or at the end. What matters, and what Manuce checks, is that each placeholder appears as many times as in the source.

For digits, Arabic uses either 0-9 (Western Arabic numerals, more common in the Maghreb) or ٠-٩ (Eastern Arabic numerals, more widespread in the Levant and the Gulf). Manuce does not translate numbers: a hard-coded 42 in a value stays 42. The choice belongs in code: pass numbers as variables and format them with the right locale (ar-EG, ar-MA…) through Intl.NumberFormat or your library's formatter.

Direction is not stored in JSON either: your app must set dir="rtl" and lang="ar", and use logical CSS properties (margin-inline-start rather than margin-left) so the layout mirrors.

What Manuce returns, and what it does not do

You upload a flat or nested JSON file, with or without string arrays, as produced for i18next, react-intl, vue-i18n, next-intl or ngx-translate. You get back:

• the same file: indentation, key order, quotes, comments, line endings, encoding and BOM preserved; only the values are now in Arabic;
• untouched keys: "checkout.button.pay" stays "checkout.button.pay";
• checked placeholders: {name}, {{count}}, %s and ICU plural and select messages are compared with the source string by string;
• completed ICU plurals: zero, two, few and many are added where the source only had one and other;
• a report: strings translated, strings left as they were, and why. If a translated value still differs from the source in placeholders or tags, the source value is kept and the report says so.

Left as they are: empty values, URLs, email addresses, numbers, colours, date formats, identifiers and anything marked as non-translatable.

What Manuce does not do: it does not create keys. If your project handles plurals with i18next key suffixes (items_one, items_other), the returned file keeps exactly those keys, with no _zero, _two, _few or _many. For Arabic, ICU messages are the safer route. Nor does Manuce set interface direction, fonts or digit style. Arabic carries a ×1.6 coefficient on the per-word rate, counted on value words only.

Preparing the file and testing the result

A few precautions before uploading, and a few tests before release:

• Encoding: save the source as UTF-8; encoding is preserved as is, and Arabic requires a Unicode encoding.
• No concatenation: t("you_have") + n + t("messages") cannot produce correct Arabic, because the noun changes form with the number. A single ICU string with {count} solves it.
• Terms to keep: product names, brands, Latin-script acronyms. Mark them non-translatable where your format allows, then check the free sample and the translation.
• Plurals: render every plural message with 0, 1, 2, 3, 11 and 100; these six numbers cover all six Arabic categories.
• Fonts and height: Arabic has marks above and below the line; make sure your font includes Arabic glyphs and that fixed-height buttons do not clip text.
• Report: deal with every string left in the source language before shipping.

In practice

1. Upload your UTF-8 JSON file: the quote appears at once, based on value words.
2. Choose a level and read the free sample translated into Arabic.
3. Pay, then download the Arabic JSON file and its report.
4. Read the report and test plurals with 0, 1, 2, 3, 11 and 100 in a right-to-left layout.