# OfficeCLI i18n and RTL Language Support in Word Documents: Complete Technical Guide > Learn how OfficeCLI provides effortless i18n and RTL language support for Word documents. Automatically detect, preserve, and manage bidirectional text with WordHandler. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: deep-dive - Published: 2026-07-12 --- **OfficeCLI provides built-in RTL (right-to-left) and internationalization support for Word documents through its `WordHandler` implementation, automatically detecting RTL locales and preserving bidirectional text attributes across parsing, modification, and export operations.** The iOfficeAI/OfficeCLI repository delivers a comprehensive command-line interface for Office document manipulation, with particular emphasis on internationalization (i18n) and right-to-left (RTL) language support in Word files. This article examines how the `WordHandler` class manages bidirectional text, locale detection, and RTL preservation throughout the document lifecycle, ensuring that Arabic, Hebrew, Persian, and other RTL scripts maintain their formatting integrity. ## How RTL is Handled in the Word Handler The `WordHandler` class implements RTL support through four specialized components that handle everything from low-level XML parsing to HTML preview generation. Each component preserves the original document's directionality attributes while allowing programmatic modifications. ### Bidirectional Runs At the XML level, bidirectional text is controlled by the `bidi` flag and `markRPr` (mark-right-to-left) attributes within Word's Open XML schema. In [`WordHandler.Set.Element.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.Element.cs) (lines 1180-1187), the parser extracts these attributes from `` elements and stores them on the internal run model. When the document is modified and exported, these attributes are written back unchanged, ensuring that mixed-direction paragraphs preserve their exact formatting. This approach treats each run's direction independently, allowing Arabic text inside English paragraphs to maintain correct rendering. ### Paragraph-Level Direction Paragraphs can be marked as RTL, LTR, or inherit direction from document defaults. The handler updates the underlying `` element (or `` in newer schemas) when processing `set` commands. In [`WordHandler.Set.Element.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.Element.cs) (lines 1867-1870), the code specifically handles paragraph property mutations, ensuring that when you change a paragraph's direction via the CLI, the corresponding XML structure is correctly modified to reflect the new bidirectional settings. ### Internationalization Helpers The `I18n` partial class (merged into `WordHandler` and located in [`WordHandler.I18n.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.I18n.cs)) provides utility methods for locale normalization and RTL detection. Key functions include: - **`NormalizeLocale`**: Standardizes locale strings to canonical formats - **`IsRtlLocale`**: Fast lookup determining if a language requires RTL direction (e.g., `ar`, `he`, `fa`) - **`ApplyLocaleToRuns`**: Automatically applies direction flags when specific locales are detected These helpers are called from the `Set` and `Add` pipelines, guaranteeing that any RTL flag is correctly propagated when users modify document language properties. ### Render Model Host For HTML preview generation, the `IRenderModelHost` implementation in [`WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.View.cs) (lines 274-281) respects the stored `bidi` attributes. When generating previews, the code inserts CSS `direction: rtl` on appropriate elements, ensuring the visual representation matches the document's actual directionality. ## The Complete RTL Pipeline OfficeCLI implements a comprehensive RTL workflow that spans the entire document lifecycle: 1. **Parsing**: The original DOCX is unmarshalled, with `` and `` tags captured and stored in the internal model 2. **Command Handling**: `set`, `add`, and `remove` commands can modify bidirectional flags or change paragraph languages, with the handler automatically toggling RTL attributes when the target locale is an RTL language 3. **Export and Preview**: The modified model is serialized into a new DOCX file, while the HTML preview reflects the correct direction for WYSIWYG accuracy ## Working with RTL Languages: Practical Examples The following command-line examples demonstrate how to use OfficeCLI's i18n and RTL features: 1. **Set the document language to Arabic (automatically switches to RTL)**: ```bash officecli set /document @lang "ar-SA" ``` The `set` command updates the document's language attribute, and the handler detects that `ar-SA` is an RTL locale, adding the required `` flag automatically. 2. **Force a specific paragraph to RTL**: ```bash # Paragraph 3 (zero-based index) becomes right-to-left officecli set /document/paragraphs/3 @dir "rtl" ``` The `@dir` property maps to the internal bidi flag, persisting the change in the DOCX and reflecting it in the HTML preview. 3. **Add a new RTL paragraph**: ```bash officecli add /document/paragraphs \ --text "مرحبا بالعالم" \ --lang "ar-SA" ``` Because the supplied language is RTL, the handler automatically decorates the newly created paragraph with the proper direction flag. 4. **Export the modified document**: ```bash officecli export /document output.docx ``` All RTL settings are written back to the resulting DOCX file. 5. **Render a preview that respects RTL direction**: ```bash officecli preview /document --format html > preview.html ``` The generated HTML contains `
…
` for any RTL paragraphs. ## Why RTL Works Reliably OfficeCLI's RTL support is robust due to three architectural decisions: - **Source-of-truth model**: The internal representation mirrors Word's Open XML schema exactly, eliminating heuristic conversion errors - **Locale-aware utilities**: The `I18n` module maintains a canonical list of RTL locales and provides fast lookup via `IsRtlLocale`, preventing mistakes where users set language but forget direction flags - **Bidirectional run handling**: By treating each run's direction independently, mixed-direction paragraphs preserve their complex formatting (e.g., Arabic text inside English paragraphs) ## Summary - **OfficeCLI** provides comprehensive RTL and i18n support through the `WordHandler` class in the iOfficeAI/OfficeCLI repository - **Bidirectional attributes** (`bidi`, `markRPr`) are preserved in [`WordHandler.Set.Element.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.Element.cs) during parsing and export - **Automatic RTL detection** occurs via `IsRtlLocale` in [`WordHandler.I18n.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.I18n.cs) when setting Arabic, Hebrew, or Persian languages - **Paragraph-level direction** can be explicitly controlled using the `@dir` attribute in `set` commands - **HTML previews** correctly render RTL content with CSS `direction: rtl` as implemented 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 if a locale code (such as `ar-SA`, `he-IL`, or `fa-IR`) corresponds to a right-to-left language. When detected, the handler automatically adds the appropriate `` flags to paragraphs and runs. ### Can I mix RTL and LTR text in the same document? Yes. The handler preserves bidirectional runs independently, as implemented in [`WordHandler.Set.Element.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Set.Element.cs) (lines 1180-1187). Each run maintains its own directionality attributes, allowing complex mixed-direction documents to retain their formatting through CLI operations. ### Will the HTML preview correctly display RTL text? Yes. The preview generator in [`WordHandler.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.View.cs) (lines 274-281) inspects the `bidi` attributes and injects CSS `direction: rtl` into the generated HTML, ensuring that the preview matches the document's actual appearance in Word. ### What happens to RTL settings when I export the document? All RTL settings are preserved during export. The `WordHandler` serializes the internal model back to Open XML format, writing the `` and `` elements exactly as they appeared in the original document, modified only by your explicit CLI commands.