-
Notifications
You must be signed in to change notification settings - Fork 528
i18n
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.
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.
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
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
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
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.
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"
- Word HTML preview emits document-level
<html lang>and<html dir="rtl">for non-en / RTL locales. - Word renderer reads
ComplexScriptfont 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 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.
- Word run set — full font/direction property tables
- Word paragraph set
- Word section set — pageNumFmt full enum
- PPT shape set — RTL on textbox / paragraph / cell
- Excel cell set — readingOrder
Based on OfficeCLI v1.0.68