Docs: Playground Docs Translations - i18n (Tracking Issue)

[juanmaguitar]

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/site run the version for the language you'd like to test. For example to test es:

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:

• Quick Start Guide
• Playground web instance
• About Playground
• Guides
• Contributing
• Links and Resources

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

[adamziel]

@juanmaguitar would it make sense to add a new documentation page with all the contributing instructions listed in this issue?

[juanmaguitar]

would it make sense to add a new documentation page with all the contributing instructions listed in this issue?

@adamziel Yes! I have opened #1808 to add such a page to the documentation

[beryl-dlg]

Hello, not sure I've done it right but I've added the french translation to the intro file
doing a PR
#2146

and create the second file in order to continue to add french translation
https://github.com/WordPress/wordpress-playground/pull/2147

Hope this is the right way,
thanks

cc: @jennydupuy