How OfficeCLI Handles Internationalization and RTL Text Rendering

OfficeCLI treats every document as a locale-aware artifact, automatically detecting RTL scripts and applying OpenXML direction cascades while resolving locale-specific font mappings for Latin, East Asian, and Complex Script text.

OfficeCLI is an open-source command-line interface for creating and manipulating Office documents. The tool implements comprehensive internationalization and RTL text rendering capabilities that ensure documents display correctly across different languages and writing directions. This article examines the specific mechanisms in the source code that handle locale detection, font resolution, and right-to-left text layout.

Locale Detection and Resolution

OfficeCLI determines the target locale through a hierarchical resolution strategy that balances explicit user input with operating system defaults.

OS Culture Snapshot and Explicit Flags

When the CLI initializes, Program.cs captures the current OS culture snapshot and stores it in LocaleFontRegistry.OsLocaleSnapshot. Users can override this default by passing the --locale flag (for example, --locale ar-SA or --locale zh-CN). If no explicit flag is provided, the system falls back to the captured OS culture.

Effective Locale Resolution

The resolution logic resides in src/officecli/Core/LocaleFontRegistry.cs within the ResolveEffectiveLocale method (lines 91-106). This method returns the final locale tag that drives all subsequent font and layout decisions. The algorithm prioritizes the command-line argument, then consults the OS snapshot, ensuring that every document operation has a deterministic locale context.

Font Mapping for Complex Scripts

Once the effective locale is established, OfficeCLI maps language tags to appropriate typefaces using a triple-slot system that handles diverse writing systems.

Locale-to-Font Triple Mapping

The LocaleFontRegistry.Resolve method (lines 28-62 in src/officecli/Core/LocaleFontRegistry.cs) returns a tuple of default fonts for three distinct slots:

• Latin scripts (English, French, etc.)
• East Asian scripts (Chinese, Japanese, Korean)
• Complex Script (Arabic, Hebrew, Thai, etc.)

This ensures that blank documents start with typefaces appropriate for the target script. For example, a document created with --locale ar-SA receives Arabic-compatible fonts in the Complex Script slot, while --locale zh-CN populates the East Asian slot with Chinese typefaces.

CJK Font Fallback Chains

For Chinese, Japanese, and Korean locales, the CLI generates CSS fallback strings via LocaleFontRegistry.GetCjkCssFallback (lines 59-70). This method returns a prioritized font list (such as 'Hiragino Sans', 'Hiragino Mincho ProN', 'Yu Gothic') that is inserted into HTML or SVG previews. This guarantees that even if the primary font is missing on the rendering machine, a suitable script-specific alternative is chosen.

RTL Text Rendering in Word Documents

OfficeCLI provides robust support for right-to-left languages through explicit OpenXML element injection and context-aware layout detection.

RTL Detection Logic

The LocaleFontRegistry.IsRightToLeft method (lines 121-146 in src/officecli/Core/LocaleFontRegistry.cs) determines whether a locale requires RTL layout. This method returns true for languages using Arabic, Hebrew, Urdu, Persian, and other RTL scripts. The boolean result drives all subsequent layout decisions in Word handlers.

The RTL Cascade (ApplyDirectionCascade)

When rendering RTL content, Word handlers invoke ApplyDirectionCascade located in src/officecli/Handlers/Word/WordHandler.I18n.cs (lines 30-45 and 54-101). This method implements an idempotent, reversible transformation that:

1. Adds <w:bidi/> and <w:rtl/> elements to the paragraph mark
2. Applies these direction properties to every run within the paragraph
3. Clears the elements when toggling back to LTR

This cascade guarantees correct visual ordering for Arabic and Hebrew text while maintaining document integrity across direction changes.

Table Context RTL Handling

Tables inserted into RTL documents require special treatment. The IsTableContextRtl method (lines 14-22 in src/officecli/Handlers/Word/WordHandler.I18n.cs) analyzes surrounding section properties and default paragraph settings to determine table direction. When the context is RTL, the handler stamps <w:bidiVisual/> on the table, ensuring that column ordering and text flow respect the right-to-left layout.

