મુખ્ય સામગ્રીને બાયપાસ કરો

Contributions to translations

Help make WordPress Playground accessible to a global audience by translating its documentation. This guide provides everything you need to know to get started. Contributing translations follows the same workflow as any other documentation change. You can either fork the WordPress/wordpress-playground repository and create a pull request (PR) with your changes or edit pages directly using the GitHub UI.

માહિતી

For a detailed guide on the contribution workflow (forking, creating PRs, etc.), please see our documentation contribution guide

How Translations Work​

Playground's documentation site is built with Docusaurus, which handles the internationalization (i18n) features.

માહિતી

To learn more about how Docusaurus manages translations, see the Internationalization section of the official Docusaurus documentation.

Configuration​

Available languages are defined in the packages/docs/site/docusaurus.config.js file. For example:

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

File Structure​

All translated documentation pages are located within the packages/docs/site/i18n/ directory, organized by language code.

For a language to work correctly, its file structure must mirror the original English documentation found in packages/docs/site/docs.

For example, the Spanish (es) translation for docs/main/intro.md must be placed at: packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/main/intro.md.

If a translated file does not exist for a specific language, Docusaurus will automatically fall back to the English version of that page.

Generating Translation Files​

When adding a new language, you can generate the necessary JSON files for UI strings (like button labels and navigation items) by running the following command from the packages/docs/site directory:

npm run write-translations -- --locale <LANGUAGE_CODE>

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.

Testing Translations Locally​

To preview your changes for an existing language:

  1. Modify or add a translated file in the appropriate language directory, such as packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/.
  2. From the /packages/docs/site directory, run the local development server for your target language. For example, to test Spanish (es):

npm run dev -- --locale es

The Language Switcher​

The language switcher is a dropdown menu that allows users to select their preferred language.

Documentation Language Switcher

Making a language publicly available on the Language Switcher​

We recommend only adding a language to the switcher when a significant portion of the documentation has been translated. This avoids a poor user experience where switching to a new language results in seeing mostly untranslated English content.

As a guideline, a language should be made publicly available in the switcher only when the entire "Documentation" hub is translated, including these key sections:

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

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

Translation Workflow​

Follow these steps to translate a page:

  1. Check for an Existing Translation Issue: First, search the repository issues to see if a tracking issue for your desired language already exists. If it does, comment on the issue to claim the page(s) you would like to translate.
  2. Create a New Translation Issue: If no issue exists, please create a new one to track the translation progress for the language. You can model it after issue #2202 and use the markdown checklist below to track progress.
  3. Translate the File:
  • Check if you have the latest version of the documentation
  • Copy the original .md file from packages/docs/site/docs/... to the corresponding path in the language directory (e.g., packages/docs/site/i18n/<LANGUAGE_CODE>/...). It is crucial to replicate the original file structure.
  • Translate the content of the new file, keeping the original content commented out <!-- English Content -->.
  • The assets are listed at packages/docs/site/static/img/ only place assets inside the translation folder when it requires localized content.
  • Once the translations are ready, check if the docs build script is running properly npm run build:docs.
  1. Create a pull request with your changes
  • Describe the pages that you translated
  • Request a review at #playground or #polyglots at wordpress.slack.com
માહિતી

We highly recommend submitting pull requests with a small number of translated pages. This approach simplifies the review process and allows for a more gradual and manageable integration of your work.

Translation Tracking Template​

You can use the following markdown in your tracking issue:

## Remaining translation pages

<details open>
<summary><h3>Main</h3></summary>

- about
  - [ ] build.md #2291
  - [ ] index.md #2282
  - [ ] launch.md #2292
  - [ ] test.md #2302
- contributing
  - [ ] code.md #2218
  - [ ] coding-standards.md #2219
  - [ ] contributor-day.md #2246
  - [ ] contributor-badge.md
  - [ ] documentation.md #2271
  - [ ] translations.md #2201
- guides
  - [ ] for-plugin-developers.md #2210
  - [ ] for-theme-developers.md #2211
  - [ ] index.md #2209
  - [ ] providing-content-for-your-demo.md #2213
  - [ ] wordpress-native-ios-app.md #2214
- [ ] intro.md #2198
- [ ] quick-start-guide.md #2204
- [ ] resources.md #2207
- [ ] web-instance.md #2208

</details>

<details open>
<summary><h3>Blueprints</h3></summary>

- blueprints
  - [ ] 01-index.md #2305
  - [ ] 02-using-blueprints.md #2330
  - [ ] 03-data-format.md #2340
   - [ ] 04-resources.md #2352
   - [ ] 05-steps-shorthands.md  #2386
  - [ ] 05-steps.md  #2386
  - [ ] 06-bundles.md #2438
   - [ ] 07-json-api-and-function-api.md #2438
   - [ ] 08-examples.md #2474
   - [ ] 09-troubleshoot-and-debug-blueprints.md #2474
   - [ ] intro.md #2489
   - tutorial
       - [ ] 01-what-are-blueprints-what-you-can-do-with-them.md #2511
       - [ ] 02-how-to-load-run-blueprints.md #2526
       - [ ] 03-build-your-first-blueprint.md
       - [ ] index.md #2511
</details>

<details open>
<summary><h3>Developers</h3></summary>

- [ ] developers
   - [ ] 03-build-an-app
      - [ ] 01-index.md
   - [ ] 05-local-development
      - [ ] 01-wp-now.md
      - [ ] 02-vscode-extension.md
      - [ ] 03-php-wasm-node.md
      - [ ] intro.md
   - [ ] 06-apis
      - [ ] 01-index.md
      - [ ] javascript-api
         - [ ] 01-index.md
         - [ ] 02-index-html-vs-remote-html.md
         - [ ] 03-playground-api-client.md
         - [ ] 04-blueprint-json-in-api-client.md
         - [ ] 05-blueprint-functions-in-api-client.md
         - [ ] 06-mount-data.md
      - [ ] query-api
          - [ ] 01-index.md
   - [ ] 23-architecture
      - [ ] 01-index.md
      - [ ] 02-wasm-php-overview.md
      - [ ] 03-wasm-php-compiling.md
      - [ ] 04-wasm-php-javascript-module.md
      - [ ] 05-wasm-php-filesystem.md
      - [ ] 07-wasm-asyncify.md
      - [ ] 08-browser-concepts.md
      - [ ] 09-browser-tab-orchestrates-execution.md
      - [ ] 10-browser-iframe-rendering.md
      - [ ] 11-browser-php-worker-threads.md
      - [ ] 12-browser-service-workers.md
      - [ ] 13-browser-scopes.md
      - [ ] 14-browser-cross-process-communication.md
      - [ ] 15-wordpress.md
      - [ ] 16-wordpress-database.md
      - [ ] 17-browser-wordpress.md
      - [ ] 18-host-your-own-playground.md
   - [ ] 24-limitations
      - [ ] 01-index.md
   - [ ] intro-devs.md
</details>

Review Process​

To simplify the review process, please keep the original English text as a comment directly above the translated content.

<!--
👋 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.
માહિતી

This practice also helps the maintenance team identify outdated translations. When the original English content is updated, we can search the codebase for the old text (now in comments) and flag the corresponding translation for review.

To find a reviewer fluent in the language of your PR, you can post a request on the Make WordPress Polyglots blog. Be sure to include the locale tag (e.g., #ja for Japanese) to notify the appropriate General Translation Editors (GTEs).

When the PR is merged, the translated version of that page should appear under https://wordpress.github.io/wordpress-playground/{%LANGUAGE%}, if you are contributing for the first time request your Contributor Badge.