Contributions to translations

You can help translate the Playground documentation into any language. This page provides a comprehensive guide on how to contribute to the translation of Playground docs.

How can I contribute to translations?

By using the same workflow than contributing to any other docs page. You could fork WordPress/wordpress-playground and make PRs with your changes, or edit pages directly using the GitHub UI

info

Check the How can I contribute? to learn more about how to contribute to Playground Docs

Translations implementation details

info

Check the Internationalization section of Docusaurus Docs to learn more about translation management in a Docusaurus website (the engine behind Playground Docs).

Languages available for the Docs site are defined on packages/docs/site/docusaurus.config.js. For example:

i18n: {
  defaultLocale: 'en',
  path: 'i18n',
  locales: ['en', 'fr'],
  localeConfigs: {
	en: {
		label: 'English',
		path: 'en',
	},
	fr: {
		label: 'French',
		path: 'fr',
	},
  },
}

Translated docs pages are located in the WordPress/wordpress-playground repository.

Under packages/docs/site/i18n/, there's a folder for each language. For example, for es (Spanish), there's a packages/docs/site/i18n/es folder.

Under each language folder, there should be a docusaurus-plugin-content-docs/current folder. For example, for es (Spanish), there's a packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current folder.

Under docusaurus-plugin-content-docs/current, the same structure of files of the original docs (same structure of files as) under packages/docs/site/docs) should be replicated.

For example, for es (Spanish), the following translated files exist: 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.

When a new language is added (see PR #1807), you can run npm run write-translations -- --locale <%LANGUAGE%> from packages/docs/site to generate the JSON files containing messages that can be translated into a specific language.

With the proper i18n docusaurus.config.js configuration and files under i18n when running npm run build:docs from the root of the project, specific folders under dist for each language will be created.

How to locally test a language

To locally test an existing language, you can do:

Modify (translate) 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

The "Language Switcher" is a UI element provided by Docusaurus (the docs engine behind Playground Docs) that allows users to change the language of a specific page.

To give more visibility to a translated version, the language switcher can be displayed by adding the following lines to packages/docs/site/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.

It's strongly recommended that a specific language is activated in this Dropdown only when there's a fair amount of pages translated. If it's activated with a few pages translated, the user's experience will be that whenever they switch to the language, no page will be translated into that language.

Making a language publicly available on the Language Switcher

All languages are available once the i18n setup for a language is complete and the correct file structure is in place under i18n.

These language versions of the docs should be hidden on the language switcher hidden until there's a fair amount of pages translated for that language. To be more precise, the recommendation is only to make a language publicly available on the Language Switcher when at least the Documentation section is completely translated for a specific language, including the following sections:

Even if the language switcher doesn't display a specific language, work on adding translated pages can still progress, as the translated pages will become publicly available once the PRs containing the translated files are merged.

Assuming 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"
  }

Testing the Language Switcher locally

Regarding testing the localeDropdown locally, I have found that although it is displayed locally, it doesn't work locally as expected, as the translated pages are not found. But it seems to work well in production.

You can test the localeDropdown from any fork and do so 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://<%GH-USER-WITH-FORK%>.github.io/wordpress-playground/
https://<%GH-USER-WITH-FORK%>.github.io/wordpress-playground/es/
https://<%GH-USER-WITH-FORK%>.github.io/wordpress-playground/fr/

A possible approach to testing the localeDropdown feature is to deploy it to the GitHub Pages of a forked repository.

Process to translate one page into 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%}

Review process

To facilitate the reviewing process, we do recommend keeping the original content commented close to the translated content, for example:

<!--
👋 Hi! Welcome to WordPress Playground documentation.

Playground is an online tool to experiment and learn about WordPress. This site (Documentation) is where you will find all the information you need to start using Playground.
-->

👋 Olá! Bem vindo a documentação oficial do WordPress Playground.

WordPress Playground é uma ferramenta online onde podes testar e aprender mais sobre o WordPress. Nesta página(Documentação) irá encontrar todas as informações necessárias para começar a trabalhar com o Playground.

<!--
<p class="docs-hubs">The WordPress Playground documentation is distributed across four separate hubs (subsites):</p>
-->
<p class="docs-hubs">A documentação do WordPress Playground está dividida em quatro hubs(subsites):</p>

For an improved review process, find reviewers matching the PR's language. Request a reviewer by posting on https://make.wordpress.org/polyglots/ and include the locale tag (e.g., #ja for Japanese). This will notify the Japanese GTEs.

How can I contribute to translations?​

Translations implementation details​

How to locally test a language​

Language Switcher - UI element to change language​

Making a language publicly available on the Language Switcher​

Testing the Language Switcher locally​

Process to translate one page into a language​

Review process​