# OfficeCLI RTL Language and Internationalization Support in Word: A Complete Technical Guide > Master OfficeCLI's RTL language and internationalization support in Word. This guide details how WordHandler preserves bidirectional text and paragraph direction for seamless document management. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: deep-dive - Published: 2026-07-10 --- **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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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 `` and `` 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.Element.cs) (lines 1867-1870) updates the underlying `` element (or `` 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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 `` and `` 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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: ```bash 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 `` 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: ```bash 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 `` element in [`WordHandler.Set.Element.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.Element.cs). ### Add New RTL Content When inserting new text in an RTL language, the handler automatically applies proper formatting: ```bash 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: ```bash officecli export /document output.docx ``` For document preview, the rendering engine respects directionality: ```bash officecli preview /document --format html > preview.html ``` The generated HTML contains `
` elements for RTL paragraphs, as implemented in [`WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.I18n.cs)**: Provides the complete internationalization module with locale normalization and RTL detection utilities. - **[`WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.View.cs)**: Hosts the rendering logic that translates internal RTL markers to CSS direction properties at lines 274-281. - **[`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs)**: Serves as the main entry point that coordinates RTL processing across the document lifecycle. - **[`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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 `` elements in the underlying Word XML. - HTML previews accurately reflect RTL content through CSS `direction: rtl` injection in [`WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.View.cs). ## Frequently Asked Questions ### How does OfficeCLI detect when to apply RTL formatting? OfficeCLI uses the **`IsRtlLocale`** method in [`WordHandler.I18n.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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 `` 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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 `` element in the Word XML structure through [`WordHandler.Set.Element.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.Element.cs).