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

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 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 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, 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, 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 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 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:

# 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†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:

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:

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.
• The ResolveEffectiveLocale() method balances explicit CLI arguments against the OS culture snapshot captured in Program.cs.
• During document creation, 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.

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. 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. 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.

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