Dear Hyperledger community,

We are a small group of volunteers that have been translating Fabric docs to Chinese since 2018. We’d like to share our current status and rationale behinds some decisions for your reference.

Tool selection

We initially started off using github, since it’s familiar to most of developers, and other projects like k8s have been doing the same. The workflow roughly looks like this:

Admins:

1.create branches in `hyperledger-labs/fabric-docs-cn` following Fabric release tags, for example `1.4.2_zh-CN`

2.populated Github issues with untranslated docs

3.assign issues to translators upon request

4.review pull request

5.readthedocs is updated automatically upon successful merge

6.periodically pull in updates from Fabric docs in the form of new issues

Translators:

1.browse Github issues looking for unassigned issues

2.assign issue by commenting on it

3.translate and submit pull request

This workflow had served us well for a small group of contributors. Later on, translation tools, in particular Zanata and Transifex, were proposed by community members, and we decided to give them a try. However, several major drawbacks of Transifex were observed after months of trial:

1.slow access in this region, resulting in bad user experience

2.intermediate files (.po) loses annotations during conversion, resulting in bad formats

3.no commit sign-off when eventually pushed to github

Therefore, we went back to Github. However, this does not mean we rule out the option of using professional tool, which obviously has its own advantages. Our current focus is to get things done and keep handful of contributors happy. When the time comes that Github becomes bottleneck (either due to increase of volunteers, or number of languages being translated to), we are definitely open for reassessment of tooling.

Location of translated docs

It was proposed to separate docs from Fabric code repo, which can co-exist with translations, similar to k8s [1]. Although the proposal was turned down for solid reasons, and we are happily informed that readthedocs actually supports multiple Github repo setup [2]. This is so far the least invasive option to incorporate non-English docs into main site.

We do not think putting translated docs into Fabric core repo is a good idea, even with fine-grained maintainer-ship in place. The PR page would be overwhelmed by foreign characters and we are no longer able to track tasks with Github issues. Besides, it doesn’t really buy us anything beyond one less repo.

To avoid creating new repo for each language that people are interested in translation, we could also setup a repo `Fabric-i18n` containing them as separate directories, e.g. `zh`, `es`, `de`, etc.

This is how things get done today and we definitely welcome any suggestion and feedback. As the number of volunteers and languages grow, we believe a standardized process will emerge.

Thank you,

Cheng Yang

[1] https://github.com/kubernetes/website/tree/master/content

[2] here’s a demonstration website to show how to incorporate multiple github repo into one readthedocs site https://stone-fabric.readthedocs.io/zh/release-1.4_zh-cn/

--

程阳

Yang Cheng

great_cy_ang@...