How OfficeCLI Implements Locale-Aware Page Numbering for Multi-Script Documents

OfficeCLI uses the --locale flag to populate the <w:themeFontLang> element, automatically configuring RTL directionality, locale-specific digit formats, and script-appropriate font fallbacks for accurate page numbering across Arabic, Hebrew, CJK, and Latin scripts.

OfficeCLI (iOfficeAI/OfficeCLI) couples page numbering logic with locale metadata to support diverse writing systems. When creating or editing documents, the CLI interprets the --locale argument to set WordprocessingML properties that control text direction, numeral style, and typography. This ensures that page numbers render with the correct script—whether Arabic-Indic digits, Devanagari numerals, or standard Latin forms—without manual formatting.

Locale Flag and Document Metadata

The foundation of locale-aware page numbering starts with the --locale command-line argument. When you specify flags like --locale ar-SA or --locale zh-CN, OfficeCLI stores this value in the <w:themeFontLang> element. This metadata drives three specific behaviors: reading direction (bidirectional text handling), number format (digit style selection), and font fallback (script-appropriate typography).

Core Implementation Components

Locale Flag Ingestion in Program.cs

In src/officecli/Program.cs (lines 51-52), the CLI extracts the --locale value from command-line arguments and passes it to the document creation routine. This locale string propagates throughout the pipeline to inform subsequent numbering and rendering decisions.

Numbering Definition in WordHandler.Set.cs

The src/officecli/Handlers/Word/WordHandler.Set.cs file (lines 1518-1581) constructs NumberingDefinitionsPart instances with locale-aware formats. When building numbering levels, the code populates the <w:numFmt> element with script-specific values—ranging from Latin and Roman numerals to Arabic-Indic and Devanagari digits—ensuring page number fields inherit the correct numeral style for the target locale.

Bidirectional Handling in WordHandler.I18n.cs

For right-to-left (RTL) scripts, src/officecli/Handlers/Word/WordHandler.I18n.cs (lines 110-118) determines whether to apply the <w:bidi> attribute. When the locale indicates an RTL language such as Arabic or Hebrew, the code stamps the bidirectional flag on page number runs, causing the entire sequence to render from right to left without manual intervention.

Font Fallback in LocaleFontRegistry.cs

The src/officecli/Core/LocaleFontRegistry.cs (lines 23-30) maintains a mapping between locale tags and font triples (Latin, East-Asian, Complex-Script). This registry ensures that when rendering page numbers, the system selects a font containing glyphs for the specific script—whether that requires a CJK font for Chinese numerals or a complex-script font for Arabic digits.

Style Propagation in WordHandler.StyleList.cs

In src/officecli/Handlers/Word/WordHandler.StyleList.cs (lines 621-623), locale settings propagate through style layers. This guarantees that list-based numbering definitions inherit the correct bidirectional settings from the document’s locale, ensuring consistent page number directionality throughout styled content.

Practical Examples

Create an Arabic document with RTL page numbering and Arabic-Indic digits:

# Create document with Arabic locale (RTL + Arabic-Indic digits)

officecli create new.docx --locale ar-SA

# Add a page number field (uses Arabic-Indic numbering format)

officecli set new.docx /body/p[1] --prop "field=page"

# Retrieve the raw numbering XML showing Arabic-Indic format

officecli get new.docx /numbering/abstractNum[@id=1]/level[0]/numFmt

# => <w:numFmt w:val="arabicIndic"/>

# View page 1 as image; page number renders right-to-left

officecli view new.docx screenshot --page 1

Create a Chinese document with CJK font fallbacks:

# Create document with Chinese locale (CJK font fallback)

officecli create chinese.docx --locale zh-CN

# Check the numbering format (uses decimal with CJK glyph support)

officecli get chinese.docx /numbering/abstractNum[@id=1]/level[0]/numFmt

# => <w:numFmt w:val="decimal"/>

Summary

• OfficeCLI accepts a --locale flag (e.g., ar-SA, zh-CN) that sets the <w:themeFontLang> element to drive script-specific rendering.
• The implementation spans five key files: Program.cs for flag ingestion, WordHandler.Set.cs for numbering definitions, WordHandler.I18n.cs for RTL handling, LocaleFontRegistry.cs for font mapping, and WordHandler.StyleList.cs for style propagation.
• The get /numbering command returns raw XML that preserves locale-specific formats like arabicIndic, enabling round-trip editing without losing script formatting.
• The rendering pipeline consults locale metadata during view operations to ensure page numbers display with correct directionality and fonts.

Frequently Asked Questions

How does OfficeCLI detect RTL scripts for page numbering?

OfficeCLI checks the locale tag provided via --locale in WordHandler.I18n.cs (lines 110-118). When the locale indicates an RTL script such as Arabic or Hebrew, the code automatically stamps the <w:bidi> attribute on page number runs, ensuring right-to-left rendering without manual configuration.

Can I retrieve the specific number format applied to page numbers?

Yes. Execute officecli get document.docx /numbering/abstractNum[@id=1]/level[0]/numFmt to return the raw XML. The response contains the exact <w:numFmt> value—such as arabicIndic for Arabic locales or decimal for Latin scripts—that was populated during document creation based on the locale.

What happens if a font doesn't support the target script's numerals?

The LocaleFontRegistry.cs (lines 23-30) maintains a mapping of locale tags to font triples (Latin, East-Asian, Complex-Script). If the primary font lacks glyphs for the target script, the registry triggers a fallback to a compatible font, ensuring that Arabic-Indic, CJK, or Devanagari digits render correctly in page number fields.

Does changing the locale affect existing page numbering fields?

When you modify the locale using the --locale flag during editing, OfficeCLI updates the document's <w:themeFontLang> and numbering definitions. However, existing page number fields may require the document to be re-rendered or refreshed to reflect changes in directionality or numeral format, as the raw XML stored in NumberingDefinitionsPart determines the final display.

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