Request: Chinese translation mirror for single-cell best practices

[UniqJade]

Hi maintainers,

Thank you for maintaining Single-cell best practices. I have created a Simplified Chinese translation mirror of the rendered website to make the material easier to access for Chinese-speaking readers.

Mirror:

• Repository: https://github.com/UniqJade/single-cell-best-practices-zh
• Website: https://uniqjade.github.io/single-cell-best-practices-zh/
• Source project: https://github.com/theislab/single-cell-best-practices
• Original website: https://www.sc-best-practices.org/

The mirror is based on the rendered static site structure and preserves the original chapter organization, citations, assets, and attribution. I include the Apache-2.0 license and clearly state that this is an unofficial community translation.

I do not intend to imply official endorsement. If you are not comfortable with this public mirror, I will make the repository private or take it down, and I am happy to follow your preferred attribution, disclaimer, or publishing policy.

I would like to ask:

1. Are you comfortable with this Chinese translation mirror being published publicly?
2. Do you have any preferred attribution/disclaimer text?
3. If the mirror looks acceptable, would you consider linking it from the README or documentation as a community translation?

I am happy to adjust the wording, repository structure, or attribution to match your preference.

Thanks!

[UniqJade]

A quick follow-up, for full transparency about what the mirror currently includes:

1. Full-book PDF + offline bundle. Besides the website, I published a pre-release on the mirror repo containing a merged Simplified-Chinese PDF of the whole book (~1044 pages, generated from the rendered pages) and an offline copy of the static site. Release: https://github.com/UniqJade/single-cell-best-practices-zh/releases/tag/0.1.0-zh (marked as a pre-release; the Apache-2.0 license is included).

2. On-page disclaimer added. While waiting for your feedback, I added a persistent banner to the top of every page of the mirror, clearly stating that it is an unofficial community machine translation, that it is not affiliated with or endorsed by the original authors, that the English original is authoritative, and linking back to https://www.sc-best-practices.org/ — so there is no impression of official endorsement.

As mentioned in my original post, I'm glad to adjust the wording/attribution, remove the PDF, or make the repository private / take it down entirely if you'd prefer. Just let me know what works best for you, and thanks again for the book!

[Zethson]

I'll answer on Monday but I can already tell you that I fully support this effort.

Thank you very much!

[UniqJade]

Thank you so much, that really means a lot! 🙏 I'll keep an eye out for your fuller reply on Monday and am happy to adjust the attribution, disclaimer, or repo setup to match whatever you and the team prefer — and to coordinate if you'd ever like it linked as a community translation. Thanks again for the book and for being so welcoming.

[Zethson]

Thank you very much for the handwritten proposal and idea! I'd love it if we can make the book more accessible to researchers in China and we should totally find the best way to do this.

A few notes:

1. The book is currently undergoing major developments both in content but also in infrastructure. We're moving to Jupyter book v2 which will have minor impact on how we're building the book and what it looks like @seohyonkim .
2. As the content changes, I think we need to discuss how you're planning to keep the Chinese translation up to date. How did you create it in the first place? Is it possible to just rerun a tool/script to regularly translate all chapters? I think the challenge for you is to ensure that you always rerun the notebooks when changes were made to them because otherwise the output becomes stale & wrong.
3. I'd love it if we could find a way to have the Chinese community also interact with us here. If Chinese readers find issues or have suggestions, I'd love to know. I think our goal should be to increase the interactions between the Western and Chinese researchers and not create two bubbles.
4. I also wonder whether these should be two separate repositories or we jointly work together on a version here using an approach like https://github.com/orgs/executablebooks/discussions/220#discussioncomment-3284310 (note that Jupyter book v2 might change this workflow). Would it be possible for you to please explore whether it'd be reasonable and possible to add the chinese text into this repository? I fear that it'd be a bad idea because we're not just talking about a few text files but actual jupyter notebooks that also need to be executed.
5. If we can't make it work to have everything in one place with a language selector on the website, I am happy to link to your version as long as you find a way to keep it up to date.

Thank you!

[UniqJade]

Thank you so much for the thoughtful, detailed response, @Zethson — the encouragement and the concrete points are exactly what I was hoping to discuss. Let me take them in turn.

1. Jupyter Book v2 migration. Good to know, and I see you've opened #401 to track it. Since my pipeline operates on the rendered static HTML rather than the source notebooks, a move to the MyST engine will change the rendered structure/styling, so I'll need to adapt my build scripts once the migration lands. I haven't dug into the v2 internals yet — I'll study the v2 migration tracked in #401 properly when I'm back and re-run my pipeline against the new output. Happy to coordinate timing with you and @seohyonkim.

