From e48b6bbf66cfaed6c455b2d527f68a36f8c42048 Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Thu, 8 Mar 2018 11:10:47 -0800 Subject: [PATCH] Rearrange and provide more information for translations --- docs/guides-translation.md | 47 ++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/docs/guides-translation.md b/docs/guides-translation.md index fd959507ff..57d4cc451f 100644 --- a/docs/guides-translation.md +++ b/docs/guides-translation.md @@ -27,15 +27,17 @@ languages.js ../crowdin.yaml ``` -The `pages/en/help-with-translations.js` file includes the same starter help page generated by the `examples` script, but now includes translation tags. +- The `pages/en/help-with-translations.js` file includes the same starter help page generated by the `examples` script, but now includes translation tags. -The `languages.js` file tells Docusaurus what languages you want to enable for your site. By default, we expect English to be enabled. +> 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`. +- The `languages.js` file tells Docusaurus what languages you want to enable for your site. By default, we expect English to be enabled. + +- 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`. ## Translating Your Existing Docs -Your documentation files do not need to be changed or moved to support translations. They will be uploaded to Crowdin to be translated directly. +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. ## Enabling Translations on Pages @@ -62,11 +64,13 @@ You can also include an optional description attribute to give more context to a

``` +> The `` 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 `` 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 `` tags amongst the pure substrings of that string. + ## Gathering Strings to Translate The strings within localized Pages must be extracted and provided to Crowdin. -Add the following script to your package.json file: +Add the following script to your `website/package.json` file, if it does not exist already: ```json ... "scripts": { @@ -113,9 +117,11 @@ Crowdin is a company that provides translation services. For Open Source project 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 translateable language to prevent the creation of `en-US` localization files as this can lead to confusion._ -Your project will need a `crowdin.yaml` file generated. +> 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. -> You will need to install `crowdin-cli`. Please follow the [installation directions](https://support.crowdin.com/cli-tool/). +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` diretory. + +> You will need to install the `crowdin` command line interface. Please follow the [installation directions](https://support.crowdin.com/cli-tool/). 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. @@ -146,7 +152,7 @@ files: You can go [here](https://support.crowdin.com/configuration-file/) to learn more about customizing your `crowdin.yaml` file. -### Manual File Sync +### Setup the Crowdin Scripts 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`.) @@ -154,16 +160,29 @@ You can add the following to your `package.json` to manually trigger crowdin. ```json "scripts": { - "crowdin-upload": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID; - export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml upload sources --auto-update -b master", - "crowdin-download": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID; - export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml download -b master" + "crowdin-upload": "export CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID; + export CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY; crowdin --config ../crowdin.yaml upload sources --auto-update -b master", + "crowdin-download": "export CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID; + export CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY; crowdin --config ../crowdin.yaml download -b master" }, ``` These commands require having an environment variable set with your crowdin project id and api key (`CROWDIN_PROJECT_ID`, `CROWDIN_API_KEY`). You can add them inline like 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`). +> `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`. + +> 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`). + +### Manual File Sync + +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: + +``` +yarn run crowdin-upload +yarn run crowdin-download +``` + +> 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. ### Automated File Sync Using CircleCI @@ -223,5 +242,3 @@ If you wish to have translation and versioning for your documentation, add the f ``` Translated, versioned documents will be copied into `website/translated_docs/${language}/${version}/`. - -> 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.