Repository navigation
Default template theme forces East-Asian text to fall back to MS Mincho (MS 明朝) #1601
Description
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:
-
word/settings.xml—themeFontLangdeclares the document's East-Asian language as Japanese:<w:themeFontLang w:val="en-US" w:eastAsia="ja-JP"/>
-
word/theme/theme1.xml— theminorFont(used by Normal text viadocDefaults) has an empty
East-Asian and complex-script typeface, and itsJpanscript 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>
(
majorFonthas the same emptyea/cswithJpan=MS ゴシック.) -
word/styles.xml—docDefaultsreferences the theme East-Asian font instead of a concrete font:<w:rFonts w:asciiTheme="minorHAnsi" w:eastAsiaTheme="minorEastAsia" w:hAnsiTheme="minorHAnsi" w:cstheme="minorBidi"/>
-
word/fontTable.xml— the theme declares the Japanese facesMS 明朝andMS ゴシックas
real fonts (charset0x80), 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:csslots, 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: givea:ea/a:csa non-empty, meaningful typeface (e.g.宋体/SimSun), or point
Jpanat a font that shippers commonly have; or set these to a neutral theme-resolvable value.
Related, non-duplicate issues
- feature: Font.name_far_east #154 — feature request for
Font.name_far_east(API does not expose East-Asian font setter) - Cannot set Chinese character font typeface #346 —
run.font.namedoes not apply to Chinese characters (same API limitation) - Chinese fonts Only the non-Chinese parts are valid #1396 — confirms
run.font.namewrites onlyascii/hAnsi, nevereastAsia
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.
Activity
lsaint commentedon Aug 28, 2026
This is one of the gaps I ran into as well. I maintain python-docx-oss, which keeps the same docx API but exposes the font slots separately, including run.font.eastAsia, so CJK fonts can be set without dropping down to raw XML.
It doesn’t address the bundled template/theme issue you identified here, but it may be useful as an immediate workaround for the missing East Asian font setter:
http://github.com/lsaint/python-docx-oss