Re: [Hyperledger Technical WG China] [i18n] Status report on translation of Fabric docs

Yang Cheng

Hi, Brain, 

Thanks for your replay, for now our translating work is mainly for fabric project and Chinese language, and just a dozen translators, so that the workflow is good for us now. We are also looking for a way adopting different projects and manage the updates conveniently, because we also want to translate the docs of other projects like Indy. We have learned the workflow of kubernetes, they also use github for translating jobs, they made scripts to generate github issues automatically, and developed a slack robot to manage the issues. We want to use the same workflow, but Fabric is different with kubernetes, the docs are separated from code repo and showed in a website they developed, not readthedocs. So we have to find other ways and tools, maybe we also have to develop some tools for this job. We will not use Transifex because it is really inefficient for us, translate with text editor and manage the translations with github is more efficient, we will keeping using github for translating until find a better way. 

Now, what we want is :

1. Show the Chinese translations in the official docs page, so that more developers would see the translations, and may attract more translators.

2. Create a new repo in github named “fabric-i18n” or “hyperledger-i18n”, so we can put the docs of different projects into the same repo, like sdk, fabric-ca, Indy projects not only Fabric.

About in-app localization, we won’t do it right now, it is much complex we should change many codes in Fabric, and actually most developers are used to English output, so the translation is not necessary now.



Cheng Yang

Yang Cheng

At 2020-01-17 12:07:40, "Brian Behlendorf" <bbehlendorf@...> wrote:

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!


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:

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 pull request
5.readthedocs is updated automatically upon successful merge
6.periodically pull in updates from Fabric docs in the form of new issues

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

[2] here’s a demonstration website to show how to incorporate multiple github repo into one readthedocs site

Yang Cheng

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

Join to automatically receive all group messages.