Project Identifier
Support multi-language to help different language speakers learn and use hyperledger fabric at the same documentation website.
Sponsor(s)
Rich Zhao, zhao.zhenhua@gmail.com
Technical Working Group China(TWGC) has been working for a long time to translate fabric documentation, so far we found it is the best way to maintain documentation.
Abstract
Help different language speakers learn fabric in their own language.
Context
Dependent Projects
Motivation
Hyperledger Fabric documentation is written in English. For those contributors whose native language is not English, they have difficulty contributing to or using hyperledger projects. If the documentation and log messages in software code can be translated into their own native language, it will help build a larger community of contributors and users.
Technical Working Group China has been working for a long time to translate fabric documentation, we use a separate repo to host the documentation but if we can use the same website as the English documentation, it would be more official and convenient for users to use.
Besides, Chinese, we do see other languages are required too.
Status
TWGC has translated about half of fabric v2 documentation with the current solution, it is available at https://fabric-documentations.readthedocs.io/en/latest/
Solution
The solution needs：
- documentation manage framework, sphinx which Fabric is using. Fabric English documentation uses Sphinx v1.7 to manage documentation materials, like .rst, .md files, and the structure layout and build to final output format HTML, pdf, ePUB, etc. Sphinx is a documentation framework based on python, we need to upgrade sphinx to version 2 for more compatible. It has been done through https://gerrit.hyperledger.org/r/c/fabric/+/31667
- A repo to store documentation material and collaborate among contributors. Fabric English documentation uses the same repo as fabric code, it is okay for other languages to use the same existing repo, but as the documentation doesn't share the update release pace as code, it is better to use a separate repo to host ALL documentation materials. All means do NOT separate other language documentation from English documentation, as others are translated from English. Translators/contributors need to monitor English status.
- A translation tool. We prefer transfex.com. Because,
- it is free for open source projects. The paid account has a statistics report, but it is fine without reports.
- More importantly, it is very collaborative, translators can working simultaneously, translating, reviewing, etc.
- It provides a CLI tx, like git, contributors can use tx to pull from/push to transfex
- readthedocs account to host the documentation. Fabris is using it, just need to merge other languages into it.
For more detail refer to:
Efforts and Resources
Suggest using a separate repo to host all documentation material.