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

> Discover how OfficeCLI supports i18n and RTL documents like Arabic and Hebrew with BCP-47 tagging, font slots, and cascading direction properties for seamless multilingual document handling.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-07-25

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs) – Core logic for `lang` properties, `<w:bidi>` elements, and complex-script font slots
- [`src/officecli/Handlers/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/ExcelHandler.cs) – Sheet view RTL implementation using `<x:rtl>`
- [`src/officecli/Handlers/Word/WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.View.cs) – PowerPoint shape RTL handling via `<a:rtl>`
- [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.