Skip to content

Commit

Permalink
Docs: i18n setup (#1766)
Browse files Browse the repository at this point in the history
## Motivation for the change, related issues

As per #1720
this PR prepares the Playground Docs Site to have the docs available in
different languages.

## Implementation details

Under `packages/docs/site/i18n/` there should be a folder for each
language.
For example for `es` (Spanish) we have:
```
packages/docs/site/i18n/es
```
Under each language folder we should have a
`docusaurus-plugin-content-docs/current` folder.
For example for `es` (Spanish) we have:
```
packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current
```

Under `docusaurus-plugin-content-docs/current` we should replicate the
same structure of files of the original docs (same structure of files
than under `packages/docs/site/docs`)

For example for `es` (Spanish) we have just one file translated:
```
packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/main/intro.md
```

If a file is not available under a language's folder the original file
in the default language will be loaded

## Testing Instructions (or ideally a Blueprint)

- Change a file under one of the available languages:
`packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current`
- From `/packages/docs/site` run the version for the language you'd like
to test. For example to test `es`:
```
npm run dev -- --locale es
```

## Notes

When this PR is merged (due to the automatic processes to build and
deploy on PR merging), there should be the following three versions of
the docs in production:
- https://wordpress.github.io/wordpress-playground/
- https://wordpress.github.io/wordpress-playground/es/
- https://wordpress.github.io/wordpress-playground/fr/

### UI element to change language 

To give more visibility to a translated version we can uncomment the
following lines at `docusaurus.config.js`
```
{
  type: 'localeDropdown',
  position: 'right',
},
```

This will generate a dropdown in the header to access directly to a
language version of each file

_NOTE: I recommend activating this option only when there's a fair
amount of pages translaged_

### Process to translate one page in a language

The recommended process is to copy and paste the `.md` file from the
original path (`packages/docs/site/docs`) into the desired language path
(
`packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current`).
It is important to replicate the structure of files at
`packages/docs/site/docs`

The file under
`packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current`
can be translated and a PR can be created with the new changes.

When the PR is merged the translated version of that page should appear
under https://wordpress.github.io/wordpress-playground/{%LANGUAGE%}

_NOTE: Because there's a process of copying and pasting files from
`packages/docs/site/docs` to the languages folder, the
#1765 PR is
recommended to be merged to reduce the number of errors when building
the docs_
  • Loading branch information
juanmaguitar authored Sep 20, 2024
1 parent 50e69af commit 78a35de
Show file tree
Hide file tree
Showing 5 changed files with 1,048 additions and 1 deletion.
21 changes: 20 additions & 1 deletion packages/docs/site/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,22 @@ const config = {
// to replace "en" with "zh-Hans".
i18n: {
defaultLocale: 'en',
locales: ['en'],
path: 'i18n',
locales: ['en', 'es', 'fr'],
localeConfigs: {
en: {
label: 'English',
path: 'en',
},
es: {
label: 'Español',
path: 'es',
},
fr: {
label: 'French',
path: 'fr',
},
},
},
themes: ['@docusaurus/theme-live-codeblock'],
plugins: [
Expand Down Expand Up @@ -146,6 +161,10 @@ const config = {
className: 'header-github-link',
'aria-label': 'GitHub repository',
},
{
type: 'localeDropdown',
position: 'right',
},
],
},
footer: {
Expand Down
Loading

0 comments on commit 78a35de

Please sign in to comment.