Localize your docs with variants in GitBook
Learn how to use variants in GitBook to translate and manage different versions of your docs site for multiple languages
Last updated
Was this helpful?
Learn how to use variants in GitBook to translate and manage different versions of your docs site for multiple languages
Last updated
Was this helpful?
This guide will walk you through the process of setting up variants, organizing your content, and ensuring your readers can access the right version of your documentation, in the language they want.
First, you need to create your content and localize it to the various languages you need — and there are a few ways to do it. You can translate part of your content using GitBook AI, or other AI services such as DeepL, ChatGPT or Claude.
Note: You will need to create a space for each translated version of your docs in GitBook. You can then link all your translated spaces to a single docs site.
Each localized version of your documentation will need to be in its own dedicated space. There’s no single right way to create your localized content, and how you do it will depend on the localization process you choose.
However, here’s a quick idea of how the process could look in GitBook:
Make sure you give your space a clear name that’s easy to find and understand — ideally refrencing the name of your primary content and the language you’ve localized for. It’ll make it easier to manage your published spaces later.
Tip: You might consider adding a flag as the space emoji to make it easy to identify and reorganized your spaces at a glance.
Use whichever process you like to translate the content of your space. Be careful about translating code, menu commands and other parts of your docs that may need to remain in your primary language in order to remain useable and correct.
Any formatting (such as cards and tables) will remain as they are in your primary content, so all you should need to worry about is the text itself.
Once you have created all the spaces you need and localized your content, it’s time to set up your docs site in GitBook.
If you have an existing site and are just adding new translations, you can head to your site’s dashboard, click Settings > Structure, and start reading at Step 4.
Your newly-created site will be empty, with no linked content. To add your documentation, click Link and existing space and choose the primary space you want to publish.
This will be the default space when people visit your docs, so make sure to select the space in your primary language.
Click the arrow next to your chosen space to expand it, then click the Add variant button. You can scroll or search through all your spaces — select the space that contains a translated version of your docs to add it as a variant.
Repeat this process for each of the languages you wish to publish. You can reorder your spaces at any time by clicking and dragging the drag handle on the left-hand side of a variant, and set a default by clicking the Actions menu on the right-hand side of the variant.
Now click the Edit variant button. In the Edit menu you can rename your variant — and this name is what will appear in the drop-down menu on your site when users select a language.
Tip: We recommend naming each variant with the language its in, so users can see a list of all the available at a glance. You might also want to rename your default content in the same way.
The structure will look something like this:
Now it’s time to get your docs online! Go back to your site main page and hit Publish to push it live.
You can then visit your published site to take a look at your work. You should see a dropdown menu on your site that lets users select the language they want to read your docs in, like this:
