diff --git a/website/docs/api/plugin-methods/i18n-lifecycles.md b/website/docs/api/plugin-methods/i18n-lifecycles.md index de45fc2e27..aa3a15f215 100644 --- a/website/docs/api/plugin-methods/i18n-lifecycles.md +++ b/website/docs/api/plugin-methods/i18n-lifecycles.md @@ -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//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) diff --git a/website/docs/api/plugins/plugin-content-blog.md b/website/docs/api/plugins/plugin-content-blog.md index 1d325ce3c1..e737f0ea7d 100644 --- a/website/docs/api/plugins/plugin-content-blog.md +++ b/website/docs/api/plugins/plugin-content-blog.md @@ -264,15 +264,15 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first. ### Translation files location {#translation-files-location} -- **Base path**: `website/i18n//docusaurus-plugin-content-blog` -- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-blog-` +- **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//docusaurus-plugin-content-blog` +- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-blog` ### Example file-system structure {#example-file-system-structure} ```bash -website/i18n//docusaurus-plugin-content-blog +website/i18n/[locale]/docusaurus-plugin-content-blog │ │ # translations for website/blog ├── authors.yml diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index 0be06dc360..47c241b821 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -302,15 +302,15 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first. ### Translation files location {#translation-files-location} -- **Base path**: `website/i18n//docusaurus-plugin-content-docs` -- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-docs-` +- **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//docusaurus-plugin-content-docs/` +- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-docs/[versionName]` ### Example file-system structure {#example-file-system-structure} ```bash -website/i18n//docusaurus-plugin-content-docs +website/i18n/[locale]/docusaurus-plugin-content-docs │ │ # translations for website/docs ├── current diff --git a/website/docs/api/plugins/plugin-content-pages.md b/website/docs/api/plugins/plugin-content-pages.md index 971ab7c925..f2c4bc7c92 100644 --- a/website/docs/api/plugins/plugin-content-pages.md +++ b/website/docs/api/plugins/plugin-content-pages.md @@ -122,15 +122,15 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first. ### Translation files location {#translation-files-location} -- **Base path**: `website/i18n//docusaurus-plugin-content-pages` -- **Multi-instance path**: `website/i18n//docusaurus-plugin-content-pages-` +- **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//docusaurus-plugin-content-pages` +- **Markdown files**: `website/i18n/[locale]/docusaurus-plugin-content-pages` ### Example file-system structure {#example-file-system-structure} ```bash -website/i18n//docusaurus-plugin-content-pages +website/i18n/[locale]/docusaurus-plugin-content-pages │ │ # translations for website/src/pages ├── first-markdown-page.md diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md index 5c79af4487..a3d4fda985 100644 --- a/website/docs/api/themes/theme-configuration.md +++ b/website/docs/api/themes/theme-configuration.md @@ -880,7 +880,7 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first. ### Translation files location {#translation-files-location} -- **Base path**: `website/i18n//docusaurus-theme-` +- **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 @@ -888,7 +888,7 @@ Read the [i18n introduction](../../i18n/i18n-introduction.md) first. ### Example file-system structure {#example-file-system-structure} ```bash -website/i18n//docusaurus-theme-classic +website/i18n/[locale]/docusaurus-theme-classic │ │ # translations for the theme ├── navbar.json diff --git a/website/docs/blog.mdx b/website/docs/blog.mdx index 4c689b5c6f..b71d166197 100644 --- a/website/docs/blog.mdx +++ b/website/docs/blog.mdx @@ -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 ``` diff --git a/website/docs/configuration.md b/website/docs/configuration.md index 5192e40264..c10a1692c9 100644 --- a/website/docs/configuration.md +++ b/website/docs/configuration.md @@ -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: diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md index b9523df1c6..cab72df81c 100644 --- a/website/docs/docusaurus-core.md +++ b/website/docs/docusaurus-core.md @@ -249,7 +249,7 @@ export default function VisitMyWebsiteMessage() { When [localizing your site](./i18n/i18n-introduction.md), the `` component will allow providing **translation support to React components**, such as your homepage. The `` 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/`. +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 diff --git a/website/docs/guides/creating-pages.md b/website/docs/guides/creating-pages.md index 3330650847..7ef75e6e95 100644 --- a/website/docs/guides/creating-pages.md +++ b/website/docs/guides/creating-pages.md @@ -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` → `` -- `/src/pages/foo.js` → `/foo` -- `/src/pages/foo/test.js` → `/foo/test` -- `/src/pages/foo/index.js` → `/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: diff --git a/website/docs/guides/docs/docs-multi-instance.mdx b/website/docs/guides/docs/docs-multi-instance.mdx index 5962be207f..9b6d144a84 100644 --- a/website/docs/guides/docs/docs-multi-instance.mdx +++ b/website/docs/guides/docs/docs-multi-instance.mdx @@ -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/_versions.json` -- `website/_versioned_docs` -- `website/_versioned_sidebars` +- `website/[pluginId]_versions.json` +- `website/[pluginId]_versioned_docs` +- `website/[pluginId]_versioned_sidebars` :::tip diff --git a/website/docs/guides/docs/sidebar.md b/website/docs/guides/docs/sidebar.md index 2512ac393c..a03e683734 100644 --- a/website/docs/guides/docs/sidebar.md +++ b/website/docs/guides/docs/sidebar.md @@ -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 = { diff --git a/website/docs/guides/docs/versioning.md b/website/docs/guides/docs/versioning.md index 167f83fde8..451e42d582 100644 --- a/website/docs/guides/docs/versioning.md +++ b/website/docs/guides/docs/versioning.md @@ -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-/` folder. -- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/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} diff --git a/website/docs/i18n/i18n-crowdin.mdx b/website/docs/i18n/i18n-crowdin.mdx index b6b2fa31a5..f914ee2b3c 100644 --- a/website/docs/i18n/i18n-crowdin.mdx +++ b/website/docs/i18n/i18n-crowdin.mdx @@ -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//..`). +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. @@ -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/`) +- Where to download the files after translation (in `i18n/[locale]`) Create `crowdin.yml` in `website`: diff --git a/website/docs/i18n/i18n-introduction.md b/website/docs/i18n/i18n-introduction.md index 18aa135d03..8d81d6fdac 100644 --- a/website/docs/i18n/i18n-introduction.md +++ b/website/docs/i18n/i18n-introduction.md @@ -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///... +website/i18n/[locale]/[pluginName]/... ``` :::note -For multi-instance plugins, the path is `website/i18n//-/...`. +For multi-instance plugins, the path is `website/i18n/[locale]/[pluginName]-[pluginId]/...`. ::: diff --git a/website/docs/migration/migration-translated-sites.md b/website/docs/migration/migration-translated-sites.md index 677eb32fdd..54bf6fabad 100644 --- a/website/docs/migration/migration-translated-sites.md +++ b/website/docs/migration/migration-translated-sites.md @@ -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/`. +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. @@ -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//code.json` using Chrome i18n JSON format. +The code translations are now added to `i18n/[locale]/code.json` using Chrome i18n JSON format. ::: diff --git a/website/docs/seo.md b/website/docs/seo.md index 314970f092..b40b1b4101 100644 --- a/website/docs/seo.md +++ b/website/docs/seo.md @@ -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//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}