# How to Create a Document with a Specific Locale in OfficeCLI

> Learn to create a document with a specific locale in OfficeCLI using the --locale flag. Easily set internal language tags, fonts, and writing direction for your documents. Get started today!

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-09

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`).

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs) (default capture), [`BlankDocCreator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BlankDocCreator.cs) (document construction), and [`LocaleFontRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.