search

WordPress / wordpress-playground

Run WordPress in the browser via WebAssembly PHP
https://w.org/playground/
GNU General Public License v2.0
1.64k stars 259 forks source link

Docs: Playground Docs Translations - i18n (Tracking Issue) #1798

Open juanmaguitar opened 1 month ago

juanmaguitar commented 1 month ago

After the merge of https://github.com/WordPress/wordpress-playground/pull/1766 translations to Docs Pages can now be added to Playground Docs.

There are currently three docs-languages-sites available in production:

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](https://wordpress.github.io/wordpress-playground/) section is completely translated for a specific language including the following sections: - [Quick Start Guide](https://wordpress.github.io/wordpress-playground/quick-start-guide) - [Playground web instance](https://wordpress.github.io/wordpress-playground/web-instance) - [About Playground](https://wordpress.github.io/wordpress-playground/about) - [Guides](https://wordpress.github.io/wordpress-playground/guides) - [Contributing](https://wordpress.github.io/wordpress-playground/contributing) - [Links and Resources](https://wordpress.github.io/wordpress-playground/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 commented 1 month ago

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

juanmaguitar commented 1 month ago

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

@adamziel Yes! I have opened https://github.com/WordPress/wordpress-playground/pull/1808 to add such a page to the documentation