fix: guidebook rendering & zh_CN i18n issues (#1-#5)#7
Merged
Conversation
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.
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 renderedCommonMark flanking rules are designed for Latin text, so
_斜体_between CJK characters and**粗体**next to full-width punctuation (e.g.:) were left literal.tools/sphinx_ext/cjk_emphasis.py: a parse-time markdown-itscanDelimspatch 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.#2 — GitHub button only pointed at the production repo
repository_url/ edit / issue buttons now point attheopensourceway/guidebook(editorial content).icon_linksentry (wrench icon) totheopensourceway/production(build toolchain).#3 — Checklist shown as literal
[ ]+ excessive spacingcolon_fence+tasklistextensions.<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⚠️ transitional solution
{% hint %}blocks shown as literal texttools/convert_gitbook.py, run fromprepare-source.sh, rewrites{% hint style="..." %}into MyST admonitions in the staging tree only.guidebooksubmodule untouched so we don't fork editorial content. The proper long-term fix is to convert the syntax upstream in theguidebookrepo; once that lands, this script and the correspondingprepare-source.shstep can be removed. Admonition titles are localized automatically via Sphinx's built-in zh_CN catalogs.#5 — Untranslated English in zh_CN
community-manager-self-careRoot cause: the translations already existed but were flagged
#, fuzzy(so Sphinx ignored them and rendered English), and some still carried stale{% hint %}markers.[ ]change and dropped the literal[ ]prefix from theirmsgstr.identicalcolumn totools/i18n/catalog_status.py(per issue suggestion GitBook {% hint %} blocks not rendered — displayed as literal text #4) to surfacemsgstr == sourcesegments.identicalsegments are bibliography citations intentionally kept in English (consistent with the existing translation convention).Files
conf.py— registercjk_emphasis, enablecolon_fence/tasklist, repo/icon link options_static/custom.css— tasklist checkbox + spacingtools/sphinx_ext/cjk_emphasis.py(new) — CJK emphasis patchtools/convert_gitbook.py(new) — hint→admonition (transitional)tools/prepare-source.sh— invoke the convertertools/i18n/catalog_status.py—identicalcolumnlocales/zh_CN/.../*.po— unfuzzy / strip stale markers / fix prefixes