3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-03 12:17:20 +02:00
Code Issues Projects Releases Packages Wiki Activity

Rearrange and provide more information for translations

Browse source
This commit is contained in:
Joel Marcey 2018-03-08 11:10:47 -08:00 • committed by GitHub
parent e8bc81f985
commit e48b6bbf66
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
docs/guides-translation.md
View file

@ -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
<p>
```
> 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.
## 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.