# How OfficeCLI Locale Font Registry Bakes Locale-Specific Fonts Into Documents

> Discover how OfficeCLI's Locale Font Registry embeds locale-specific fonts into documents, ensuring script-appropriate defaults for global content.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-07-08

---

**The OfficeCLI Locale Font Registry automatically embeds script-appropriate default fonts into OOXML documents by mapping the user's locale to Latin, East-Asian, and Complex-Script font families during document creation.**

The iOfficeAI/OfficeCLI repository provides a cross-platform command-line tool for automating Microsoft Office documents. At its core, the **OfficeCLI Locale Font Registry** ensures that generated documents contain the correct default typography for the target language, eliminating manual font configuration for global teams.

## How the Locale Font Registry Resolves Fonts

The registry operates on a three-step resolution pipeline that translates a locale identifier into concrete font instructions.

### Capturing the OS Locale Snapshot

On startup, [`/src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/Program.cs) captures the current operating system culture and stores it in the static property `LocaleFontRegistry.OsLocaleSnapshot`†L14. This snapshot serves as the default fallback when no explicit locale is provided.

### Resolving the Effective Locale

The `LocaleFontRegistry.ResolveEffectiveLocale(string? explicitLocale)` method in [`/src/officecli/Core/LocaleFontRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/Core/LocaleFontRegistry.cs) implements the priority logic: it returns the explicit `--locale` argument if supplied, otherwise falls back to the OS snapshot†L91-L94. This ensures CLI users can override system defaults while maintaining sensible defaults for automated environments.

### Mapping Locales to Font Triplets

The `LocaleFontRegistry.Resolve(string locale)` method returns a triplet of font identifiers:
- **Latin** (`locLatin`): The generic Latin-script font (e.g., *Calibri* for Western locales).
- **East-Asian** (`locEa`): A font supporting CJK script blocks (e.g., *Microsoft YaHei* for Chinese).
- **Complex-Script** (`locCs`): A font for scripts requiring shaping (e.g., *Neo Sans Arabic* for Arabic).

This mapping lives in a static dictionary inside [`LocaleFontRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/LocaleFontRegistry.cs), enabling O(1) lookups at runtime.

## Baking Fonts Into OOXML Document Defaults

Once the font triplet is resolved, the registry embeds these values directly into the document package.

### Writing the DocDefaults Section

In [`/src/officecli/BlankDocCreator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/BlankDocCreator.cs), the creation workflow calls `LocaleFontRegistry.Resolve(locale)` and writes the three fonts into the `<w:docDefaults>` section of the generated `.docx` (or analogous parts for `.pptx` and `.xlsx`)†L116-L119. The resulting OOXML contains the `<w:rFonts>` element with `w:ascii`, `w:eastAsia`, and `w:cs` attributes populated according to the resolved locale.

### RTL Layout Detection

For right-to-left scripts, `LocaleFontRegistry.IsRightToLeft(locale)` checks against Arabic, Hebrew, Persian, Urdu, and other RTL locales†L284-L287. When detected, [`BlankDocCreator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BlankDocCreator.cs) injects the `<w:rtl/>` flag into the run properties, ensuring the document opens with correct bidirectional layout in Microsoft Office.

## Generating Locale-Aware HTML Previews

The registry reuses the same locale logic when rendering documents to HTML for preview purposes.

### Detecting Locale from Theme Fonts

When processing a Word document for HTML output, `LocaleFontRegistry.DetectLocaleFromCjkFontName(themeEa)` extracts the locale identifier from the theme's East-Asian font name†L181-L183. This allows the preview engine to infer the document's intended language even when the `--locale` flag was not explicitly provided during creation.

### CSS Fallback Chains

The `LocaleFontRegistry.GetCjkCssFallback(locale)` method returns a list of `@font-face` CSS rules that guarantee the correct script font is available in headless browser environments†L3320-L3368. The [`/src/officecli/Handlers/Word/WordHandler.HtmlPreview.Css.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/Handlers/Word/WordHandler.HtmlPreview.Css.cs) file embeds these rules into the generated HTML `<style>` block, ensuring visual fidelity between the OOXML source and the rendered preview.

## Command-Line and Programmatic Usage

### Creating Documents with Explicit Locales

Use the `--locale` flag to bake specific fonts into new documents:

```bash

# Arabic document with RTL layout and Arabic Typesetting font

officecli create report.docx --locale ar-SA

# Chinese Simplified document with Microsoft YaHei for CJK glyphs

officecli create sales.docx --locale zh-CN

```

The `officecli create` command, defined in [`/src/officecli/CommandBuilder.Import.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/CommandBuilder.Import.cs)†L126-L149, passes the locale value through `ResolveEffectiveLocale()` before invoking the document creator.

### Inspecting Baked Font Defaults

Dump the OOXML to verify the embedded fonts:

```bash
officecli dump report.docx /word/settings.xml -o defaults.xml

```

The output will contain the `<w:docDefaults>` structure with `w:rFonts` attributes matching the locale-specific selections.

### Using the C# SDK

Programmatically access the registry when building custom document workflows:

```csharp
using OfficeCli.Core;

// Resolve locale (explicit or OS fallback)
string locale = LocaleFontRegistry.ResolveEffectiveLocale(null);

// Retrieve the three default fonts
var (latinFont, eaFont, csFont) = LocaleFontRegistry.Resolve(locale);

// Apply to a new document
var doc = new WordDocument();
doc.SetDefaultFonts(latinFont, eaFont, csFont);
doc.Save("localized.docx");

```

## Summary

- **OfficeCLI Locale Font Registry** maps locale strings to three distinct font families (Latin, East-Asian, Complex-Script) stored in [`/src/officecli/Core/LocaleFontRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/Core/LocaleFontRegistry.cs).
- The `ResolveEffectiveLocale()` method balances explicit CLI arguments against the OS culture snapshot captured in [`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs).
- During document creation, [`BlankDocCreator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BlankDocCreator.cs) embeds these fonts into the OOXML `<w:docDefaults>` and sets RTL flags for right-to-left scripts.
- HTML preview generation leverages `DetectLocaleFromCjkFontName()` and `GetCjkCssFallback()` to produce locale-appropriate CSS in [`/src/officecli/Handlers/Word/WordHandler.HtmlPreview.Css.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/Handlers/Word/WordHandler.HtmlPreview.Css.cs).

## Frequently Asked Questions

### How does OfficeCLI handle documents for mixed-language teams?

OfficeCLI stores the locale-specific fonts in the document's default run properties, not as hardcoded text styles. This means when a colleague opens the document in Microsoft Office, the editing environment automatically loads the appropriate script fonts and directionality settings, regardless of their local OS language.

### Can I override the default font mapping for a specific locale?

Yes. The `LocaleFontRegistry.Resolve()` method uses a static dictionary that can be modified at runtime if you are using the C# SDK directly. For CLI users, you can create a document with one locale, then manually edit the OOXML `docDefaults` afterward, though the registry itself is designed to enforce consistent typography standards.

### What happens if I create a document without specifying a locale?

The system falls back to `LocaleFontRegistry.OsLocaleSnapshot`, captured at startup in [`/src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/Program.cs). This ensures the document uses fonts appropriate for the machine where the command runs, making automation pipelines locale-aware by default.

### Does the font registry affect existing documents or only new ones?

The registry primarily affects new documents created via [`BlankDocCreator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BlankDocCreator.cs). When rendering existing documents to HTML, the preview system uses `DetectLocaleFromCjkFontName()` to infer the original locale from the document's theme fonts, ensuring the HTML preview matches the intended script without modifying the source file.