How to Create a Document with a Specific Locale in OfficeCLI

Use the --locale flag with the create command to specify a language-locale (e.g., ar-SA, zh-CN), which sets the document's internal language tags, font fallback, and right-to-left writing direction.

OfficeCLI is an open-source command-line tool for generating Microsoft Office-compatible documents. When you need to create a document with a specific locale in OfficeCLI, the tool provides first-class support for language-specific formatting through the --locale parameter, ensuring that fonts, text direction, and internal metadata align with your target region's standards.

How the --locale Flag Works

The create verb in OfficeCLI accepts an optional --locale argument that instructs the document engine which language and regional settings to apply. According to the iOfficeAI/OfficeCLI source code, this parameter influences three critical aspects of document generation: the writing direction (left-to-right vs. right-to-left), the theme font languages for proper font fallback, and the document's primary language metadata.

When you omit the flag, OfficeCLI falls back to the operating system's user locale captured at startup, mirroring the behavior of Microsoft Word and Apple Pages.

Step-by-Step Document Creation with Locales

Default Behavior: OS Locale Snapshot

At application startup, OfficeCLI captures the current operating system locale in OfficeCli.Core.LocaleFontRegistry.OsLocaleSnapshot as shown in src/officecli/Program.cs【L9-L14】. This snapshot serves as the default value for all document creation operations when the --locale flag is not explicitly provided.

Overriding with Explicit Locales

To create a document with a specific locale, append the --locale flag followed by a valid BCP47 language tag (such as ar-SA for Arabic-Saudi Arabia or zh-CN for Chinese-Simplified). The CLI parses this argument and passes it to the BlankDocCreator.Create method, which accepts a nullable locale parameter【BlankDocCreator.csL15-L25】.

Technical Implementation Details

The locale handling pipeline spans three core files that work together to inject language-specific behavior into new documents.

Program.cs and OS Locale Detection

The entry point in src/officecli/Program.cs initializes the locale system by snapshotting the OS user locale at startup【L9-L14】. This ensures that default document creation matches the user's environment unless explicitly overridden.

BlankDocCreator.cs and Document Construction

The BlankDocCreator.Create method serves as the primary factory for blank Office files. When creating Word documents (.docx), the call routes to CreateWord, which performs two critical locale-aware operations:

1. RTL Detection: The method checks LocaleFontRegistry.IsRightToLeft(locale) to determine if the locale requires right-to-left layout【BlankDocCreator.csL16-L21】.
2. Bidirectional Markup: If RTL is detected, OfficeCLI adds a <w:bidi/> element to the section properties, forcing the entire document into RTL mode【BlankDocCreator.csL29-L31】.
3. Theme Language Stamping: The primary language is stamped into the document's ThemeFontLanguages property, ensuring that preview rendering and font fallback work correctly【BlankDocCreator.csL86-L92】.

LocaleFontRegistry.cs and Font Resolution

The LocaleFontRegistry class in src/officecli/Core/LocaleFontRegistry.cs provides the underlying locale resolution logic【L8-L30】. Its Resolve method maps locale tags to appropriate font triples for East Asian, Complex Script, and Latin text ranges. The IsRightToLeft method checks the language portion of the tag (e.g., ar in ar-SA) to determine if RTL layout is required【L78-L84】.

Practical Examples

The --locale flag works uniformly across all supported Office formats (.docx, .xlsx, .pptx).

# Create using OS default locale (no flag specified)

officecli create mydoc.docx

# Create Arabic document with RTL layout support

officecli create contract.docx --locale ar-SA

# Create Chinese document with CJK font fallback

officecli create report.xlsx --locale zh-CN

# Create Japanese PowerPoint with appropriate theme fonts

officecli create slides.pptx --locale ja-JP

Note: Locale tags must follow standard BCP47 format (e.g., en-US, he-IL, th-TH). Invalid tags will fall back to the OS snapshot behavior.

Summary

• Use the --locale flag with the create command to specify a document's language and regional settings.
• RTL support is automatic: OfficeCLI detects right-to-left locales via LocaleFontRegistry.IsRightToLeft and injects <w:bidi/> elements in Word documents.
• Default behavior captures the OS locale at startup (Program.cs) and applies it when no flag is provided.
• Font handling occurs through LocaleFontRegistry.Resolve, which maps locales to appropriate font triples for multi-script support.
• Implementation spans three files: Program.cs (default capture), BlankDocCreator.cs (document construction), and LocaleFontRegistry.cs (locale resolution).

Frequently Asked Questions

What happens if I omit the --locale flag?

OfficeCLI uses the operating system user locale captured at application startup. This snapshot is stored in OfficeCli.Core.LocaleFontRegistry.OsLocaleSnapshot during initialization in Program.cs, ensuring consistent behavior with desktop Office applications.

Does the locale flag affect Excel and PowerPoint files?

Yes. While the implementation details differ internally, the --locale flag is respected across all supported formats (.docx, .xlsx, .pptx). The flag influences font fallback lists and language metadata in the underlying Open XML structure.

How does OfficeCLI handle right-to-left languages?

When you specify an RTL locale (such as ar-SA or he-IL), the CreateWord method in BlankDocCreator.cs calls LocaleFontRegistry.IsRightToLeft(locale) to detect the writing direction. If RTL is detected, the method adds a <w:bidi/> element to the document's section properties, setting the entire document to RTL layout.

Can I use any language tag format?

OfficeCLI expects standard BCP47 language tags (e.g., zh-CN, en-GB, ar-SA). The LocaleFontRegistry.Resolve method parses these tags to determine font families and writing direction. Non-standard tags may result in fallback to the OS default locale.

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