Docusaurus allows for easy translation functionality using [Crowdin](https://crowdin.com/). Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a `<translate>` tag. Other titles and labels will also be found and properly translated.
* The `pages/en/help-with-translations.js` file includes the same starter help page generated by the `examples` script, but now includes translation tags.
> Generally, you will use `help-with-translations.js` as a guide to enable translations in your other pages, but not actually commit the file to your repo (i.e., you can delete it). However, if you want a Help page, and you currently do not have one, you can rename this file to `help.js` and use it as a starting point.
* The `crowdin.yaml` file is used to configure Crowdin integration, and is copied up one level into your Docusaurus project repo. If your Docusaurus project resides in `/project/website`, then `crowdin.yaml` will be copied to `/project/crowdin.yaml`.
Your documentation files (e.g., the `.md` files that live in your `docs` directory) do not need to be changed or moved to support translations. They will be uploaded to Crowdin to be translated directly.
> The `<translate>` tag generally works well on pure strings. If you have a string like "Docusaurus currently provides support to help your website use [translations](${siteConfig.baseUrl}docs/${this.props.language}/translation.html)", wrapping the `<translation>` tag around that entire string will cause issues because of the markdown linking, etc. Your options are to not translate those strings, or spread a bunch of `<translate>` tags amongst the pure substrings of that string.
If you want to add additional custom translation strings, or override any of the strings that get produced by the script that creates the `website/i18n/en.json` file, you can add a `website/data/custom-translation-strings.json` file. The file should have form of:
```json
{
"localized-strings": {
"id": "string",
"id2": "string2"
},
"pages-strings" : {
"id3": "string3",
"id4": "string4"
}
}
```
where `localized-strings` represent strings in your documentation content and `pages-strings` represents metadata in your documentation (e.g., title, links, etc).
Here is an example:
```json
{
"_comment": "This file is used to provide custom strings for translations, including overriding defaults",
"localized-strings": {
"translation": "Translations and Localization"
},
"pages-strings" : {
"Help Translate|recruit community translators for your project": "Help Us Translate"
}
}
```
See the generated `website/i18n/en.json` for an example.
Docusaurus itself does not do any translation from one language to another. Instead, it integrates [Crowdin](https://crowdin.com/) to upload translations and then downloads the appropriately translated files from Crowdin.
A Docusaurus site has many strings used throughout it that require localization. However, maintaining a list of strings used through out a site can be laborious. Docusaurus simplifies this by centralizing strings.
The header navigation, for example can have links to 'Home' or your 'Blog'. This and other strings found in the headers and sidebars of pages are extracted and placed into `i18n/en.json`. When your files are translated, say into Spanish, a `i18n/es-ES.json` file will be downloaded from Crowdin. Then, when the Spanish pages are generated, Docusaurus will replace the English version of corresponding strings with translated strings from the corresponding localized strings file (e.g. In a Spanish enabled site 'Help' will become 'Ayuda').
For other pages, Docusaurus will automatically transform all `<translate>` tags it finds into function calls that return the translated strings from the corresponding localized file _`locale.json`_.
Create your translation project on [Crowdin](https://crowdin.com/). You can use [Crowdin's guides](https://support.crowdin.com/translation-process-overview/) to learn more about the translations work flow. _We suggest that you deselect and do not include "English" as a translatable language to prevent the creation of `en-US` localization files as this can lead to confusion._
> Ensure in your Crowdin settings, in the Translations section, that "Duplicate Strings" are set to ["Hide - all duplicates will share the same translation"](https://support.crowdin.com/api/create-project/). This setting will ensure that identical strings between versions share a single translation.
Your project will need a `crowdin.yaml` file generated. If you ran `yarn examples translations` or `npm run examples translations`, this file was created for you on the same level as your `website` directory.
The example below can be automatically generated by the Docusaurus cli with the `examples` script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.
Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.
You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in `/docs` as well as translatable strings in `website/i18n/en.json`. (These strings can be generated by running `yarn write-translations`.)
You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:
> `YOUR_CROWDIN_PROJECT_ID` is the name of your Crowdin project. e.g., for https://crowdin.com/project/docusaurus/, that variable would be set to `docusaurus`. `YOUR_CROWDIN_API_KEY` is a unique key that is like a password. You can find it in the `API` tab of your Crowdin project's `Settings`.
> These commands require having an environment variable set with your Crowdin project id and api key (`CROWDIN_PROJECT_ID`, `CROWDIN_API_KEY`). You can preface them inline as done above or add them permanently to your `.bashrc` or `.bash_profile`.
> If you run more than one localized Docusaurus project on your computer, you should change the name of the environment variables to something unique (`CROWDIN_PROJECTNAME_PROJECT_ID`, `CROWDIN_PROJECTNAME_API_KEY`).
> Since the files are generated, you do not need to have any files in your `website/i18n` or `website/translated_docs` directory as part of your repo. So you can can add `website/i18n/*` and `website/translated_docs` to your `.gitignore` file.
First, 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:
- 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. The provided `crowdin.yaml` file will copy translated documents into `website/translated_docs/`, and translated versions of the `i18n/en.json` strings file will into `i18n/${language}.json`.
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. The only difference is that you must set `project_identifier` and `api_key` values in the `crowdin.yaml` file since you will not have Circle environment variables set up.
