Skip to content

Default template theme forces East-Asian text to fall back to MS Mincho (MS 明朝) #1601

Description

@sebastEXlabe

Default template's theme forces East-Asian text to fall back to MS Mincho (MS 明朝)

Summary

Document() (a fresh document created from the bundled default.docx template) configures the
theme and document settings so that East-Asian text resolves to the Japanese font MS 明朝 (MS Mincho),
even when the user never asked for a Japanese font and even after setting an explicit East-Asian
font with run.font.name.
On systems that don't have MS Mincho installed (a standard Chinese/English
Windows), the CJK glyphs are then substituted / rendered in the wrong typeface.

This is distinct from the long-standing API gaps in #346 / #154 / #1396 (which are about
Font.name not writing the w:eastAsia attribute). Those reports are about the user-side setter.
This issue is about the default template itself shipping a mis-configured theme that make the
fallback land on a Japanese font.

Environment

  • python-docx: 1.2.0 (verified against master, byte-identical template)
  • Word / WPS on a Chinese-locale Windows without the MS Mincho / MS Gothic fonts installed

Reproduction

from docx import Document

doc = Document()          # fresh document from bundled default.docx
p = doc.add_paragraph()
run = p.add_run("中文字体回退测试 Chinese 123")
# Default behavior - we never set any font.
doc.save("repro.docx")

The run python-docx emits

<w:r><w:t>中文字体回退测试 Chinese 123</w:t></w:r>

There is no <w:rPr>/<w:rFonts> on the run at all. So the CJK glyphs must inherit from the theme.

Root cause chain (all confirmed from the shipped template)

The inherited East-Asian font resolves through this chain, and every link is wrong:

  1. word/settings.xmlthemeFontLang declares the document's East-Asian language as Japanese:

    <w:themeFontLang w:val="en-US" w:eastAsia="ja-JP"/>
  2. word/theme/theme1.xml — the minorFont (used by Normal text via docDefaults) has an empty
    East-Asian and complex-script typeface, and its Jpan script font is a Japanese face:

    <a:minorFont>
      <a:latin typeface="Cambria"/>
      <a:ea typeface=""/>
      <a:cs typeface=""/>
      <a:font script="Jpan" typeface="MS 明朝"/>
      ...
    </a:minorFont>

    (majorFont has the same empty ea/cs with Jpan = MS ゴシック.)

  3. word/styles.xmldocDefaults references the theme East-Asian font instead of a concrete font:

    <w:rFonts w:asciiTheme="minorHAnsi" w:eastAsiaTheme="minorEastAsia" w:hAnsiTheme="minorHAnsi" w:cstheme="minorBidi"/>
  4. word/fontTable.xml — the theme declares the Japanese faces MS 明朝 and MS ゴシック as
    real fonts (charset 0x80), so they are treated as available.

Resolution: run has no font → docDefaults gives eastAsiaTheme="minorEastAsia" → theme minorFont
East-Asian typeface is empty → because themeFontLang eastAsia is ja-JP, the document's East-Asian
language is Japanese → the Jpan script font (MS 明朝) is selected.

Even setting run.font.name = '宋体' does NOT fix the CJK glyphs, because python-docx only writes
w:ascii/w:hAnsi (see #346 / #154) and the East-Asian characters still fall through to the theme's
Japanese font.

Expected behavior

  • A freshly created Document() should not, by default, resolve CJK text to a Japanese typeface.
  • The default template should either declare a neutral/Chinese East-Asian language
    (w:eastAsia="zh-CN"), or specify a concrete, localizable East-Asian font in the theme's
    a:ea/a:cs slots, so CJK glyphs don't silently fall back to MS Mincho.

Possible fix (in the bundled template)

  • settings.xml: w:themeFontLang ... w:eastAsia="zh-CN" (or drop the Japanese default).
  • theme1.xml: give a:ea/a:cs a non-empty, meaningful typeface (e.g. 宋体/SimSun), or point
    Jpan at a font that shippers commonly have; or set these to a neutral theme-resolvable value.

Related, non-duplicate issues

These describe the missing eastAsia API; none of them reports that the default template itself
ships a Japanese-language theme that makes the fallback land on MS Mincho.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions