OfficeCLI i18n and RTL Language Support in Word Documents: Complete Technical Guide

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 (lines 1180-1187), the parser extracts these attributes from <w:rPr> 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 <w:pPr><w:bidi> element (or <w:rtl> in newer schemas) when processing set commands.

In 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) 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 (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 <w:bidi> and <w:rtl> 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):

   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 <w:bidi> flag automatically.

2. Force a specific paragraph to RTL:

   # 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:

   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:

   officecli export /document output.docx

   All RTL settings are written back to the resulting DOCX file.

5. Render a preview that respects RTL direction:

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

   The generated HTML contains <div style="direction: rtl">…</div> 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 during parsing and export
• Automatic RTL detection occurs via IsRtlLocale in 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

Frequently Asked Questions

How does OfficeCLI detect when to apply RTL formatting?

OfficeCLI uses the IsRtlLocale method in 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 <w:bidi> 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 (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 (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 <w:bidi> and <w:rtl> elements exactly as they appeared in the original document, modified only by your explicit CLI commands.

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