Skip to content

i18n

Jump to bottom
zmworm edited this page Apr 29, 2026 · 3 revisions

Internationalization (i18n & RTL)

OfficeCLI supports multilingual content and right-to-left layouts across Word, Excel, and PowerPoint. This page consolidates the i18n surface — full property listings live on the per-element pages.

Per-script font slots

OOXML stores up to four font typefaces per run, one per script class. OfficeCLI exposes them as dotted sub-keys. The bare font= property still works as a shortcut that writes the Latin slot.

Sub-key OOXML slot Used for
font.latin rFonts/@ascii + @hAnsi ASCII / Western text
font.ea (aliases: font.eastasia, font.eastasian) rFonts/@eastAsia Chinese / Japanese / Korean
font.cs (aliases: font.complexscript, font.complex) rFonts/@cs Arabic / Hebrew / Thai

Available on Word run/paragraph (add, set, get), PPT shape/textbox/table-cell, Word header/footer Set.

# Mixed-script paragraph
officecli set report.docx /body/p[1] \
  --prop font.latin=Calibri \
  --prop font.ea=SimSun \
  --prop font.cs="Arabic Typesetting"

# PPT shape
officecli set deck.pptx /slide[1]/shape[2] \
  --prop font.ea=メイリオ

Get readback emits font.latin / font.ea / font.cs per OOXML schema; the bare font key is emitted only when all populated slots agree on a single typeface.

Complex-script bold / italic / size

Arabic and Hebrew text needs separate <w:bCs/> / <w:iCs/> / <w:szCs/> toggles — without them, bold/italic/size set on the regular Latin slot is ignored by Word.

Property OOXML Notes
bold.cs (aliases: font.bold.cs, boldcs) <w:bCs/> Complex-script bold
italic.cs (aliases: font.italic.cs, italiccs) <w:iCs/> Complex-script italic
size.cs (aliases: font.size.cs, sizecs) <w:szCs/> Complex-script size (pt) 
# Make Arabic text bold and 16pt — needs the .cs flags to render correctly
officecli set report.docx /body/p[1] \
  --prop direction=rtl \
  --prop font.cs="Arabic Typesetting" \
  --prop bold=true --prop bold.cs=true \
  --prop size=16 --prop size.cs=16

RTL direction

A single direction property cascades to the right OOXML element by scope:

Scope OOXML written Notes
Word paragraph <w:bidi/> on pPr + <w:rtl/> on each child run + paragraph mark Single prop produces a fully Arabic-correct paragraph
Word run <w:rtl/> on rPr
Word section <w:bidi/> on sectPr Section-wide reading direction
PPT shape / textbox <a:pPr rtl="1"/> on every paragraph; <a:bodyPr rtlCol="1"/> on shape
PPT table cell <a:bodyPr rtlCol="1"/> on cell
Excel cell maps to alignment.readingOrder aliased as direction / dir

direction=ltr clears the relevant attribute (or writes rtl="0" where required). Aliases: dir, bidi.

# Word paragraph — fully RTL
officecli set report.docx /body/p[1] --prop direction=rtl

# PPT textbox — RTL column flow
officecli set deck.pptx /slide[2]/shape[1] --prop direction=rtl

# Excel cell — RTL reading order
officecli set sheet.xlsx /Sheet1/A1 --prop direction=rtl

Locale-aware page numbering

Word section pageNumFmt accepts the full ECMA-376 enum, including non-Latin numerals:

decimal, upperRoman, lowerRoman, upperLetter, lowerLetter, ordinal, cardinalText, ordinalText, hex, chicago, ideographDigital, japaneseCounting, japaneseDigitalTenThousand (alias: japanesedigitaltenthousand), japaneseLegal, aiueo, iroha, decimalEnclosedCircle, decimalEnclosedFullstop, decimalEnclosedParen, decimalFullWidth, decimalFullWidth2, decimalHalfWidth, decimalZero, bullet, ganada, chosung, koreanCounting, koreanDigital, koreanDigital2, koreanLegal, taiwaneseCounting, taiwaneseCountingThousand, taiwaneseDigital, chineseCounting, chineseCountingThousand, chineseLegalSimplified, hebrew1, hebrew2, arabicAlpha, arabicAbjad, hindiVowels, hindiConsonants, hindiNumbers, hindiCounting, thaiLetters, thaiNumbers, thaiCounting, bahtText, dollarText, vietnameseCounting, numberInDash, russianLower, russianUpper.

# Hindi numerals (٠١٢٣)
officecli set report.docx /section[1] --prop pageNumFmt=hindiNumbers

# Japanese counting
officecli set report.docx /section[1] --prop pageNumFmt=japaneseCounting

Default fonts

Blank Word documents no longer hardcode Chinese (宋体) / Times New Roman fallbacks in docDefaults. A fresh document renders with the host application's UI-locale default fonts — matches Apache POI / LibreOffice convention. To pin specific fonts, set them explicitly:

officecli set report.docx / \
  --prop docDefaults.font.latin=Calibri \
  --prop docDefaults.font.ea=SimSun \
  --prop docDefaults.font.cs="Arabic Typesetting"

HTML preview

  • Word HTML preview emits document-level <html lang> and <html dir="rtl"> for non-en / RTL locales.
  • Word renderer reads ComplexScript font for runs that have <w:rtl/> set.
  • PPT HTML preview honors paragraph rtl="1" and <a:bodyPr rtlCol="1"/>.

See Also

Based on OfficeCLI v1.0.64

Clone this wiki locally