Docs: Playground Docs Translations - i18n (Tracking Issue) #1798
Description
After the merge of #1766 translations to Docs Pages can now be added to Playground Docs.
There are currently three docs-languages-sites available in production:
- https://wordpress.github.io/wordpress-playground/
- https://wordpress.github.io/wordpress-playground/es/
- https://wordpress.github.io/wordpress-playground/fr/
For es and fr there are only some translations done on the intro page but everything is ready to add more translated pages for these languages
I open this Issue to centralize and track translations efforts and to provide some tips on how to approach translations to docs pages.
See Instructions and tips on contributing to Playground Docs translations
Implementation details
Under packages/docs/site/i18n/ there's a folder for each language.
For example for es (Spanish) we have:
packages/docs/site/i18n/es
Under each language folder there should bea 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
How to locally test a language
- Change any file under one of the available languages:
packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current - From
/packages/docs/siterun the version for the language you'd like to test. For example to testes:
npm run dev -- --locale es
Language Switcher - 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
I recommend activating this option only when there's a fair amount of pages translated. If it's activated with few pages translated the experience the user will get is that whenever they change to the language no page will be translated to that language
My suggestion here would be to keep this language switcher hidden until there's a fair amount of pages translated. To be more precise, I would suggest this switcher is only enabled for a language when at least the Documentation section is completely translated for a specific language including the following sections:
With the current PR merged in trunk the work to translate the Documentation hub (Quick Start Guide, Playground web instance, About Playground, Guides,... ) in a specific language could start in different branch. Once the first language is completed for those pages the branch could be merged with the localeDropdown uncommented, taking into account that the i18n config should only contain active languages in production.
Asumming the fr language is the first language with the Documentation hub pages (Quick Start Guide, Playground web instance, About Playground, Guides,... ) completely translated to French, the docusaurus.config.js should look like this in that branch so npm run build:docs properly generate the fr subsite and only displays the french language in the localeDropdown language switcher
i18n: {
defaultLocale: 'en',
path: 'i18n',
locales: ['en', 'fr'],
localeConfigs: {
en: {
label: 'English',
path: 'en',
},
fr: {
label: 'French',
path: 'fr',
},
},
},
...
{
type: 'localeDropdown',
position: 'right',
},
Regarding testing the localeDropdown locally, I have found that although is displayed locally it doesn't really work locally as expected as the translated pages are not found. But it seems to work well in production. I have successfully tested from my fork at https://github.com/wordpress-juanmaguitar/wordpress-playground/tree/docs/i18n and doing from the root of the project:
npm run build:docs
npm run deploy:docs
This generates three versions of the docs in the GitHub Pages of my forked repo:
https://wordpress-juanmaguitar.github.io/wordpress-playground/
https://wordpress-juanmaguitar.github.io/wordpress-playground/es/
https://wordpress-juanmaguitar.github.io/wordpress-playground/fr/
So, the best way I have found to test the localeDropdown feature (so far) in by deploying it to the GitHub Pages of any forked repo.
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%}
Creating a branch to work on new translated pages and opening PRs
To contribute to the docs adding translated pages you need to be familiar with Git workflows and contributing to WordPress GitHub repositories.
The process of creating a branch to open new PRs with translated pages on https://github.com/WordPress/wordpress-playground is the same than contributing to other WordPress repositories such as gutenberg.
The process explained in the following resource can be applied to contributing to the wordpress-playground repo
https://developer.wordpress.org/block-editor/contributors/code/git-workflow/
Some commands you may use in this contribution workflow.
git clone https://github.com/YOUR-USER-NAME/wordpress-playground
git switch -c update/my-branch
git commit -m "Your Good Commit Message" path/to/FILE
git push -u origin update/my-branch
cc: @adamziel