OfficeCLI RTL Language and Internationalization Support in Word: A Complete Technical Guide

OfficeCLI delivers comprehensive RTL language and internationalization support in Word documents through its WordHandler implementation, preserving bidirectional text markers and paragraph directionality throughout parsing, modification, and rendering operations.

The iOfficeAI/OfficeCLI repository provides command-line tools for manipulating Microsoft Office documents with particular attention to right-to-left (RTL) scripts and internationalization (i18n) requirements. When processing Arabic, Hebrew, or Persian content in Word files, the WordHandler class ensures that all directionality attributes in the underlying Open XML structure remain intact during document transformations.

Understanding the RTL Architecture in WordHandler

OfficeCLI's Word handler implements a complete RTL pipeline that mirrors Word's Open XML schema. This architecture ensures that bidirectional runs, paragraph direction markers, and locale-specific attributes persist through any document operation.

Bidirectional Run Handling

At the lowest level, OfficeCLI recognizes and preserves the XML attributes that control text direction within individual runs. In WordHandler.Set.Element.cs (lines 1180-1187), the parser extracts the bidi flag and any markRPr (mark-right-to-left) attributes from the source document, storing them on the internal run model. During export, these attributes serialize back to the <w:bidi> and <w:markRPr> elements unchanged, ensuring mixed-direction paragraphs—such as Arabic text within English content—maintain their original formatting.

Paragraph-Level Direction Control

The handler manages paragraph-wide directionality through the paragraph properties element. When the CLI processes a set command targeting paragraph properties, the code at WordHandler.Set.Element.cs (lines 1867-1870) updates the underlying <w:pPr><w:bidi> element (or <w:rtl> in newer schemas). This allows explicit control over whether a paragraph flows right-to-left, left-to-right, or inherits direction from document defaults.

Internationalization Utilities

The I18n partial class, defined in WordHandler.I18n.cs, provides the locale-aware logic that automates RTL detection. Key methods include:

• IsRtlLocale: Fast lookup function that identifies RTL languages (e.g., ar, he, fa)
• NormalizeLocale: Standardizes locale strings to canonical formats
• ApplyLocaleToRuns: Propagates direction flags to text runs based on language settings

These utilities integrate into the Set and Add pipelines, automatically toggling RTL attributes when the target locale requires right-to-left rendering.

How the RTL Pipeline Works

OfficeCLI processes RTL content through three distinct stages that preserve document fidelity:

1. Parsing: The DOCX unmarshaller captures all <w:bidi> and <w:rtl> tags from the source Word XML, storing them in the internal representation.
2. Command Handling: When executing set, add, or remove commands, the handler consults the I18n utilities. If the target language is an RTL locale, the system automatically decorates paragraphs and runs with the appropriate direction flags.
3. Export and Preview: The modified model re-serializes into DOCX format with all RTL attributes intact. Simultaneously, the IRenderModelHost implementation in WordHandler.View.cs (lines 274-281) generates HTML previews that respect the bidi attribute, injecting CSS direction: rtl styles to ensure accurate WYSIWYG rendering.

Working with RTL Languages in OfficeCLI

The following command-line examples demonstrate how to manipulate RTL content using OfficeCLI's Word handler.

Set Document Language with Automatic RTL Detection

When updating the document language to an RTL locale, OfficeCLI automatically applies the correct directionality flags:

officecli set /document @lang "ar-SA"

The handler detects that ar-SA (Arabic - Saudi Arabia) is an RTL locale through the IsRtlLocale function and adds the required <w:bidi> flags to the document structure without requiring explicit direction parameters.

Force Specific Paragraph Direction

To explicitly set a paragraph's direction regardless of language settings:

officecli set /document/paragraphs/3 @dir "rtl"

This command updates the paragraph at index 3 (zero-based) with the RTL direction flag, modifying the underlying <w:pPr><w:bidi> element in WordHandler.Set.Element.cs.

Add New RTL Content

When inserting new text in an RTL language, the handler automatically applies proper formatting:

officecli add /document/paragraphs \
    --text "مرحبا بالعالم" \
    --lang "ar-SA"

Because the supplied language ar-SA triggers the RTL detection logic, the new paragraph receives the appropriate direction decorations during creation.

Export and Preview RTL Documents

After modifications, export preserves all RTL settings:

officecli export /document output.docx

For document preview, the rendering engine respects directionality:

officecli preview /document --format html > preview.html

The generated HTML contains <div style="direction: rtl"> elements for RTL paragraphs, as implemented in WordHandler.View.cs (lines 274-281).

Implementation Details and Source Code Architecture

OfficeCLI's RTL support relies on specific implementations across several source files:

• WordHandler.Set.Element.cs: Contains the mutation logic for paragraph and run elements, specifically handling bidi and markRPr attributes at lines 1180-1187 and 1867-1870.
• WordHandler.I18n.cs: Provides the complete internationalization module with locale normalization and RTL detection utilities.
• WordHandler.View.cs: Hosts the rendering logic that translates internal RTL markers to CSS direction properties at lines 274-281.
• WordHandler.cs: Serves as the main entry point that coordinates RTL processing across the document lifecycle.
• ResidentServer.cs: Routes Word-specific requests to the appropriate handler methods while maintaining document state.

Summary

• OfficeCLI provides native RTL support through the WordHandler class, preserving Open XML directionality markers during all operations.
• Bidirectional runs maintain their bidi and markRPr attributes through parsing and export cycles via WordHandler.Set.Element.cs.
• The I18n utility class automatically detects RTL locales (Arabic, Hebrew, Persian) and applies appropriate direction flags without manual intervention.
• Paragraph-level direction can be explicitly controlled through the @dir property, modifying <w:pPr><w:bidi> elements in the underlying Word XML.
• HTML previews accurately reflect RTL content through CSS direction: rtl injection in WordHandler.View.cs.

Frequently Asked Questions

How does OfficeCLI detect when to apply RTL formatting?

OfficeCLI uses the IsRtlLocale method in WordHandler.I18n.cs to check language codes against a canonical list of RTL locales. When processing set or add commands with language parameters like ar-SA or he-IL, the handler automatically applies the <w:bidi> flag to paragraphs and runs, ensuring proper right-to-left rendering without requiring explicit direction parameters.

Can OfficeCLI handle mixed-direction text within the same paragraph?

Yes. The handler preserves bidirectional runs by storing individual bidi flags on each text run during parsing. When a paragraph contains both English (LTR) and Arabic (RTL) text, OfficeCLI maintains separate run properties for each segment, ensuring that mixed-direction content exports correctly back to the DOCX format.

What happens to RTL settings when exporting to HTML preview?

The rendering pipeline in WordHandler.View.cs (lines 274-281) inspects the stored bidi attributes during HTML generation. For any content flagged as right-to-left, the preview generator injects inline CSS direction: rtl styles onto the corresponding HTML elements, producing a WYSIWYG preview that matches the Word document's actual layout.

Is it possible to force RTL direction without changing the document language?

Yes. OfficeCLI supports explicit direction control through the @dir property. You can execute officecli set /document/paragraphs/3 @dir "rtl" to set a specific paragraph to RTL mode regardless of the language setting. This command directly manipulates the <w:pPr><w:bidi> element in the Word XML structure through WordHandler.Set.Element.cs.

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