Skip to content

i18n

Jump to bottom
zmworm edited this page May 1, 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. Inherits from the enclosing section's bidi when unset.
Word run <w:rtl/> on rPr Footnote/endnote/SDT contentRun/display-equation runs inherit the host paragraph's RTL automatically.
Word section <w:bidi/> on sectPr Section-wide reading direction. Add accepts direction=rtl.
Word table <w:bidiVisual/> on tblPr Get returns direction=rtl; round-trips through Add/Set/Get on tblPr/cell.
Word style <w:rtl/> on pPr and synthesized StyleRunProperties.rtl Round-trips through Add/Set/Get; cascades to inheriting styles via docDefaults.
Word header / footer propagates to all child runs add header --prop direction=rtl writes paragraph + run-level RTL.
Word docDefaults <w:rtl/> on docDefaults/rPrDefault/rPr docDefaults.rtl=true is the document-wide RTL override; effective.rtl resolves the chain run > pPr > pStyle > docDefaults.
Word section gutter <w:rtlGutter/> on sectPr Add/Set both accept rtlGutter=true — RTL binding-gutter flag.
Word numbering lvl <w:bidi/> on lvl pPr Add/Set/Get accept `direction=rtl
Word comment <w:rtl/> on comment runs / <w:bidi/> on pPr Round-trips through Add/Set/Get.
Word footnote / endnote inherits from host paragraph Get surfaces direction from pPr.bidi.
Word character style <w:rtl/> on rPr (not <w:bidi/> on pPr) Character-style direction maps to rPr/rtl.
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
PPT slideLayout / slideMaster inherits via txStyles per placeholder type Layout/master direction probe routes by placeholder type.
PPT speaker notes <a:pPr rtl="1"/> notes Add/Set accept direction=rtl and lang=; HTML preview honors notes direction.
PPT slide comment U+200F bidi mark prepended to body text Round-trips through Add and Set.
PPT chart <a:rtl/> stamped on chartSpace txPr, cascaded to legend, per-axis txPr, title rich text, chart-level dLbls
Excel sheet <x:sheetView rightToLeft="1"/> Canonical key is direction (matches Word/PPT). Aliases: rtl, rightToLeft, sheet.direction. Get returns direction=rtl. direction=ltr clears the attribute.
Excel cell maps to alignment.readingOrder aliased as direction / dir
Excel comment <rtl/> on each run-properties block Add/Set both accept direction=rtl.
Excel chart <a:rtl/> cascades to per-axis txPr and title rich text

direction=ltr clears the relevant attribute (or writes rtl="0" where required) instead of writing val="0". Aliases: dir, bidi, rtl. Accepted forms: rtl/ltr, true/false, 1/0, righttoleft/lefttoright — invalid input now lists all accepted forms in the error message.

Inheritance cancel: direction=ltr on a Word paragraph inside an RTL section writes <w:bidi w:val=false/> so the paragraph overrides the section/style/numbering/docDefaults inheritance. effective.direction and effective.rtl resolve the full chain run > pPr > pStyle > tblPr/bidiVisual > sectPr > docDefaults. Hyperlink runs and footnote/endnote reference runs inside RTL paragraphs surface effective.rtl=true on Get.

# 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

Per-script language tags (Word run)

Word runs accept three BCP-47 language tags mirroring the font slots — Word uses these to pick the right spell-check dictionary and to scope CJK/RTL behavior. Validator follows RFC 5646 shape with a 35-char cap; literal null is rejected; empty value clears the slot.

Sub-key OOXML attribute
lang.latin <w:lang w:val>
lang.ea (alias lang.eastasia) <w:lang w:eastAsia>
lang.cs (alias lang.complexscript) <w:lang w:bidi>

<w:lang> is emitted at the tail of the run-properties block per CT_RPr schema order, after <w:rtl/>.

# Trilingual run (English + Japanese + Arabic)
officecli set report.docx /body/p[1]/r[1] \
  --prop lang.latin=en-US \
  --prop lang.ea=ja-JP \
  --prop lang.cs=ar-SA

Document-level locale is exposed on get of / as locale=..., sourced from themeFontLang. BlankDocCreator stamps themeFontLang from the --locale flag at create time.

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"/>.
  • PPT HTML preview renders speaker notes with direction propagation.

Query selector

query accepts paragraph-level direction predicates and the rtl alias:

officecli query report.docx 'p[direction=rtl]'
officecli query report.docx 'p[rtl]'

set find=... --prop direction=... cascades the change to all matched runs and the paragraph mark.

See Also

Based on OfficeCLI v1.0.68

Clone this wiki locally