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 2021-01-19 17:26:31 +01:00 committed by GitHub
parent af8dc63202
commit a8ee7fd3e8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
50 changed files with 1469 additions and 102 deletions

View file

@ -125,6 +125,58 @@ const MyComponent = () => {
};
```
### `<Translate/>`
When [localizing your site](./i18n/i18n-introduction.md), the `<Translate/>` component will allow providing **translation support to React components**, such as your homepage.
The translation strings will be extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations) CLI and create a `code.json` translation file in `website/i18n/<locale>`.
:::note
The `<Translate/>` props **must be hardcoded strings**.
It is **not possible to use variables**, or the extraction wouldn't work.
:::
#### Props
- `children`: untranslated string in the default site locale`
- `id`: optional value to use as key in JSON translation files
- `description`: optional text to help the translator
#### Example
```jsx title="src/index.js"
import React from 'react';
import Layout from '@theme/Layout';
// highlight-start
import Translate from '@docusaurus/Translate';
// highlight-end
export default function Home() {
return (
<Layout>
<h1>
{/* highlight-start */}
<Translate
id="homepage.title"
description="The homepage welcome message">
Welcome to my website
</Translate>
{/* highlight-end */}
</h1>
<main>
{/* highlight-start */}
<Translate>My website content</Translate>
{/* highlight-end */}
</main>
</Layout>
);
}
```
## Hooks
### `useDocusaurusContext`
@ -303,6 +355,54 @@ const MyComponent = () => {
};
```
## Functions
### `translate`
The imperative counterpart of the [`<Translate>`](#translate) component.
:::tip
Use the imperative API for the **rare cases** when a **component cannot be used**, such as:
- the `placeholder` props of form input
- the page `title` metadata
:::
```jsx title="src/index.js"
import React from 'react';
import Layout from '@theme/Layout';
// highlight-start
import {translate} from '@docusaurus/Translate';
// highlight-end
export default function Home() {
return (
<Layout
// highlight-start
title={translate({message: 'My page meta title'})}
// highlight-end
>
<input
type="text"
placeholder={
// highlight-start
translate({
message: 'Some input placeholder',
// Optional
id: 'homepage.input.placeholder',
description: 'The homepage input placeholder',
})
// highlight-end
}
/>
</Layout>
);
}
```
## Modules
### `ExecutionEnvironment`