Overview

GitBook has Collections. Collections contain Spaces. A Space contains Pages for the documentation. When a Gitbook site has a Collection with multiple Spaces, users can select which space they want to view.

Currently, the Juicebox Gitbook has 1 Space; this space is the entire Juicebox documentation.

To support multiple languages, we must create a space for each language we want to support. These spaces will be located under a single Collection. Users can then chose their language by selecting which Space they wish to use. This is shown in the image below.

To sync GitBook with GitHub, we can create language-specific branches for each language. The existing master branch will contain the English source documentation. Each language-specific branch will contain the translated documentation for each language. Language-specific branches will be protected (meaning they can only be changed via pull requests) and named per the following naming convention: master-{code} (e.g. master-zh).

Each Gitbook space will be synced with the respective language-specific branch in GitHub.

Proof of concept

I have a fork of juice-docs that is deployed here: https://aksolian.gitbook.io/juicebox-i18n/.

An example of Chinese documentation within this fork can be found here: https://aksolian.gitbook.io/juicebox-i18n/v/zh/getting-started/create-a-juicebox-project#di-3-jie-zi-jin-fen-pei

There are 2 branches:

1. master - this branch contains the English docs. It is untouched from the upstream juice-docs.
2. master-zh - this branch contains some Chinese translations.

Roll-out

We will aim to roll out Chinese translations as a first iteration. Once this roll-out is successful, other languages can follow.

In GitHub:

1. Create a branch named master-zh.
2. Add Chinese translations.

In Gitbook: