---
id: translation
title: Translations
---

## Overview

Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users. Top-level pages written with English strings can be easily translated by wrapping any strings you want to translate in a `<translate>` tag. Strings found in the site header and in documentation front matter will also be found by Docusaurus and properly translated. Read on for more details.

## Docusaurus Translation Configurations

To generate example files for translations with Docusuaurus, run the `examples` script with the command line argument `translations`:

```
npm run examples translations
```

This will create the following files in your website folder:

```
pages/en/help-with-translations.js
languages.js
crowdin.yaml
```

The `pages/en/help-with-translations.js` file is the same example help page generated by the `examples` script but now using translations tags that are described below.
The `languages.js` file tells Docusaurus what languages you want to enable for your site.
The `crowdin.yaml` file is used to configure crowdin integration, and should be moved out one level into your project repo.


## How Docusaurus Finds Strings to Translate

Add the following script to your package.json file:
```json
...
"scripts": {
  "write-translations": "docusaurus-write-translations"
},
...
```

Running the script will generate an `i18n/en.json` file containing all the strings that will be translated from English into other languages.

The script will include text from the following places:
  - title strings and category strings in documentation front matter
  - tagline in `siteConfig.js`
  - internal and external header link text strings in `siteConfig.js`

It will also include any strings in any `.js` files in the `pages` folder that are wrapped in a `<translate>` tag. You can also include an optional description attribute to give more context to a translator about how to translate the string.

In addition to these strings in the `i18n/en.json` file, the whole documentation files themselves will be translated.

## How Docusaurus Translates Strings

Docusaurus itself does not do any translation from one language to another. Instead, it uses Crowdin to manage translations and then downloads appropriately translated files from Crowdin. More information on how to set up Crowdin translations later.

## How Docusaurus Uses String Translations

This section provides some more context for how translation works, but is not necessary information for the user to know.

For things like the strings found in the headers and sidebars of pages, Docusaurus references a translated version of `i18n/en.json` (for example, a `i18n/fr.json` file downloaded from Crowdin).

For documentation text itself, fully translated markdown files will be compiled in the same way English documentation markdown files would be.

For other pages, Docusaurus will automatically transform all `<translate>` tags into function calls that will return appropriately translated strings. For each language that is enabled with `languages.js`, Docusaurus will build translated pages using the files in `pages/en` and the language's respective `.json` file in `i18n`.

## Crowdin Set-Up

Create your translation project on [Crowdin](https://www.crowdin.com/). You can use [Crowdin's guides](https://support.crowdin.com/translation-process-overview/) to learn more about the translations work flow.

To automatically get the translations for your files, update the `circle.yml` file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example `circle.yml` file:

```yaml
machine:
  node:
    version: 6.10.3
  npm:
    version: 3.10.10

test:
  override:
    - "true"

deployment:
  website:
    branch: master
    commands:
      # configure git user
      - git config --global user.email "test-site-bot@users.noreply.github.com"
      - git config --global user.name "Website Deployment Script"
      - echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
      # install Docusaurus and generate file of English strings
      - cd website && npm install && npm run write-translations && cd ..
      # crowdin install
      - sudo apt-get install default-jre
      - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
      - sudo dpkg -i crowdin.deb
      # translations upload/download
      - crowdin --config crowdin.yaml upload sources --auto-update -b master
      - crowdin --config crowdin.yaml download -b master
      # build and publish website
      - cd website && GIT_USER=test-site-bot npm run publish-gh-pages
```

The `crowdin` command uses the `crowdin.yaml` file generated with the `examples` script. It should be placed in your project directory to configure how and what files are uploaded/downloaded.

Note that in the `crowdin.yaml` file, `CROWDIN_PROJECT_ID` and `CROWDIN_API_KEY` are environment variables set-up in Circle for your Crowdin project. They can be found in your Crowdin project settings.

Now, Circle will help you automatically get translations prior to building your website. If you wish to use crowdin on your machine locally, you can install the [Crowdin CLI tool](https://support.crowdin.com/cli-tool/) and run the same commands found in the `circle.yaml` file, making sure you actually set the `project_identifier` and `api_key`.