Creating a new translation

Audience: Writers who would like to create a new Fabric translation.

If the Hyperledger Fabric documentation is not available in your chosen language then why not start a new language translation? It's relatively easy to get started, and creating a new language translation can be a very satisfying activity for you and other Fabric users.

In this topic, we're going to cover:

Introduction

Hyperledger Fabric documentation is being translated into many different languages. For example:

If your chosen language is not available, then the first thing to do is to create a new language workgroup.

Create a new workgroup

It's much easier to translate, maintain, and manage a language repository if you collaborate with other translators. Start this process by adding a new workgroup to the list of international workgroups, using one of the existing workgroup pages as an exemplar.

Document how your workgroup will collaborate; meetings, chat and mailing lists can all be very effective. Making these mechanisms clear on your workgroup page can help build a community of translators.

Then use Rocket chat channels to let other people know you've started a translation, and invite them to join the workgroup.

Create a new translation

Follow these instructions to create your own language repository. Our sample instructions will show you how to create a new language translation for Spanish as spoken in Mexico:

  1. Fork the fabric-docs-i18n repository to your GitHub account.

  2. Clone your repository fork to your local machine:

    git clone git@github.com:YOURGITHUBID/fabric-docs-i18n.git
    
  3. Select the Fabric version you are going to use as a baseline. We recommend that you start with Fabric 2.2 as this is an LTS release. You can add other releases later.

    cd fabric-docs-i18n
    git fetch origin
    git checkout release-2.2
    
  4. Create a local feature branch:

    git checkout -b newtranslation
    
  5. Identify the appropriate two or four letter language code. Mexican Spanish has the language code es_MX.

  6. Update the fabric CODEOWNERS file in the root directory. Add the following line:

    /docs/locale/ex_EX/ @hyperledger/fabric-core-doc-maintainers @hyperledger/fabric-es_MX-doc-maintainers
    
  7. Create a new language folder under docs/locale/ for your language.

    cd docs/locale
    mkdir es_MX
    
  8. Copy the language files from another language folder, for example

    cp -R pt_BR/ es_MX/
    

    Alternatively, you could copy the docs/ folder from the fabric repository.

  9. Customize the README.md file for your new language using this example.

  10. Commit your changes locally:

    git add .
    git commit -s -m "First commit for Mexican Spanish"
    
  11. Push your newtranslation local feature branch to the release-2.2 branch of your forked fabric-docs-i18n repository:

    git push origin release-2.2:newtranslation
    
    
    Total 0 (delta 0), reused 0 (delta 0)
    remote:
    remote: Create a pull request for 'newtranslation' on GitHub by visiting:
    remote:      https://github.com/YOURGITHUBID/fabric-docs-i18n/pull/new/newtranslation
    remote:
    To github.com:ODOWDAIBM/fabric-docs-i18n.git
    * [new branch]      release-2.2 -> newtranslation
    
  12. Connect your repository fork to ReadTheDocs using these instructions. Verify that your documentation builds correctly.

  13. Create a pull request (PR) for newtranslation on GitHub by visiting:

    https://github.com/YOURGITHUBID/fabric-docs-i18n/pull/new/newtranslation

    Your PR needs to be approved by one of the documentation maintainers. They will be automatically informed of your PR by email, and you can contact them via Rocket chat.

  14. On the i18n rocket channel request the creation of the new group of maintainers for your language, @hyperledger/fabric-es_MX-doc-maintainers. Provide your GitHubID for addition to this group.

    Once you've been added to this list, you can add others translators from your workgroup.

Congratulations! A community of translators can now translate your newly-created language in the fabric-docs-i18n repository.

First topics

Before your new language can be published to the documentation website, you must translate the following topics. These topics help users and translators of your new language get started.

  • Fabric front page

    This is your advert! Thanks to you, users can now see that the documentation is available in their language. It might not be complete yet, but its clear you and your team are trying to achieve. Translating this page will help you recruit other translators.

  • Introduction

    This short topic gives a high level overview of Fabric, and because it's probably one of the first topics a new user will look at, it's important that it's translated.

  • Contributions Welcome!

    This topic is vital -- it helps contributors understand what, why and how of contributing to Fabric. You need to translate this topic so that others can help you collaborate in your translation.

  • Glossary

    Translating this topic provides the essential reference material that helps other language translators make progress; in short, it allows your workgroup to scale.

Once this set of topics have been translated, and you've created a language workgroup, your translation can be published on the documentation website. For example, the Chinese language docs are available here.

You can now request, via the i18n rocket channel, that your translation is included on the documentation website.

Translation tools

When translating topics from US English to your international language, it's often helpful to use an online tool to generate a first pass of the translation, which you then correct in a second pass review.

Language workgroups have found the following tools helpful:

Suggested next topics

Once you have published the mandatory initial set of topics on the documentation website, you are encouraged to translate these topics, in order. If you choose to adopt another order, that's fine; you still will find it helpful to agree an order of translation in your workgroup.

  • Key concepts

    For solution architects, application architects, systems architects, developers, academics and students alike, this topic provides a comprehensive conceptual understanding of Fabric.

  • Getting started

    For developers who want to get hands-on with Fabric, this topic provides key instructions to help install, build a sample network and get hands-on with Fabric.

  • Developing applications

    This topic helps developers write smart contracts and applications; these are the core elements of any solution that uses Fabric.

  • Tutorials

    A set of hands-on tutorials to help developers and administrators try out specific Fabric features and capabilities.

  • What's new in Hyperledger Fabric v2.x

    This topic covers the latest features in Hyperledger Fabric.

Finally, we wish you good luck, and thank you for your contribution to Hyperledger Fabric.