简单来说
一家基金会用阿拉伯文写的年度报告,每段后面跟着英文译文。页面混排两种方向,词语、数字和表格都不会乱序。
成品一览
虚构的翻译基金会“达德之家”2025年年度报告,页面210 × 280 mm,字体是IBM Plex Sans Arabic和IBM Plex Sans,同一字体族的两半。报告是阿拉伯文的:从右向左排,页码印作٢、٣。每段阿拉伯文后面跟着它的英文版本,字号较小,石板灰色,从左向右排,右侧不齐;每个阿拉伯文标题在另一侧页边距配一个英文标签。阿拉伯文句子里的拉丁名称保持自己的顺序,全年的数字出现两次:一张从右读的阿拉伯文表格,一张从左读的英文表格。西班牙文版中,第二语言是西班牙文。
这道食谱解答
- 怎样在同一页混排阿拉伯文和英文的段落、数字和表格?
简短回答
// 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' };
用料
做法
#1 · 用标记的块排第二语言
代码见上文的简短回答。文档是阿拉伯文,所以除非Markdown另有说明,每个块都从右向左:在:::paragraphs围栏或标题上加{dir=ltr},就把那个块翻转过来,textAlign: 'start'让每个块靠向它开始的一侧,阿拉伯文靠右,英文靠左(文档、块与行内方向)。阿拉伯文行内的拉丁名称:ltr[Harbour Modern Classics]是一个隔离段:双向算法把它当作一个中性整体,周围的阿拉伯文词语和逗号位置不变(隔离段)。emphasis: 'italic'让英文中的Middlemarch保持斜体;无论怎样设置,引擎都不会把阿拉伯字母排成斜体。
#2 · 每个方向一张表
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' } },
];
阿拉伯文表格跟随文档方向:第一列“项目”在右边,align: 'end'让数字靠单元格左边。英文表格设了direction: 'ltr',所以第一列在左边,'end'指右边(左、右、起始与末尾的含义)。阿拉伯文数字用٠–٩输入,英文用0–9:文档的数字系统只用于引擎生成的数字,比如题注里的表格编号جدول ١-١。这也是英文表格单独用一个不计数的类型的原因,否则那里的编号会印成٢。
#3 · 一条色带上的两个标题
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) } } },
] } };
封面是一级标题的设计。标题的设计排在文本流中,随页面一起镜像,所以它的锚点说的是文字的两侧:top-left是纸面的右边,阿拉伯文名称和标题从那里起排;top-right是纸面的左边,英文标题从那里起排。设计文字采用文档的方向,所以阿拉伯文各行无需再设置;英文标题设direction: 'ltr'。色带是锚定到出血线的框,深86 mm,章首的minHeight让主任致辞排在它下面。
完整食谱
// ═══ 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
组合好的script.js可以直接运行:把它粘贴到任何页面的模块脚本中,或在CodePen上打开这道食谱。 GitHub上的食谱文件夹 ↗ (在新标签页中打开)
变化
#把英文放在前面
给不读阿拉伯文的理事会看的报告,互换两种语言的角色:英文文档,英文块不加标记,阿拉伯文块标记{dir=rtl}。
- locale: 'ar', // written out, never LANG (gotcha: arabic-locale-tag)
+ locale: 'en-us', // Arabic blocks then carry {dir=rtl}常见问题
易错点
阿拉伯文书标记为'ar',不要用LANG
食谱的版本是en和es,但阿拉伯文示例在两个版本里都是阿拉伯文:`locale: LANG`会让它从左向右排、左装订、页码印成1 2 3,并把图标注为Figure或Figura。postext 1.30起,这个标记也是文字成形所用的语言(测量、绘制和嵌入都按它进行),所以标记成英文或西班牙文时,Markazi Text这样的字体不画尖角引号(« »)和句点的阿拉伯文字形,断行的位置也随之改变。自己写出标记:'ar'(阿拉伯-印度数字,马什里克惯例),或带地区的'ar-EG'、'ar-SA';马格里布版本用欧洲数字,写'ar-MA'、'ar-DZ'或'ar-TN'。只引用阿拉伯文的拉丁文页面保留自己的locale。 从右向左的文字 →
易错点
阿拉伯文字体需要通过arabic块加载其arabic文件
Fontsource把Amiri、Noto Naskh Arabic或Scheherazade New按子集分成多个文件提供,阿拉伯字母在arabic文件里。loadFonts只获取latin(以及latin-ext),所以屏幕上的阿拉伯文来自系统字体,测量不准;fontsourceProvider交给PDF的也是这个latin文件,印出来是空框。列出kit中的arabic块,在loadFonts之后调用loadArabicFonts(FONTS, markdown),并在FONTS中列出页面用于阿拉伯文的每个字重,再给renderToPdf传fontProvider: arabicPdfProvider。 阿拉伯文字体 →
- 引擎在英文块里生成的数字,比如列表编号或题注标签,仍然使用文档的数字系统(阿拉伯文报告里是٢)。给这类表格一个不计数的资源类型,或者自己写出编号。
致谢
- 文本
- The annual report of an invented translation foundation, written in Arabic, English and Spanish for the recipe · Postext Cookbook · 原创
- 字体
- IBM Plex Sans Arabic (SIL OFL 1.1) · IBM Plex Sans (SIL OFL 1.1)


