OfficeCLI Support for Word i18n and RTL Languages: Complete Implementation Guide

OfficeCLI provides native, built-in support for Word document internationalization (i18n) and right-to-left (RTL) layouts through a multi-layer cascade system that handles document defaults, style inheritance, paragraph properties, and run-level direction flags.

OfficeCLI is an open-source command-line tool for creating and manipulating Word documents without Microsoft Word. Its Word i18n and RTL support is engineered directly into the core engine, enabling AI agents and automation scripts to reliably produce documents in Arabic, Hebrew, Persian, and any other RTL script. This article examines the source code architecture that makes this possible.

How RTL Direction Cascades Through Document Layers

OfficeCLI implements a five-layer inheritance model for RTL handling. Each layer can set direction, with downstream layers gracefully overriding upstream values while preserving provenance information.

Document-Wide Defaults (docDefaults)

The foundation sits in WordHandler.Set.DocDefaults.cs, which persists global RTL settings to the <w:bidi> element in the document's default properties.

officecli create report.docx --locale ar-SA

This single command writes the BCP-47 language tag (ar-SA) and sets docDefaults.rtl=true automatically. In the source, lines 116-124 handle the mapping between the rtl/direction CLI keys and the internal docdefaults.rtl boolean.

Style-Level Inheritance

WordHandler.StyleList.cs (lines 98-106) lifts <w:bidi> from paragraph style properties into an effective run-level RightToLeftText flag. This guarantees that text runs inheriting a style receive the correct direction without explicit markup.

The style resolution engine merges:

• Parent style definitions
• Table style overrides
• Direct formatting instructions

Paragraph-Level Resolution

The ResolveEffectiveParagraphStyleProperties method (lines 885-938) computes final direction by merging:

1. Document defaults
2. Section settings
3. Table cell properties
4. Style definitions
5. Direct paragraph properties (<w:pPr><w:bidi>)

The method emits both effective.direction ("rtl" or "ltr") and effective.rtl (boolean) for downstream consumers.

Run-Level Handling

Individual runs may explicitly declare RTL via <w:rtl>. When absent, ResolveEffectiveRunPropertiesCore (lines 77-88) inherits the paragraph's effective direction and records provenance in effective.rtl—indicating whether the value came from explicit run markup, paragraph context, or style cascade.

Selector and Query Interface

The CLI exposes RTL as a first-class selector in WordHandler.Selector.cs (lines 207-214):

officecli query report.docx "paragraph[rtl=true]" --json
officecli query report.docx "run[rtl=true]" --json

The selector maps to the run's RightToLeftText value, returning matches regardless of where the direction originated in the cascade.

Setting RTL Properties: CLI Commands

Set Paragraph Direction Manually

officecli set report.docx '/body/p[1]' --prop direction=rtl

This updates <w:pPr><w:bidi/> on the target paragraph. Subsequent get or query operations show effective.rtl=true for all child runs.

Set RTL via Boolean Aliases

The set command parser accepts multiple forms:

• rtl
• righttoleft
• true
• 1

officecli set report.docx '/body/p[2]' --prop rtl=true

Verify Effective Direction

officecli get report.docx '/body/p[1]/r[1]' --json

Expected output:

{
  "tag": "run",
  "path": "/body/p[1]/r[1]",
  "attributes": {
    "text": "مرحبا",
    "effective.rtl": true,
    "effective.direction": "rtl"
  }
}

Per-Script Font Slots and Language Tags

OfficeCLI exposes complete support for complex script font slots and BCP-47 language tags through the same property system.

Mixed-Script Font Configuration

officecli set report.docx '/body/p[2]/r[1]' \
  --prop font.eastAsia=宋体 \
  --prop font.cs=Times\ New\ Roman \
  --prop font.hAnsi=Calibri \
  --prop font.ascii=Calibri

The merge logic in MergeRunProperties (WordHandler.StyleList.cs, lines 93-106) respects per-slot inheritance rules, ensuring Arabic text in a CJK-context document receives correct shaping.

Language Tag Management

Slot	CLI Key	Typical Use
Latin languages	lang.latin	English, French, German
East Asian	lang.ea	Chinese, Japanese, Korean
Complex scripts	lang.cs	Arabic, Hebrew, Thai, Devanagari

officecli set report.docx '/body/p[1]' --prop lang.cs=ar-SA

RTL-Specific Document Features

Beyond basic direction, OfficeCLI handles RTL-specific layout features:

• rtlGutter: Gutter positioning for bound documents
• pgBorders: Page border ordering that respects reading direction
• Locale-aware numbering: Arabic-Indic numerals, Thai digits, CJK numbering systems

These integrate with the same cascade engine, reading from section properties and document defaults.

Architecture: Three-Layer Model

OfficeCLI's RTL implementation follows its documented Read → DOM → Raw XML pattern:

1. Read layer parses OpenXML into an object model
2. DOM layer computes effective properties (including RTL resolution)
3. Raw XML layer serializes modifications back to standard WordprocessingML

RTL handling executes at the DOM layer, ensuring both high-level (view, get, query) and low-level (raw-set) commands observe consistent direction information.

Key Source Files for Word i18n and RTL Support

File	Responsibility	Critical Lines
WordHandler.Set.DocDefaults.cs	Document-wide RTL defaults	116-124 (bidi handling)
WordHandler.StyleList.cs	Cascade engine and provenance	77-88 (run resolution), 885-938 (paragraph resolution)
WordHandler.Selector.cs	RTL selector implementation	207-214 (rtl key mapping)
WordHandler.Set.cs	CLI argument parsing and validation	(key normalization)

Summary

• OfficeCLI Word i18n and RTL support is native to the engine, not a wrapper around Microsoft Word
• Five-layer cascade (docDefaults → section → table → style → paragraph → run) computes effective direction
• Provenance tracking via effective.rtl and effective.direction attributes shows where values originated
• Flexible CLI interface accepts rtl, direction=rtl, righttoleft, and boolean aliases
• Per-script font slots (font.eastAsia, font.cs, font.hAnsi) handle mixed-script documents
• BCP-47 language tags exposed as lang.latin, lang.ea, lang.cs

Frequently Asked Questions

Does OfficeCLI require Microsoft Word for RTL document creation?

No. OfficeCLI operates independently as a headless engine. All RTL handling—including complex script font shaping, bidirectional layout calculation, and OpenXML serialization—is implemented directly in the C# source, primarily in WordHandler.StyleList.cs and related handlers.

How does OfficeCLI handle mixed RTL and LTR paragraphs in one document?

Each paragraph and run maintains its own effective direction through the cascade system. The effective.direction attribute exposed in JSON output indicates the computed direction for any element. Query selectors like paragraph[rtl=true] return only RTL elements, allowing precise manipulation of mixed-direction documents.

Can I convert an existing LTR document to RTL using OfficeCLI?

Yes. Use the document defaults handler to set global RTL, then optionally adjust specific paragraphs:

officecli set existing.docx '/' --prop docdefaults.rtl=true
officecli set existing.docx '/body/p[1]' --prop direction=rtl

The first command modifies <w:settings>, while the second adds explicit <w:bidi> to paragraph properties.

What font slots does OfficeCLI support for international scripts?

Four font slots map to OpenXML's w:rFonts element: font.ascii (basic Latin), font.hAnsi (extended Latin/European), font.eastAsia (CJK), and font.cs (complex scripts including Arabic, Hebrew, Thai). The MergeRunProperties method in WordHandler.StyleList.cs handles inheritance between these slots according to the WordprocessingML specification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}