Skip to content

Add Sphinx navigation, zh_CN translations, and content formatting fixes#261

Merged
semioticrobotic merged 1 commit into
theopensourceway:mainfrom
sanchuanhehe:pr/sphinx-nav-and-translations
May 21, 2026
Merged

Add Sphinx navigation, zh_CN translations, and content formatting fixes#261
semioticrobotic merged 1 commit into
theopensourceway:mainfrom
sanchuanhehe:pr/sphinx-nav-and-translations

Conversation

@sanchuanhehe
Copy link
Copy Markdown
Contributor

@sanchuanhehe sanchuanhehe commented May 21, 2026

Summary

This PR adds files needed by the new production toolchain (discussed in #260) to the editorial source tree:

  • Sphinx navigation files: `index.md` (root) and section `index.md` files with MyST toctree directives, enabling Sphinx to build the guidebook with proper chapter navigation
  • zh_CN gettext catalogs: Full Simplified Chinese translation catalogs under `locales/zh_CN/LC_MESSAGES/`, migrated from the existing `l10n/cn` Markdown with semantic corrections
  • Content formatting fixes: Markdown formatting adjustments for MyST compatibility (list styles, line breaks, footnote references) in several chapter files

These files are currently used by the production repository to build multilingual HTML and PDF outputs. Placing them in the editorial source tree keeps translations and navigation alongside the content they describe, and enables the production repo to reference the guidebook as a submodule without maintaining separate copies.

What this enables

  • The production repo builds HTML/PDF from the guidebook submodule directly
  • Translators can update .po files in the same repo as the source content
  • Sphinx can generate proper toctree navigation matching the GitBook-style chapter hierarchy
  • Future locales (e.g., Japanese) can follow the same locales//LC_MESSAGES/ pattern

Test plan

  • Verify the production repo build succeeds with these changes merged into the submodule
  • Confirm that existing GitBook-based workflows are not affected (index.md files are only used by Sphinx/MyST)
  • Review zh_CN catalog accuracy against the original l10n/cn Markdown

Sphinx navigation:
- Add root index.md with toctree for all sections
- Add section index.md files (getting-started, attracting-users,
  guiding-participants, growing-contributors, measuring-success)

zh_CN translations:
- Add gettext catalogs under locales/zh_CN/LC_MESSAGES/
- Covers all chapters with full translation coverage

Content formatting fixes:
- Fix Markdown formatting for MyST compatibility
- Correct list styles, line breaks, and footnote references
- Fix typos in building-a-strategy.md, community-manager-self-care.md,
  constructing-an-onboarding-experience.md, and others

These changes support the production toolchain described in
theopensourceway/production and discussion theopensourceway#260.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copy link
Copy Markdown
Member

@semioticrobotic semioticrobotic left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me, @sanchuanhehe. Thanks very much for your careful work here, and for keeping the impact on existing editorial workflows as minimal as possible.

Approved and merging.

@semioticrobotic semioticrobotic merged commit 5f0078a into theopensourceway:main May 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants