This has gone without a reply since it was posted so I thought I would add one,

It's terrific to see this energy for expanding the global footprint for Fabric! And for taking such a well researched and thoughtful approach to figuring out how to support the needs of translators efficiently. And your recommendations on bold at the bottom make sense for me. Thank you for writing up the recommendations and the rationale, that is valuable for future teams looking at this. An additional repo makes a ton of sense. I am sure here are good techniques to correlate updates to core docs to a need for updating their translated equivalents.

So far, the TSC seems like it has been happy leaving these questions up to individual projects rather than setting a site-wide standard. But the TSC and others in the community might still want to weigh in on this, and if it looks good, consider adopting it as a common standard across projects, so that it's even easier for volunteers for translations on any project to know how and where to plug in.

One last question: would it make sense for translation bundles for in-app localizations to be done in this -i18n repo, or to be done in the main code repo? I'm guessing the former so that a distribution can easily bundle them all together, and they change much less frequently, but I believe they are as important as translated docs (for projects that use them) to highlight to volunteers.

Again, thanks!

Brian

On January 13, 2020 2:57:48 PM GMT+08:00, Yang Cheng <great_cy_ang@...> wrote:

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@...

--
Sent from my Android device with K-9 Mail. Please excuse my brevity.