Practical Implementation Examples

The following C# code demonstrates how OfficeCLI components interact to handle internationalization and RTL text rendering programmatically:

// Capture the effective locale from OS or explicit flag
var effectiveLocale = LocaleFontRegistry.ResolveEffectiveLocale(null);
// Returns "ar-SA" on an Arabic Windows system without explicit override

// Determine if RTL layout is required
bool isRtl = LocaleFontRegistry.IsRightToLeft(effectiveLocale);
// Returns true for Arabic, Hebrew, Urdu, Persian, etc.

// Apply the RTL cascade to a Word paragraph
Paragraph p = new Paragraph();
WordHandler handler = new WordHandler(...);
handler.ApplyDirectionCascade(p, rtl: isRtl);
// Paragraph now contains <w:bidi/> and <w:rtl/> on the mark run and all runs

// Generate CSS fallback for CJK preview
string locale = "ja-JP";
string cssFallback = LocaleFontRegistry.GetCjkCssFallback(locale);
// Returns "'Hiragino Sans', 'Hiragino Mincho ProN', 'Yu Gothic', ..."

You can also invoke these capabilities directly from the command line:

# Create a document with Arabic locale and automatic RTL detection

officecli create MyArabicDoc.docx --locale ar-SA --direction rtl

# The command automatically:

# • Detects RTL via IsRightToLeft

# • Adds <w:bidi/> to section defaults

# • Applies the full RTL cascade to every paragraph

# • Maps appropriate fonts for Complex Script

Summary

• Locale Resolution: OfficeCLI uses LocaleFontRegistry.ResolveEffectiveLocale to determine the target locale from explicit flags or OS culture snapshots captured in Program.cs.
• Font Mapping: The system maps locales to triple-slot font families (Latin, East Asian, Complex Script) and provides CJK-specific CSS fallback chains via GetCjkCssFallback.
• RTL Detection: IsRightToLeft identifies RTL languages and triggers layout adjustments in Word documents.
• OpenXML Cascade: ApplyDirectionCascade injects <w:bidi/> and <w:rtl/> elements to ensure correct visual ordering for Arabic, Hebrew, and other RTL scripts.
• Table Support: IsTableContextRtl stamps <w:bidiVisual/> on tables placed in RTL contexts, maintaining proper column ordering.

Frequently Asked Questions

How does OfficeCLI detect if a language requires RTL layout?

OfficeCLI detects RTL requirements through the LocaleFontRegistry.IsRightToLeft method in src/officecli/Core/LocaleFontRegistry.cs (lines 121-146). This method checks the primary script of the locale tag against known RTL scripts including Arabic, Hebrew, Urdu, and Persian. When the method returns true, the Word handler triggers the RTL cascade to apply appropriate OpenXML direction elements.

What specific OpenXML elements does OfficeCLI add for RTL support?

When processing RTL content, OfficeCLI adds <w:bidi/> and <w:rtl/> elements to paragraph marks and individual runs through the ApplyDirectionCascade method in src/officecli/Handlers/Word/WordHandler.I18n.cs. For tables in RTL contexts, it stamps <w:bidiVisual/> to ensure correct visual column ordering. These elements are idempotent and reversible, allowing dynamic direction toggling.

How does the font fallback system work for CJK languages?

For Chinese, Japanese, and Korean locales, OfficeCLI calls LocaleFontRegistry.GetCjkCssFallback (lines 59-70) to generate a prioritized CSS font chain. This string includes system fonts like Hiragino Sans and Yu Gothic that are inserted into HTML or SVG previews. This ensures that even when the declared document font is unavailable on the viewing machine, the text renders with an appropriate script-specific typeface.

Can I override the automatic locale detection in OfficeCLI?

Yes. While OfficeCLI captures the OS culture snapshot at startup in Program.cs, you can override this by passing the --locale flag followed by a BCP-47 language tag (such as ar-SA or ja-JP). The ResolveEffectiveLocale method prioritizes this explicit flag over the OS default, allowing you to generate documents for any supported locale regardless of your system settings.

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