Skip to content

fix: guidebook rendering & zh_CN i18n issues (#1-#5)#7

Merged
sanchuanhehe merged 1 commit into
mainfrom
fix/guidebook-rendering-i18n-1-5
Jun 11, 2026
Merged

fix: guidebook rendering & zh_CN i18n issues (#1-#5)#7
sanchuanhehe merged 1 commit into
mainfrom
fix/guidebook-rendering-i18n-1-5

Conversation

@sanchuanhehe

@sanchuanhehe sanchuanhehe commented Jun 11, 2026

Copy link
Copy Markdown
Member

Fixes five rendering/translation defects in the built guidebook. Verified end-to-end with a local build of EN + zh_CN HTML and LaTeX/PDF, and the catalog consistency check (git diff --exit-code -- locales) is idempotent.

Closes #1
Closes #2
Closes #3
Closes #4
Closes #5

#1 — CJK emphasis (**/_) not rendered

CommonMark flanking rules are designed for Latin text, so _斜体_ between CJK characters and **粗体** next to full-width punctuation (e.g. ) were left literal.

  • New tools/sphinx_ext/cjk_emphasis.py: a parse-time markdown-it scanDelims patch that is CJK-aware. Rules only relax when a CJK character is adjacent to the marker, so Latin text (snake_case, English emphasis) is untouched.
  • Parse-level fix → covers source and translations, HTML and PDF.

#2 — GitHub button only pointed at the production repo

  • repository_url / edit / issue buttons now point at theopensourceway/guidebook (editorial content).
  • Added an icon_links entry (wrench icon) to theopensourceway/production (build toolchain).

#3 — Checklist shown as literal [ ] + excessive spacing

  • Enabled MyST colon_fence + tasklist extensions.
  • The extension's checkbox <input> sits inside the translatable paragraph and is dropped in translated output, so the checkbox is drawn with a CSS pseudo-element (and the real input hidden). EN and zh_CN now render identically; list spacing tightened.

#4 — GitBook {% hint %} blocks shown as literal text ⚠️ transitional solution

  • New tools/convert_gitbook.py, run from prepare-source.sh, rewrites {% hint style="..." %} into MyST admonitions in the staging tree only.
  • This is a transitional workaround: it leaves the guidebook submodule untouched so we don't fork editorial content. The proper long-term fix is to convert the syntax upstream in the guidebook repo; once that lands, this script and the corresponding prepare-source.sh step can be removed. Admonition titles are localized automatically via Sphinx's built-in zh_CN catalogs.
  • 📌 Follow-up tracked in Move GitBook {% hint %} conversion upstream into the guidebook repo (remove transitional staging workaround) #8 (move the conversion upstream and remove this workaround).

#5 — Untranslated English in zh_CN community-manager-self-care

Root cause: the translations already existed but were flagged #, fuzzy (so Sphinx ignored them and rendered English), and some still carried stale {% hint %} markers.

  • Unfuzzied 23 valid translations in self-care + 4 in communication-norms, and stripped the stale GitBook markers.
  • Fixed 38 checklist entries that went fuzzy after the [ ] change and dropped the literal [ ] prefix from their msgstr.
  • Added an identical column to tools/i18n/catalog_status.py (per issue suggestion GitBook {% hint %} blocks not rendered — displayed as literal text #4) to surface msgstr == source segments.
  • Result: untranslated = 0, fuzzy = 0 on the affected pages. The remaining identical segments are bibliography citations intentionally kept in English (consistent with the existing translation convention).

Files

  • conf.py — register cjk_emphasis, enable colon_fence/tasklist, repo/icon link options
  • _static/custom.css — tasklist checkbox + spacing
  • tools/sphinx_ext/cjk_emphasis.py (new) — CJK emphasis patch
  • tools/convert_gitbook.py (new) — hint→admonition (transitional)
  • tools/prepare-source.sh — invoke the converter
  • tools/i18n/catalog_status.pyidentical column
  • locales/zh_CN/.../*.po — unfuzzy / strip stale markers / fix prefixes

Fixes five rendering/translation defects in the built guidebook.

#1 CJK emphasis (`**`/`_`) not rendered
  Add tools/sphinx_ext/cjk_emphasis.py, a parse-time markdown-it patch that
  makes emphasis flanking CJK-aware (only relaxes rules when a CJK character
  is adjacent, so Latin text is untouched). Fixes source and translated
  content across HTML and PDF.

#2 GitHub button only pointed at the production repo
  Point repository/edit/issue buttons at theopensourceway/guidebook (editorial
  content) and add an icon link to theopensourceway/production (toolchain).

#3 Checklist rendered as literal `[ ]` with excessive spacing
  Enable MyST colon_fence + tasklist extensions; render the checkbox via CSS
  (the extension's <input> sits inside the translatable paragraph and is lost
  in translated output, so a CSS pseudo-element keeps EN/zh_CN identical) and
  tighten list spacing.

#4 GitBook {% hint %} blocks shown as literal text (transitional solution)
  Add tools/convert_gitbook.py, run from prepare-source.sh, to rewrite
  {% hint %} into MyST admonitions in the staging tree. This is a transitional
  workaround that leaves the guidebook submodule untouched; the proper fix is
  to convert the syntax upstream in the guidebook repo, after which this script
  and step can be removed.

#5 Untranslated English in zh_CN community-manager-self-care
  Root cause: translations existed but were flagged `#, fuzzy` (so Sphinx
  ignored them) and some still carried stale {% hint %} markers. Unfuzzy the
  valid translations, strip stale markers, and fix checklist msgstr that kept a
  literal `[ ] ` prefix. Add an `identical` column to catalog_status.py to
  surface msgstr-equals-source segments. Remaining identical entries are
  citations intentionally kept in English.
@sanchuanhehe sanchuanhehe merged commit 4234af8 into main Jun 11, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment