Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: normalize usage of placeholders #6142

Merged
merged 1 commit into from
Dec 21, 2021
Merged

docs: normalize usage of placeholders #6142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion website/docs/api/plugin-methods/i18n-lifecycles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Plugins declare the JSON translation files they want to use.

Returns translation files `{path: string, content: ChromeI18nJSON}`:

- `path`: relative to the plugin localized folder `i18n/<locale>/pluginName`. Extension `.json` should be omitted to remain generic.
- `path`: relative to the plugin localized folder `i18n/[locale]/[pluginName]`. Extension `.json` should be omitted to remain generic.
- `content`: using the Chrome i18n JSON format.

These files will be written by the [`write-translations` CLI](../../cli.md#docusaurus-write-translations-sitedir) to the plugin i18n subfolder, and will be read in the appropriate locale before calling [`translateContent()`](#translateContent) and [`translateThemeConfig()`](#translateThemeConfig)
Expand Down
8 changes: 4 additions & 4 deletions website/docs/api/plugins/plugin-content-blog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,15 +264,15 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.

### Translation files location {#translation-files-location}

- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>`
- **Base path**: `website/i18n/[locale]/docusaurus-plugin-content-blog`
- **Multi-instance path**: `website/i18n/[locale]/docusaurus-plugin-content-blog-[pluginId]`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-blog`

### Example file-system structure {#example-file-system-structure}

```bash
website/i18n/<locale>/docusaurus-plugin-content-blog
website/i18n/[locale]/docusaurus-plugin-content-blog
│
│ # translations for website/blog
├── authors.yml
Expand Down
8 changes: 4 additions & 4 deletions website/docs/api/plugins/plugin-content-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -302,15 +302,15 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.

### Translation files location {#translation-files-location}

- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-docs`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>`
- **Base path**: `website/i18n/[locale]/docusaurus-plugin-content-docs`
- **Multi-instance path**: `website/i18n/[locale]/docusaurus-plugin-content-docs-[pluginId]`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-docs/<version>`
- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]`

### Example file-system structure {#example-file-system-structure}

```bash
website/i18n/<locale>/docusaurus-plugin-content-docs
website/i18n/[locale]/docusaurus-plugin-content-docs
│
│ # translations for website/docs
├── current
Expand Down
8 changes: 4 additions & 4 deletions website/docs/api/plugins/plugin-content-pages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,15 +122,15 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.

### Translation files location {#translation-files-location}

- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-pages-<pluginId>`
- **Base path**: `website/i18n/[locale]/docusaurus-plugin-content-pages`
- **Multi-instance path**: `website/i18n/[locale]/docusaurus-plugin-content-pages-[pluginId]`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-pages`

### Example file-system structure {#example-file-system-structure}

```bash
website/i18n/<locale>/docusaurus-plugin-content-pages
website/i18n/[locale]/docusaurus-plugin-content-pages
│
│ # translations for website/src/pages
├── first-markdown-page.md
Expand Down
4 changes: 2 additions & 2 deletions website/docs/api/themes/theme-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -880,15 +880,15 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first.

### Translation files location {#translation-files-location}

- **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>`
- **Base path**: `website/i18n/[locale]/docusaurus-theme-[themeName]`
- **Multi-instance path**: N/A
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations-sitedir)
- **Markdown files**: N/A

### Example file-system structure {#example-file-system-structure}

```bash
website/i18n/<locale>/docusaurus-theme-classic
website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
Expand Down
2 changes: 1 addition & 1 deletion website/docs/blog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -328,7 +328,7 @@ authors:
The configuration file can be localized, just create a localized copy of it at:

```bash
website/i18n/{{locale}}/docusaurus-plugin-content-blog/authors.yml
website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
```

</details>
Expand Down
8 changes: 4 additions & 4 deletions website/docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,11 +66,11 @@ module.exports = {

When it sees a plugin / theme / preset name, it tries to load one of the following, in that order:

- `{name}`
- `@docusaurus/{type}-{name}`
- `docusaurus-{type}-{name}`,
- `[name]`
- `@docusaurus/[moduleType]-[name]`
- `docusaurus-[moduleType]-[name]`,

where `type` is one of `'preset'`, `'theme'`, `'plugin'`, depending on which field the module name is declared in. The first module name that's successfully found is loaded.
where `moduleType` is one of `'preset'`, `'theme'`, `'plugin'`, depending on which field the module name is declared in. The first module name that's successfully found is loaded.

If the name is scoped (beginning with `@`), the name is first split into scope and package name by the first slash:

Expand Down
2 changes: 1 addition & 1 deletion website/docs/docusaurus-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ export default function VisitMyWebsiteMessage() {

When [localizing your site](./i18n/i18n-introduction.md), the `<Translate/>` component will allow providing **translation support to React components**, such as your homepage. The `<Translate>` component supports [interpolation](#interpolate).

The translation strings will be extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and create a `code.json` translation file in `website/i18n/<locale>`.
The translation strings will be extracted from your code with the [`docusaurus write-translations`](./cli.md#docusaurus-write-translations-sitedir) CLI and create a `code.json` translation file in `website/i18n/[locale]`.

:::note

Expand Down
8 changes: 4 additions & 4 deletions website/docs/guides/creating-pages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,10 +97,10 @@ You can use the full power of React in Markdown pages too, refer to the [MDX](ht

If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example:

- `/src/pages/index.js` → `<baseUrl>`
- `/src/pages/foo.js` → `<baseUrl>/foo`
- `/src/pages/foo/test.js` → `<baseUrl>/foo/test`
- `/src/pages/foo/index.js` → `<baseUrl>/foo/`
- `/src/pages/index.js` → `[baseUrl]`
- `/src/pages/foo.js` → `[baseUrl]/foo`
- `/src/pages/foo/test.js` → `[baseUrl]/foo/test`
- `/src/pages/foo/index.js` → `[baseUrl]/foo/`

In this component-based development era, it is encouraged to co-locate your styling, markup and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following:

Expand Down
6 changes: 3 additions & 3 deletions website/docs/guides/docs/docs-multi-instance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,9 +150,9 @@ The default plugin instance will use these paths:

The other plugin instances (with an `id` attribute) will use these paths:

- `website/<pluginId>_versions.json`
- `website/<pluginId>_versioned_docs`
- `website/<pluginId>_versioned_sidebars`
- `website/[pluginId]_versions.json`
- `website/[pluginId]_versioned_docs`
- `website/[pluginId]_versioned_sidebars`

:::tip

Expand Down
2 changes: 1 addition & 1 deletion website/docs/guides/docs/sidebar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -423,7 +423,7 @@ See it in action in the [i18n introduction page](../../i18n/i18n-introduction.md

##### Generated index page {#generated-index-page}

You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/{{category name}}`.
You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/[categoryName]`.

```js title="sidebars.js"
module.exports = {
Expand Down
4 changes: 2 additions & 2 deletions website/docs/guides/docs/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,8 @@ npm run docusaurus docs:version 1.1.0

When tagging a new version, the document versioning mechanism will:

- Copy the full `docs/` folder contents into a new `versioned_docs/version-<version>/` folder.
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
- Copy the full `docs/` folder contents into a new `versioned_docs/version-[versionName]/` folder.
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-[versionName]-sidebars.json`.
- Append the new version number to `versions.json`.

## Docs {#docs}
Expand Down
4 changes: 2 additions & 2 deletions website/docs/i18n/i18n-crowdin.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ We recommend the following translation workflow:

Crowdin provides a [CLI](https://support.crowdin.com/cli-tool/) to **upload sources** and **download translations**, allowing you to automate the translation process.

The [`crowdin.yml` configuration file](https://support.crowdin.com/configuration-file/) is convenient for Docusaurus, and permits to **download the localized translation files at the expected location** (in `i18n/<locale>/..`).
The [`crowdin.yml` configuration file](https://support.crowdin.com/configuration-file/) is convenient for Docusaurus, and permits to **download the localized translation files at the expected location** (in `i18n/[locale]/..`).

Read the **[official documentation](https://support.crowdin.com/)** to know more about advanced features and different translation workflows.

Expand Down Expand Up @@ -114,7 +114,7 @@ Your project is created, but it is empty for now. We will upload the files to tr
This configuration ([doc](https://support.crowdin.com/configuration-file/)) provides a mapping for the Crowdin CLI to understand:

- Where to find the source files to upload (JSON and Markdown)
- Where to download the files after translation (in `i18n/<locale>`)
- Where to download the files after translation (in `i18n/[locale]`)

Create `crowdin.yml` in `website`:

Expand Down
4 changes: 2 additions & 2 deletions website/docs/i18n/i18n-introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,12 +92,12 @@ The translation files should be created at the correct filesystem location.
Each locale and plugin has its own `i18n` subfolder:

```
website/i18n/<locale>/<pluginName>/...
website/i18n/[locale]/[pluginName]/...
```

:::note

For multi-instance plugins, the path is `website/i18n/<locale>/<pluginName>-<pluginId>/...`.
For multi-instance plugins, the path is `website/i18n/[locale]/[pluginName]-[pluginId]/...`.

:::

Expand Down
4 changes: 2 additions & 2 deletions website/docs/migration/migration-translated-sites.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ It is not tightly coupled to Crowdin, and you can use Git or another SaaS instea

### Different filesystem paths {#different-filesystem-paths}

On Docusaurus v2, localized content is generally found at `website/i18n/<locale>`.
On Docusaurus v2, localized content is generally found at `website/i18n/[locale]`.

Docusaurus v2 is modular based on a plugin system, and each plugin is responsible to manage its own translations.

Expand Down Expand Up @@ -50,7 +50,7 @@ import Translate from '@docusaurus/Translate';

The `write-translations` CLI still works to extract translations from your code.

The code translations are now added to `i18n/<lang>/code.json` using Chrome i18n JSON format.
The code translations are now added to `i18n/[locale]/code.json` using Chrome i18n JSON format.

:::

Expand Down
2 changes: 1 addition & 1 deletion website/docs/seo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ Read more about the robots file in [the Google documentation](https://developers

## Sitemap file {#sitemap-file}

Docusaurus provides the [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) plugin, which is shipped with `preset-classic` by default. It autogenerates a `sitemap.xml` file which will be available at `https://example.com/<baseUrl>/sitemap.xml` after the production build. This sitemap metadata helps search engine crawlers crawl your site more accurately.
Docusaurus provides the [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) plugin, which is shipped with `preset-classic` by default. It autogenerates a `sitemap.xml` file which will be available at `https://example.com/[baseUrl]/sitemap.xml` after the production build. This sitemap metadata helps search engine crawlers crawl your site more accurately.

## Human readable links {#human-readable-links}

Expand Down