How OfficeCLI Handles i18n and RTL Documents: Arabic, Hebrew, and Complex Script Support

OfficeCLI provides comprehensive internationalization (i18n) and right-to-left (RTL) support for Word, Excel, and PowerPoint by implementing BCP-47 language tagging, complex-script font slots, and cascading direction properties that automatically propagate from document defaults to individual text runs.

The iOfficeAI/OfficeCLI repository offers first-class support for RTL documents through a layered architecture that mirrors native Office application behavior. Understanding how OfficeCLI handles i18n and RTL documents ensures your automated document generation respects script-specific requirements for typography, layout, and reading order across Arabic, Hebrew, and other complex scripts.

Language Tagging with BCP-47 Standards

Every textual element in OfficeCLI can be assigned a lang property accepting a BCP-47 tag (e.g., ar-SA, he-IL). According to the source code in src/officecli/Handlers/WordHandler.cs, this tag is internally stored within the OpenXML <w:lang> element, enabling Word to apply appropriate script-specific fonts and hyphenation rules automatically.

Complex Script Font Slots

Font properties in OfficeCLI are split per script type: latin, ea (East Asian), and cs (complex script). When processing Arabic or Hebrew text, the CLI utilizes the cs slot, which is essential for proper glyph shaping and rendering across all generated documents.

Configuring RTL Direction Across Formats

The direction=rtl flag can be applied to paragraphs, table cells, textboxes, shapes, and document defaults. This property cascades: parent elements propagate RTL directionality to children unless explicitly overridden.

Word Documents

In src/officecli/Handlers/WordHandler.cs, the direction=rtl property translates to the <w:bidi> element in OpenXML. This marking controls paragraph direction and interacts with the RTL gutter feature (rtlGutter), which adds appropriate right-hand gutters for RTL reading order in section properties. Styles and docDefaults nodes also accept direction=rtl, ensuring newly added runs inherit RTL direction automatically.

Excel Workbooks

The src/officecli/Handlers/ExcelHandler.cs file implements RTL through the direction=rtl property on sheet views, corresponding to the <x:rtl> element. This mirrors Excel's "Right-to-Left" UI option, flipping column order and ensuring formulas and references respect the RTL layout.

PowerPoint Presentations

For PowerPoint shapes and textboxes, OfficeCLI utilizes src/officecli/Handlers/Word/WordHandler.View.cs to parse and write RTL flags. The direction=rtl property maps to the <a:rtl> element, properly handling text direction within shapes while respecting complex-script font assignments.

Automatic RTL Document Creation

The src/officecli/CommandBuilder.cs file processes the global --locale flag to inject RTL settings automatically. When creating documents with officecli create --locale ar-SA (or any RTL BCP-47 tag), the CLI automatically sets direction=rtl and lang properties throughout the document structure, including locale-aware page numbering adaptations for Arabic, Hindi, and Thai numerals.

Practical Usage Examples

Generate RTL-ready documents and apply directional properties using the following commands:

# Create a new Arabic Word document with automatic RTL layout

officecli create --type word --locale ar-SA myArabicDoc.docx

# Add an RTL paragraph to an existing document

officecli set --prop "text=مرحبا بالعالم" --prop direction=rtl myArabicDoc.docx

# Set RTL direction on an Excel sheet view

officecli set --sheet Sheet1 --prop direction=rtl myWorkbook.xlsx

# Apply RTL direction to a PowerPoint textbox with complex-script font

officecli set --slide 2 --shape textbox1 \
    --prop "text=שלום עולם" \
    --prop direction=rtl \
    --prop font.cs=Calibri\ (Arabic)

Implementation Summary

Key source files handling i18n and RTL logic include:

• src/officecli/Handlers/WordHandler.cs – Core logic for lang properties, <w:bidi> elements, and complex-script font slots
• src/officecli/Handlers/ExcelHandler.cs – Sheet view RTL implementation using <x:rtl>
• src/officecli/Handlers/Word/WordHandler.View.cs – PowerPoint shape RTL handling via <a:rtl>
• src/officecli/CommandBuilder.cs – CLI locale parsing and automatic RTL injection during document creation

Summary

• OfficeCLI uses BCP-47 language tags stored in <w:lang> elements to identify document languages
• Complex-script font slots (cs) ensure proper Arabic and Hebrew glyph rendering
• Cascading direction properties allow RTL settings to propagate from docDefaults and styles to individual elements
• The direction=rtl flag maps to format-specific OpenXML: <w:bidi> (Word), <x:rtl> (Excel), and <a:rtl> (PowerPoint)
• Automatic RTL generation occurs when using officecli create --locale with any RTL BCP-47 tag

Frequently Asked Questions

How does OfficeCLI detect RTL languages automatically?

When you specify an RTL locale such as ar-SA or he-IL via the --locale flag during document creation, the CommandBuilder.cs logic automatically injects direction=rtl and appropriate lang attributes throughout the document structure. This eliminates manual configuration requirements and ensures proper complex-script handling from the first paragraph.

What is the difference between CS fonts and regular fonts in OfficeCLI?

CS (complex script) fonts are specifically designated for Arabic, Hebrew, and other scripts requiring contextual glyph shaping. OfficeCLI treats the font.cs property separately from font.latin, ensuring that RTL text uses the appropriate typographic rules stored in the OpenXML <w:rFonts> element's CS slot rather than standard Latin character spacing.

Can I mix RTL and LTR content in the same OfficeCLI document?

Yes. While you can set default RTL directionality at the document or style level, individual paragraphs, runs, or cells can override this with direction=ltr. The cascading architecture ensures that explicit directional settings on child elements take precedence over inherited parent settings, allowing bidirectional content within a single file.

Does OfficeCLI handle RTL page numbering for Arabic documents?

Yes. When creating documents with RTL locale flags, OfficeCLI automatically adapts page-number formatting to use Arabic-Indic numerals and adjusts section-level properties like rtlGutter to maintain proper binding margins for right-to-left reading order, as implemented in the WordHandler.cs section handling logic.

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