From 5cc47ade89e95ee944a3db03564f0f71b497ae3f Mon Sep 17 00:00:00 2001 From: Frank Li Date: Wed, 9 Aug 2017 17:26:02 -0700 Subject: [PATCH] Small update to translation guide --- docs/translation.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/translation.md b/docs/translation.md index c3deb7ce6c..f05693efc3 100644 --- a/docs/translation.md +++ b/docs/translation.md @@ -3,9 +3,7 @@ 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 `` 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 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 translated by wrapping any strings you want to translate in a `` tag. Other titles and labels will also be found and properly translated. ## Docusaurus Translation Configurations @@ -15,7 +13,7 @@ To generate example files for translations with Docusuaurus, run the `examples` npm run examples translations ``` -This will create the following files in your website folder: +This will create the following files: ``` pages/en/help-with-translations.js @@ -25,7 +23,7 @@ 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. +The `crowdin.yaml` file is used to configure crowdin integration, and is copied out one level into your project repo. ## How Docusaurus Finds Strings to Translate @@ -39,7 +37,7 @@ Add the following script to your package.json file: ... ``` -Running the script will generate an `i18n/en.json` file containing all the strings that will be translated from English into other languages. +Running the script will generate a `website/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 @@ -106,4 +104,18 @@ The `crowdin` command uses the `crowdin.yaml` file generated with the `examples` 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`. +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` in the `crowdin.yaml` file. 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`. + +## Translations and Versioning + +If you wish to have translation and versioning for your documentation, add the following section to the end of your `crowdin.yaml` file: + +```yaml + - + source: '/website/versioned_docs/**/*.md' + translation: '/website/translated_docs/%locale%/**/%original_file_name%' + languages_mapping: *anchor +``` + +Translated, versioned documents will be copied into `website/translated_docs/${language}/${version}/`. +