feat(FR-2719): use language-appropriate Noto CJK font for PDF body

yomybaby · yomybaby · commit 774a538ca3c6 · 2026-04-26T02:59:04.000Z
The previous CI build of the Korean PDF embedded WenQuanYiZenHei (a
Chinese fontconfig fallback) for the body text instead of a proper
Korean font. The cause was a two-part gap:

1. The release workflow installed only the single-face fonts pdf-lib
   needs for header/footer stamping (fonts-nanum / fonts-takao-gothic /
   fonts-thai-tlwg). Chromium's HTML rendering needs a different set
   of fonts that match what the CSS font-family list requests.
2. The CSS in styles.ts and styles-web.ts requested 'Noto Sans KR/JP'
   only, never 'Noto Sans CJK KR/JP/TC'. fonts-noto-cjk on Ubuntu only
   registers the latter family names, so even with the package installed
   Chromium would fall through to fontconfig's sans-serif default
   (WenQuanYiZenHei).

Fixes:
- workflow: add fonts-noto-cjk to the apt install list and run fc-cache
  so Chromium picks the proper CJK face when rendering HTML.
- styles.ts: extend the body font-family with 'Noto Sans CJK KR/JP/TC'.
  Add :lang(ja) and :lang(th) overrides so the per-language &lt;html lang&gt;
  attribute selects the language-appropriate Noto CJK face (the
  KR/JP/TC faces differ in kanji/hanja glyph style) instead of always
  falling back to the Korean face.
- styles-web.ts: same family extension so the docs website matches.

Verified locally with pdffonts on a freshly rebuilt v26.4.7 set:
  ko → NotoSansCJKkr-Regular/Bold (was WenQuanYiZenHei)
  ja → NotoSansCJKjp-Regular/Bold (was NotoSansCJKkr fallback)
  th → Loma + Loma-Bold + Loma-Oblique (was WenQuanYiZenHei + partial Loma)
  en → NotoSansCJKkr (Latin coverage)

The v26.4.7 release assets have been re-uploaded with the corrected
build via `gh release upload --clobber`.
diff --git a/.github/workflows/package.yml b/.github/workflows/package.yml
@@ -259,20 +259,30 @@ jobs:
       - name: Install Playwright Chromium
         run: pnpm --filter backend.ai-webui-docs exec playwright install --with-deps chromium
 
-      # Install single-face CJK + Thai fonts. Ubuntu's `fonts-noto-cjk`
-      # ships only a TTC bundle that pdf-lib/fontkit cannot embed, so we
-      # use language-specific single-file packages whose paths are listed
-      # in DEFAULT_CJK_FONT_CANDIDATES (pdf-renderer.ts):
-      #   - fonts-nanum         → /usr/share/fonts/truetype/nanum/NanumBarunGothic.ttf      (ko)
-      #   - fonts-takao-gothic  → /usr/share/fonts/truetype/takao-gothic/TakaoGothic.ttf    (ja)
-      #   - fonts-thai-tlwg     → /usr/share/fonts/opentype/tlwg/Loma.otf or Garuda.ttf     (th)
-      # Languages whose font is missing will be reported as a failure by
+      # PDF rendering uses two distinct font paths that need different fonts:
+      #
+      # 1. Body text — rendered by Chromium from HTML. Resolves the CSS
+      #    font-family (see styles.ts) via fontconfig, so it understands
+      #    .ttc collections. `fonts-noto-cjk` provides "Noto Sans CJK KR/JP/TC"
+      #    which the CSS lists as the canonical CJK body font.
+      #
+      # 2. Header/footer — stamped post-render by pdf-lib, which cannot embed
+      #    .ttc collections. So we additionally install language-specific
+      #    single-face packages whose paths are listed in
+      #    DEFAULT_CJK_FONT_CANDIDATES (pdf-renderer.ts):
+      #      - fonts-nanum         → /usr/share/fonts/truetype/nanum/NanumBarunGothic.ttf  (ko)
+      #      - fonts-takao-gothic  → /usr/share/fonts/truetype/takao-gothic/TakaoGothic.ttf (ja)
+      #      - fonts-thai-tlwg     → /usr/share/fonts/opentype/tlwg/Loma.otf | Garuda.ttf  (th)
+      #
+      # Languages whose pdf-lib font is missing will be reported as a failure by
       # generate-pdf.ts but will not abort the other language renders.
       - name: Install CJK + Thai fonts (best effort)
         run: |
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends \
+            fonts-noto-cjk \
             fonts-nanum fonts-takao-gothic fonts-thai-tlwg || true
+          fc-cache -f || true
 
       # generate-pdf.ts continues past per-language failures and exits
       # non-zero only if *every* requested language failed. Combined with
diff --git a/packages/backend.ai-docs-toolkit/src/styles-web.ts b/packages/backend.ai-docs-toolkit/src/styles-web.ts
@@ -50,7 +50,11 @@ export function generateWebStyles(lang?: string): string {
   --ifm-color-emphasis-1000: #000;
 
   --ifm-font-family-base: system-ui, -apple-system, "Segoe UI", Roboto,
-    Ubuntu, Cantarell, "Noto Sans", "Noto Sans KR", "Noto Sans JP", "Noto Sans Thai",
+    Ubuntu, Cantarell, "Noto Sans",
+    "Noto Sans KR", "Noto Sans CJK KR",
+    "Noto Sans JP", "Noto Sans CJK JP",
+    "Noto Sans TC", "Noto Sans CJK TC",
+    "Noto Sans Thai",
     sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   --ifm-font-family-monospace: "SFMono-Regular", Menlo, Consolas, "Liberation Mono", "Courier New", monospace;
 
diff --git a/packages/backend.ai-docs-toolkit/src/styles.ts b/packages/backend.ai-docs-toolkit/src/styles.ts
@@ -20,7 +20,26 @@ export function generatePdfStyles(theme: PdfTheme, lang?: string): string {
 
 body {
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans",
-    "Noto Sans KR", "Noto Sans JP", "Noto Sans Thai",
+    "Noto Sans KR", "Noto Sans CJK KR",
+    "Noto Sans JP", "Noto Sans CJK JP",
+    "Noto Sans TC", "Noto Sans CJK TC",
+    "Noto Sans Thai",
+    Helvetica, Arial, sans-serif;
+}
+
+/* Per-language font priorities so Chromium picks the language-appropriate
+ * Noto CJK face first (KR/JP/TC differ in kanji/hanja glyph style). The
+ * <html lang="..."> attribute is set by html-builder.ts. */
+:lang(ja) {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans",
+    "Noto Sans JP", "Noto Sans CJK JP",
+    "Noto Sans KR", "Noto Sans CJK KR",
+    Helvetica, Arial, sans-serif;
+}
+
+:lang(th) {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans",
+    "Noto Sans Thai", "Loma", "Garuda",
     Helvetica, Arial, sans-serif;
   font-size: ${theme.baseFontSize};
   line-height: 1.6;
