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：


  1. 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
  2. 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. 
  3. A translation tool. We prefer transfex.com. Because,
    1. it is free for open source projects. The paid account has a statistics report,  but it is fine without reports.
    2. More importantly,  it is very collaborative,  translators can working simultaneously, translating, reviewing, etc. 
    3. It provides a CLI tx, like git, contributors can use tx to pull from/push to transfex
  4. 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. 

How To

References


Closure

Reviewed By

5 Comments

  1. Gari Singh

    Not exactly sure why this is coming to the TSC.  This seems to be specifically about translating Fabric documentation to other languages.

    Are you asking Hyperledger to provide something here?

  2. Arnaud J Le Hors

    Looking at the history of this page I see that this is nothing new. Ry Jones why did you ask for TSC members to review this? Housekeeping?

    1. Ry Jones

      Yes, housekeeping. These three proposals were left in unfinished state, or were using the old format with the previous TSC list.

  3. Hart Montgomery

    This is a great effort, but I'm not sure that it fits best as a project, which is supposed to be a coding effort.

    Can we find some good way to organize documentation efforts?

  4. Zhenhua Zhao

    After discussing with translation volunteers in TWGC,  we decided to use github to maintain fabric document, as github is able to track everyone's contributing.