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

> Implement OfficeCLI support for Word i18n and RTL languages effortlessly. This guide details the multi-layer cascade system for global document compatibility.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.DocDefaults.cs), which persists global RTL settings to the `<w:bidi>` element in the document's default properties.

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Selector.cs) (lines 207-214):

```bash
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

```bash
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`

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

```

### Verify Effective Direction

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

```

Expected output:

```json
{
  "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

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/lang.cs) | Arabic, Hebrew, Thai, Devanagari |

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.DocDefaults.cs) | Document-wide RTL defaults | 116-124 (bidi handling) |
| [`WordHandler.StyleList.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.StyleList.cs) | Cascade engine and provenance | 77-88 (run resolution), 885-938 (paragraph resolution) |
| [`WordHandler.Selector.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Selector.cs) | RTL selector implementation | 207-214 (rtl key mapping) |
| [`WordHandler.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/font.cs), `font.hAnsi`) handle mixed-script documents
- **BCP-47 language tags** exposed as `lang.latin`, `lang.ea`, [`lang.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/font.cs) (complex scripts including Arabic, Hebrew, Thai). The `MergeRunProperties` method in [`WordHandler.StyleList.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.StyleList.cs) handles inheritance between these slots according to the WordprocessingML specification.