2. Keeping the translation up to date. It's a repeatable, scripted pipeline: pull the upstream rendered HTML → machine-translate as a base layer (local offline engine, no external API dependency) → apply a curated override cache (currently ~5,100 human-curated corrections, with LLM assistance for review) → run QA (terminology checks, English-leak detection, link reconciliation).

The important part for your concern: the pipeline never re-executes notebooks — it only translates the visible prose. Code cells, outputs, figures, equations, citations, and dataset/parameter names are preserved verbatim from upstream, so they always match what you rendered and can't be corrupted or mistranslated. The overrides are keyed by source text, so when upstream changes, unchanged text reuses reviewed translations automatically and only genuinely new or changed text needs fresh translation. The honest limitation is therefore freshness, not correctness — and that's just "how recently did I re-run the pipeline." I'm planning a GitHub Action that detects upstream changes and flags exactly which chapters need re-translation, and I'm improving the "translate only the changed parts" step so it stays high-quality with minimal manual work. Happy to discuss what cadence makes sense.

3. Chinese community interaction. Completely agree — the goal is to make the mirror a gateway into this community, not a wall around a separate one. Concretely: a prominent link on every mirror page pointing readers to this repo's Issues/Discussions; a note encouraging Chinese-speaking readers to participate upstream (in English where they can); and I'll triage issues raised on the mirror and cross-post the relevant content/science ones here, translating where needed.

4. Separate repos vs. one repo. The executablebooks#220 thread is helpful context, and I think your intuition is right that merging is hard at this stage. My pipeline translates rendered output, not source notebooks. Even with the gettext/.po workflow from that thread — which keeps a single source and stores translations separately, so it isn't about forking notebooks — the notebooks would still need to be executed per language on every build, and the translatable strings would have to track ongoing code/content changes. That's exactly the execution burden you flagged. By contrast, translating the rendered output sidesteps execution entirely: the code and results always match what you've already run upstream. I'm very open to exploring a monorepo approach once v2 settles: if v2 brings native i18n support (e.g. MyST locale files), that could change the picture significantly. Until then, separate repos with linking (your point 5) looks like the most practical path.

5. Linking. And if linking is where we land — whether as an interim step or the longer-term arrangement — that would be very welcome. I'll keep the mirror up to date and clearly attributed so it's a resource you're comfortable pointing readers to, and I'd be glad to draft a README PR with suggested wording, or leave the phrasing entirely to you.

One timing note: I'll be travelling to Hong Kong next week, so I won't be able to start the exploration work until about a week from now. I wanted to reply now to keep momentum, and I'll pick up the investigation (v2 compatibility, the community-interaction setup, the in-repo feasibility) as soon as I'm back. Thanks again for being so welcoming and for thinking this through together.

[UniqJade]

Thanks again for the thoughtful pointers! Following up on my June 15 reply — I'm back and have now completed the v2 investigation I mentioned. Here's what I found:

1. Jupyter Book v2 / MyST. I tested a local build against feature/jupyter-book-v2. The v2 output replaces rendered HTML with a React SPA backed by MyST JSON AST files — so my current HTML post-processing approach won't carry over. The good news: a v2 pipeline operating directly on the MyST JSON layer (translating only natural-language text nodes, leaving code, math, URLs, xrefs, and notebook outputs untouched) works in proof-of-concept.

2. Keeping the translation up to date. The pipeline never re-executes notebooks — it only translates visible prose. Reviewed manual overrides are the highest-priority source of truth; unchanged source text reuses cached translations automatically; and a change report flags what's new. This delta approach keeps the mirror fresh without adding CI burden to your repo.

3. Chinese community interaction. Translation-specific issues stay in the mirror repo. Scientific/code issues that affect the original material will be triaged and cross-posted here so the main project benefits from the feedback.

4. Separate repos vs. one repo. The executablebooks gettext thread is helpful context but tailored to the older Sphinx/v1 model. I agree merging would add real build complexity around executed notebooks. An external mirror is the most practical path for now. I'm open to revisiting if v2 introduces native i18n support.

5. Linking. Once the v2 version is stable, I'd be happy to open a small PR suggesting wording like "Read the Chinese translation." Until then, I'll keep refining the mirror pipeline on my side.

Thanks again!

[Zethson]

Sounds good! Then I'll get back to you when the V2 version is merged & released. Then we can happily add a note that points to your mirror. @seohyonkim

Thank you!

[Zethson]

Quick update: We've now merged an initial version of jupyter book v2. I'd still suggest to wait a few more weeks till we can be sure that everything is stable and works.

[UniqJade]

Thanks for the update — that’s great news! I’ll wait a few more weeks as you suggested. Please feel free to ping me when you think it’s ready.