mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-04 01:09:20 +02:00
docs(v2): i18n doc + polish (#4014)
* add some initial i18n doc * i18n doc progress * i18n tutorial progress * i18n tutorial progress * polish Crowdin docs * i18n sidebar in guides * polish crowdin doc * update Crowdin doc a bit * fix annoying relative link to global site resource in template (breaks i18n tutorial) * template: use simpler export for homepage * add markdown page example * rename mdx.md to interactiveDoc.mdx * update bootstrap/facebook templates too * sync init template package scripts * add slug frontmatter doc * improve i18n doc * complete i18n doc * temporarily enable the localeDropdown * doc typo * improve the i18n doc * Add Git i18n doc * add missing "--" for npm run options (unfortunately they don't get stripped by npm2yarn, and are required foor npm) * improve a bit the Crowdin doc
This commit is contained in:
Sébastien Lorber
GitHub
parent
af8dc63202
commit
a8ee7fd3e8
50 changed files with 1469 additions and 102 deletions
173
website/docs/i18n/i18n-git.md
Normal file
173
website/docs/i18n/i18n-git.md
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
---
|
||||
id: git
|
||||
title: i18n - Using git
|
||||
sidebar_label: Using Git
|
||||
slug: /i18n/git
|
||||
---
|
||||
|
||||
A **possible translation strategy** is to **version control the translation files** to Git (or any other [VCS](https://en.wikipedia.org/wiki/Version_control)).
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
This strategy has advantages:
|
||||
|
||||
- **Easy to get started**: just add the `i18n` folder to Git
|
||||
- **Easy for developers**: Git, GitHub and pull-requests are mainstream developer tools
|
||||
- **Free** (or without any additional cost, assuming you already use Git)
|
||||
- **Low friction**: does not require signing-up to an external tool
|
||||
- **Rewarding**: contributors are happy to have a nice contribution history
|
||||
|
||||
Using Git also present some shortcomings:
|
||||
|
||||
- **Hard for non-developers**: they do not master Git and pull-requests
|
||||
- **Hard for professional translations**: they are used to SaaS translation softwares and advanced features
|
||||
- **Hard to maintain**: you have to keep the translated files **in sync** with the untranslated files
|
||||
|
||||
:::note
|
||||
|
||||
Some **large-scale technical projects** (ReactJS, VueJS, Gatsby, TypeScript, Nuxt...) use Git for translations.
|
||||
|
||||
Refer to the [Docusaurus i18n RFC](https://github.com/facebook/docusaurus/issues/3317) for our notes and links studying these systems.
|
||||
|
||||
:::
|
||||
|
||||
## Git tutorial
|
||||
|
||||
This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
|
||||
|
||||
### Prepare the Docusaurus site
|
||||
|
||||
Initialize a new Docusaurus site:
|
||||
|
||||
```bash
|
||||
npx @docusaurus/init@latest init website classic
|
||||
```
|
||||
|
||||
Add the site configuration for the French language:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
i18n: {
|
||||
defaultLocale: 'en',
|
||||
locales: ['en', 'fr'],
|
||||
},
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
items: [
|
||||
// ...
|
||||
{
|
||||
type: 'localeDropdown',
|
||||
position: 'left',
|
||||
},
|
||||
// ...
|
||||
],
|
||||
},
|
||||
},
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
Translate the homepage:
|
||||
|
||||
```jsx title="src/index.js"
|
||||
import React from 'react';
|
||||
import Translate from '@docusaurus/Translate';
|
||||
import Layout from '@theme/Layout';
|
||||
|
||||
export default function Home() {
|
||||
return (
|
||||
<Layout>
|
||||
<h1 style={{margin: 20}}>
|
||||
<Translate description="The homepage main heading">
|
||||
Welcome to my Docusaurus translated site!
|
||||
</Translate>
|
||||
</h1>
|
||||
</Layout>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Initialize the `i18n` folder
|
||||
|
||||
Use the [write-translations](../cli.md#docusaurus-write-translations) CLI command to initialize the JSON translation files for the French locale:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run write-translations -- --locale fr
|
||||
|
||||
1 translations written at i18n/fr/code.json
|
||||
11 translations written at i18n/fr/docusaurus-theme-classic/footer.json
|
||||
4 translations written at i18n/fr/docusaurus-theme-classic/navbar.json
|
||||
3 translations written at i18n/fr/docusaurus-plugin-content-docs/current.json
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Use the `--messagePrefix '(fr) '` option to make the untranslated strings stand out.
|
||||
|
||||
`Hello` will appear as `(fr) Hello` and makes it clear a translation is missing.
|
||||
|
||||
:::
|
||||
|
||||
Copy your untranslated Markdown files to the French folder:
|
||||
|
||||
```
|
||||
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current
|
||||
cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current
|
||||
|
||||
mkdir -p i18n/fr/docusaurus-plugin-content-blog
|
||||
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog
|
||||
|
||||
mkdir -p i18n/fr/docusaurus-plugin-content-pages
|
||||
cp -r pages/**.md i18n/fr/docusaurus-plugin-content-pages
|
||||
cp -r pages/**.mdx i18n/fr/docusaurus-plugin-content-pages
|
||||
```
|
||||
|
||||
Add all these files to Git.
|
||||
|
||||
### Translate the files
|
||||
|
||||
Translate the Markdown and JSON files in `i18n/fr` and commit the translation.
|
||||
|
||||
You should now be able to start your site in French and see the translations:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run start -- --locale fr
|
||||
```
|
||||
|
||||
You can also build the site locally or on your CI:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run build
|
||||
# or
|
||||
npm run build -- --locale fr
|
||||
```
|
||||
|
||||
### Repeat
|
||||
|
||||
Follow the same process for each locale you need to support.
|
||||
|
||||
## Maintain the translations
|
||||
|
||||
Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents.
|
||||
|
||||
### Markdown translations
|
||||
|
||||
When an untranslated Markdown document is edited, it is **your responsibility to maintain the respective translated files**, and we unfortunately don't have a good way to help you do so.
|
||||
|
||||
To keep your translated sites consistent, when the `website/docs/doc1.md` doc is edited, you need **backport these edits** to `i18n/fr/docusaurus-plugin-content-docs/current/doc1.md`.
|
||||
|
||||
### JSON translations
|
||||
|
||||
To help you maintain the JSON translation files, it is possible to run again the [write-translations](../cli.md#docusaurus-write-translations) CLI command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run write-translations -- --locale fr
|
||||
```
|
||||
|
||||
New translation will be appended, and existing ones will not be overridden.
|
||||
|
||||
:::tip
|
||||
|
||||
Reset your translations with the `--override` option.
|
||||
|
||||
:::
|
||||
Loading…
Add table
Add a link
Reference in a new issue