In short
A foundation's annual report written in Arabic, with each paragraph followed by its English version. The page mixes the two directions without the words, numbers or tables getting out of order.
What you'll build
The 2025 annual report of an imaginary translation foundation, Dar al-Dad, on an A4-wide 210 × 280 mm page in IBM Plex Sans Arabic and IBM Plex Sans, the two halves of one type family. The report is Arabic: it runs right to left and numbers its pages ٢, ٣. Each Arabic paragraph is followed by its English version, smaller and in slate grey, set left to right and ragged on the right; each Arabic heading carries an English label at the other margin. Latin names inside Arabic sentences keep their own order, and the year's figures appear twice, in an Arabic table that reads from the right and an English one that reads from the left. In the Spanish edition the second language is Spanish.
This recipe answers
- How do I mix Arabic and English paragraphs, numbers and tables on one page?
The short answer
// The document is Arabic (locale 'ar'): right to left, Arabic-Indic digits. A block in the
// other language says so in the Markdown, and its style gives it its own voice:
// :::paragraphs{style="second" dir=ltr} a paragraph or several, set left to right
// ### Director's note {style="second-head" dir=ltr}
// Inside an Arabic sentence, a Latin name is an isolate, :ltr[Penguin Classics]{lang=en}, so
// the words around it keep their order. 'start' and 'end' follow each block's own direction.
const second = { id: 'second', fontFamily: LATIN, fontSize: pt(9.5), lineHeight: pt(14),
color: col('slate'), textAlign: 'start', firstLineIndent: pt(0) };
const bodyText = { fontFamily: ARABIC, fontSize: pt(11), lineHeight: pt(LEAD),
color: col('ink'), boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
textAlign: 'start', // ragged: the right edge for Arabic, the left for an English block
firstLineIndent: pt(0), paragraphSpacing: true,
// The Arabic is never slanted; italics stay for the titles in the Latin blocks.
emphasis: 'italic' };
One Arabic document, its English blocks marked {dir=ltr}
Ingredients
- Features
- Paragraphs in the other directionRuns in the other directionRight-to-left textArabic fontsArabic as the document languageDigits of the generated numbersTables from dataTable styleNamed table stylesCaption styleCustom resource typesDesigned openersHeading stylesParagraph stylesSemantic colour palettePDF export
- Also uses
- Heading attributesFigures exactly hereFigure and Table in your languageHeads by page roleFonts embedded in the PDFBooks bound on the right
- Type
- IBM Plex Sans Arabic, IBM Plex Sans (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · The second language as marked blocks
The code is the short answer above. The document is Arabic, so every block is right to left until the Markdown says otherwise: {dir=ltr} on a :::paragraphs fence or on a heading turns that block around, and textAlign: 'start' sends each block to the side it starts on, right for Arabic and left for English (Document, block and inline direction). A Latin name inside an Arabic line, :ltr[Harbour Modern Classics], is an isolate: the bidi algorithm treats it as one neutral piece, so the Arabic words and the comma around it keep their places (Isolates). emphasis: 'italic' keeps Middlemarch in italics in the English text; the engine never slants an Arabic letter, whatever the setting.
#2 · One table for each direction
const cell = (content, extra = {}) => ({ content, ...extra });
const tableOf = (head, rows) => ({ headerRowCount: 1, columnWidths: [46, 18, 18, 18],
rows: [head.map((h, i) => cell(h, { isHeader: true, align: i ? 'end' : 'start' })),
...rows.map((r) => r.map((c, i) => cell(c, { align: i ? 'end' : 'start' })))] });
const FIGURES = [ // programme, 2024, 2025, change: the Foundation's own counts
['كتب مترجمة إلى العربية', 'Books translated into Arabic', 28, 34],
['كتب مترجمة من العربية', 'Books translated from Arabic', 9, 14],
['منح للمترجمين', 'Translator grants', 41, 52],
['ورشات تدريب', 'Training workshops', 12, 18],
['مشاركون في الورشات', 'Workshop participants', 310, 466]];
const SPANISH = { 'Books translated into Arabic': 'Libros traducidos al árabe',
'Books translated from Arabic': 'Libros traducidos del árabe',
'Translator grants': 'Becas para traductores', 'Training workshops': 'Talleres de formación',
'Workshop participants': 'Participantes en los talleres' };
const change = (a, b) => `${b > a ? '+' : ''}${Math.round((100 * (b - a)) / a)}%`;
const AR = (n) => String(n).replace(/\d/g, (d) => '٠١٢٣٤٥٦٧٨٩'[d]); // the author's ٠–٩
const tableAr = tableOf(['البرنامج', '٢٠٢٤', '٢٠٢٥', 'التغيّر'], FIGURES.map(([ar, , a, b]) =>
[ar, AR(a), AR(b), AR(change(a, b)).replaceAll('%', '٪')]));
const tableEn = tableOf(t({ en: ['Programme', '2024', '2025', 'Change'],
es: ['Programa', '2024', '2025', 'Cambio'] }), FIGURES.map(([, en, a, b]) =>
[t({ en, es: SPANISH[en] }), String(a), String(b), change(a, b)]));
// The English table has a heading of its own and no number: a generated number would print in
// the document's digits, ٢, inside the English block.
const resourceTypes = [...defaultResourceTypes('ar'), { id: 'data', name: 'Data',
shortLabel: 'Data', captionPrefix: '', numberingTemplate: '', resetOn: 'never',
counterFormat: 'decimal' }];
const resources = [
{ id: 'figures-ar', typeId: 'table', kind: 'table', createdAt: 0, updatedAt: 0,
table: { model: tableAr }, placement: { position: 'here' },
caption: 'أرقام البرامج في عامي ٢٠٢٤ و٢٠٢٥' },
{ id: 'figures-en', typeId: 'data', kind: 'table', createdAt: 0, updatedAt: 0,
table: { model: tableEn, direction: 'ltr', styleId: 'second' },
placement: { position: 'here' } },
];
The Arabic table runs with the document: its first column, the programme, is on the right, and align: 'end' puts the numbers against the left edge of their cells. The English table sets direction: 'ltr', so its first column is on the left and 'end' means the right edge (What left, right, start and end mean). The Arabic figures are typed in ٠–٩, the English ones in 0–9: the document's digits apply only to the numbers the engine writes, such as the table's number in its caption, جدول ١-١. That is also why the English table has a type of its own with no counter, since a number there would print as ٢.
#3 · Two titles on one band
const band = { enabled: true, minHeight: mm(70), slot: { elements: [
{ kind: 'box', id: 'band', style: { backgroundColor: col('teal') },
placement: { anchor: { to: 'bleed', edge: 'top-left' },
size: { width: mm(216), height: mm(86) } } },
// A heading's design is set in the flow and mirrored with the page: 'left' is the side the
// text starts on, the sheet's right in this book, and 'right' its left. Design text takes
// the document's direction; the English title says 'ltr' and starts from the sheet's left.
{ kind: 'text', id: 'org', content: '{attr.org}', fontFamily: ARABIC, fontSize: pt(13),
fontWeight: 600, color: col('tint'), align: 'start',
placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: mm(SIDE), y: mm(18) } } },
{ kind: 'text', id: 'title', content: '{titleText}', fontFamily: ARABIC, fontSize: pt(50),
fontWeight: 700, lineHeight: 1.15, color: col('paper'), align: 'start',
placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: mm(SIDE), y: mm(30) } } },
{ kind: 'text', id: 'title-2', content: '{attr.second}', direction: 'ltr', fontFamily: LATIN,
fontSize: pt(18), fontWeight: 300, color: col('tint'), align: 'start',
placement: { anchor: { to: 'page', edge: 'top-right' }, offset: { x: mm(-SIDE), y: mm(66) } } },
] } };
The cover is the first-level heading's design. A heading's design is set in the flow and mirrored with the page, so its anchors name the sides of the text: top-left is the sheet's right, where the Arabic name and title start, and top-right its left, where the English title starts. Design text takes the document's direction, so the Arabic lines need nothing more; the English title sets direction: 'ltr'. The band is a box anchored to the bleed, 86 mm deep, and the opener's minHeight brings the director's note under it.
The whole recipe
// ═══ Postext Cookbook · Nº 106 · A bilingual Arabic–English report ═══════════════════
// https://postext.dev/en/cookbook/bilingual-arabic-english-report
// Code: MIT · Text: original Arabic, English and Spanish prose (CC BY 4.0) · Pictures: none
// Fonts: IBM Plex Sans Arabic, IBM Plex Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocument, withLoadedFonts, renderPageToCanvas, defaultResourceTypes,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
const LANG = 'en'; // @lang: the second language of the report: English, or Spanish in 'es'
const RECIPE = 'bilingual-arabic-english-report';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a deep teal for the Arabic, a slate for the second language
const palette = {
ink: '#1b1f22', // the Arabic text
teal: '#0e5a5c', // the accent: the cover band, headings, table heads
slate: '#45535c', // the English (or Spanish) text: a voice of its own, a step lighter
tint: '#e4eeec', // the second language's panels
rule: '#b9c4c2', // hairlines
paper: '#ffffff',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.teal })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [ARABIC, LATIN] = ['IBM Plex Sans Arabic', 'IBM Plex Sans']; // one superfamily
const LEAD = 18; // pt: the Arabic leading
const SIDE = 20; // mm: the side margins
// #region answer: one Arabic document, its English blocks marked {dir=ltr}
// The document is Arabic (locale 'ar'): right to left, Arabic-Indic digits. A block in the
// other language says so in the Markdown, and its style gives it its own voice:
// :::paragraphs{style="second" dir=ltr} a paragraph or several, set left to right
// ### Director's note {style="second-head" dir=ltr}
// Inside an Arabic sentence, a Latin name is an isolate, :ltr[Penguin Classics]{lang=en}, so
// the words around it keep their order. 'start' and 'end' follow each block's own direction.
const second = { id: 'second', fontFamily: LATIN, fontSize: pt(9.5), lineHeight: pt(14),
color: col('slate'), textAlign: 'start', firstLineIndent: pt(0) };
const bodyText = { fontFamily: ARABIC, fontSize: pt(11), lineHeight: pt(LEAD),
color: col('ink'), boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
textAlign: 'start', // ragged: the right edge for Arabic, the left for an English block
firstLineIndent: pt(0), paragraphSpacing: true,
// The Arabic is never slanted; italics stay for the titles in the Latin blocks.
emphasis: 'italic' };
// #endregion
// #region tables: the Arabic table runs with the page; the English one runs left to right
The composed script.js runs as it is: paste it into any page’s module script, or open the recipe on CodePen. Recipe folder on GitHub ↗ (opens in a new tab)
Variations
#Put the English first
A report for a board that does not read Arabic swaps the roles: an English document, its blocks unmarked, and the Arabic ones marked {dir=rtl}.
- locale: 'ar', // written out, never LANG (gotcha: arabic-locale-tag)
+ locale: 'en-us', // Arabic blocks then carry {dir=rtl}Pitfalls
Pitfall
Tag an Arabic book 'ar', not with LANG
A recipe's editions are en and es, but an Arabic sample is Arabic in both: `locale: LANG` would set it left to right, bind it on the left, number its pages 1 2 3 and caption its figures Figure or Figura. From postext 1.30 the tag is also the language the text is shaped in (measured, painted and embedded), so under an English or Spanish tag a face such as Markazi Text does not draw the Arabic forms of its guillemets and stops, and the lines break elsewhere. Write the tag yourself: 'ar' (Arabic-Indic digits, the Mashriq convention), a region such as 'ar-EG' or 'ar-SA', or 'ar-MA', 'ar-DZ' or 'ar-TN' for a Maghreb edition with European digits. A Latin page that only quotes Arabic keeps its own locale. Right-to-left text →
Pitfall
Arabic faces need their arabic file, through the arabic block
Fontsource serves Amiri, Noto Naskh Arabic or Scheherazade New as one file per subset, and the Arabic letters are in the arabic file. loadFonts fetches only latin (and latin-ext), so on screen the Arabic comes from a system face and measures wrong, and fontsourceProvider hands the PDF that latin file, which prints empty boxes. List the arabic kit block, call loadArabicFonts(FONTS, markdown) after loadFonts, with every weight the pages set in Arabic listed in FONTS, and give renderToPdf fontProvider: arabicPdfProvider. Arabic fonts →
- A number the engine writes inside an English block, a list number or a caption label, still takes the document's digits (٢ in an Arabic report). Give such tables a resource type without a counter, or write the numbers yourself.
Credits
- Recipe
- Ignacio Ferro
- Text
- The annual report of an invented translation foundation, written in Arabic, English and Spanish for the recipe · Postext Cookbook · original
- Fonts
- IBM Plex Sans Arabic (SIL OFL 1.1) · IBM Plex Sans (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


