Docs: i18n setup #1766

juanmaguitar · 2024-09-15T17:14:54Z

Motivation for the change, related issues

As per #1720 this PR prepares the Playground Docs Site to have the docs available in different languages.

Implementation details

Under packages/docs/site/i18n/ there should be a folder for each language.
For example for es (Spanish) we have:

packages/docs/site/i18n/es

Under each language folder we should have a 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

Testing Instructions (or ideally a Blueprint)

Change a 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

Notes

When this PR is merged (due to the automatic processes to build and deploy on PR merging), there should be the following three versions of the docs in production:

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

NOTE: I recommend activating this option only when there's a fair amount of pages translaged

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

NOTE: Because there's a process of copying and pasting files from packages/docs/site/docs to the languages folder, the #1765 PR is recommended to be merged to reduce the number of errors when building the docs

bgrgicak · 2024-09-18T06:03:12Z

@juanmaguitar I'm unable to start the dev site because of link issues.

Compiled with problems:
×
ERROR in ./docs/main/contributing/documentation.md
Module build failed (from ../../../node_modules/@docusaurus/plugin-content-docs/lib/markdown/index.js):
Error: Docs markdown link couldn't be resolved: (../intro.md) in "/Users/bero/Projects/wordpress-playground/packages/docs/site/docs/main/contributing/documentation.md" for version current
    at throwError (/Users/bero/Projects/wordpress-playground/node_modules/@docusaurus/logger/lib/index.js:76:11)
    at onBrokenMarkdownLink (/Users/bero/Projects/wordpress-playground/node_modules/@docusaurus/plugin-content-docs/lib/index.js:213:79)
    at /Users/bero/Projects/wordpress-playground/node_modules/@docusaurus/plugin-content-docs/lib/markdown/linkify.js:31:40
    at Array.forEach (<anonymous>)
    at linkify (/Users/bero/Projects/wordpress-playground/node_modules/@docusaurus/plugin-content-docs/lib/markdown/linkify.js:31:25)
    at Object.markdownLoader (/Users/bero/Projects/wordpress-playground/node_modules/@docusaurus/plugin-content-docs/lib/markdown/index.js:14:49)

## Motivation for the change, related issues This PR removes "wordpress-playground" from links as it's not needed, and to keep consistency with the rest of the links. It also unifies links, removing relative paths so they start from root. This change reduces the chance of errors when using these files for other languages (See #1766) This PR also fixes this error when doing `npm run build:docs` ``` Error: Docs markdown link couldn't be resolved: (../developers/23-architecture/18-host-your-own-playground.md) in "/Users/juanmanuelgarrido/PROJECTS/2024/wordpress-playground/packages/docs/site/docs/_fragments/_playground_wp_net_may_stop_working.md" for version current at Array.forEach (<anonymous>) [ERROR] Client bundle compiled with errors therefore further build is impossible. Warning: run-commands command "docusaurus build --out-dir ../../../dist/docs/build" exited with non-zero status code ```

juanmaguitar · 2024-09-18T07:36:29Z

@bgrgicak I just tried it locally and is working for me.

See terminal output when doing npm run dev:docs

⬢  wordpress-playground  docs/i18n ⦾ npm run dev:docs

> [email protected] dev:docs
> nx dev docs-site


> nx run docs-site:dev

Debugger listening on ws://127.0.0.1:59925/fae4d337-4ef9-4231-8289-679dc62ec519
For help, see: https://nodejs.org/en/docs/inspector
Debugger attached.
Waiting for the debugger to disconnect...

╭──────────────────────────────────────────────────────────────────────────────╮│                                                                              ││                        Update available 2.4.1 → 3.5.2                        ││                                                                              ││       To upgrade Docusaurus packages with the latest version, run the        ││                             following command:                               ││                                   `npm i `                                   ││                                                                              │╰──────────────────────────────────────────────────────────────────────────────╯

[INFO] Starting the development server...
warning You are running with an unsupported TypeScript version! If TypeDoc crashes, this is why. TypeDoc supports 4.6, 4.7, 4.8, 4.9
...
JSON written to ./.docusaurus/api-typedoc-default.json
[SUCCESS] Docusaurus website is running at: http://localhost:3000/wordpress-playground/
Browserslist: caniuse-lite is outdated. Please run:
  npx update-browserslist-db@latest
  Why you should do it regularly: https://github.com/browserslist/update-db#readme
ℹ Compiling Client
✔ Client: Compiled successfully in 949.62ms
client (webpack 5.83.0) compiled successfully

Could you provide more info about the process you're doing to get that error?

packages/docs/site/docusaurus.config.js

bgrgicak

Thanks @juanmaguitar! Overall it's working, but I wasn't able to get the language switcher to work.

packages/docs/site/docusaurus.config.js

packages/docs/site/i18n/es/code.json

juanmaguitar · 2024-09-19T13:05:50Z

Thanks for testing this @bgrgicak

Regarding the visibility of the language switcher I added it to the PR commented because I think this is something that should be activated when there are at least some pages translated of each language.
If it's activated with this PR 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.

cc: @adamziel

bgrgicak

Thanks for explaining @juanmaguitar. I'm happy to merge this as is.

…ss-playground into docs/i18n

jennydupuy · 2024-09-23T08:55:44Z

Hi @juanmaguitar, could you explain the process to create a branch please?

adamziel · 2024-09-23T18:50:31Z

It seems like this PR broke the docs build in trunk:

[ERROR] Unable to build website for locale fr.
[ERROR] Error: Docusaurus found broken links!

Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.

Exhaustive list of all broken links found:

- On source page path = /wordpress-playground/fr/:
   -> linking to /wordpress-playground/fr/wordpress-playground/
   -> linking to /wordpress-playground/fr/wordpress-playground/blueprints
   -> linking to /wordpress-playground/fr/wordpress-playground/developers
   -> linking to /wordpress-playground/fr/wordpress-playground/api
   -> linking to /wordpress-playground/fr/wordpress-playground/quick-start-guide#start-a-new-wordpress-site (resolved as: /wordpress-playground/fr/wordpress-playground/quick-start-guide)
   -> linking to /wordpress-playground/fr/wordpress-playground/quick-start-guide#try-a-block-a-theme-or-a-plugin (resolved as: /wordpress-playground/fr/wordpress-playground/quick-start-guide)
   -> linking to /wordpress-playground/fr/wordpress-playground/quick-start-guide#use-a-specific-wordpress-or-php-version (resolved as: /wordpress-playground/fr/wordpress-playground/quick-start-guide)

    at throwError (/home/runner/work/wordpress-playground/wordpress-playground/node_modules/@docusaurus/logger/lib/index.js:76:11)
    at handleBrokenLinks (/home/runner/work/wordpress-playground/wordpress-playground/node_modules/@docusaurus/core/lib/server/brokenLinks.js:153:47)
    at async buildLocale (/home/runner/work/wordpress-playground/wordpress-playground/node_modules/@docusaurus/core/lib/commands/build.js:186:5)
    at async tryToBuildLocale (/home/runner/work/wordpress-playground/wordpress-playground/node_modules/@docusaurus/core/lib/commands/build.js:41:20)
    at async mapAsyncSequential (/home/runner/work/wordpress-playground/wordpress-playground/node_modules/@docusaurus/utils/lib/jsUtils.js:34:24)
    at async Command.build (/home/runner/work/wordpress-playground/wordpress-playground/node_modules/@docusaurus/core/lib/commands/build.js:76:21)

cc @bgrgicak

jennydupuy · 2024-09-24T07:37:42Z

Hi @juanmaguitar

In this #1766 (comment), you mention the Changelog section as needing to be translated to activate the language switcher, but it seems to me that this section is not essential for users needing to learn about the Playground. After all, this section contains a lot of technical elements that are difficult for a basic user to understand.
I therefore propose not to translate this section.

In addition, I think it would be a good idea to add to each page a reference to the contributor(s) who wrote the source page, and to the contributor(s) who translated/reviewed it.

## Motivation for the change, related issues This PR fixes the issue reported at #1766 (comment) ## Implementation details ## Testing Instructions (or ideally a Blueprint) Run `npm run build:docs` from this branch and check how the build is done succesfully

juanmaguitar · 2024-09-24T09:05:02Z

It seems like this PR broke the docs build in trunk

@adamziel this issue has been fixed on #1795

juanmaguitar · 2024-09-24T10:39:36Z

In this #1766 (comment), you mention the Changelog section as needing to be translated to activate the language switcher, but it seems to me that this section is not essential for users needing to learn about the Playground. After all, this section contains a lot of technical elements that are difficult for a basic user to understand.
I therefore propose not to translate this section.

I agree with this @jennydupuy. I have opened #1798 to coordinate translations efforts and provide some instructions and tips on the translations workflows.

In addition, I think it would be a good idea to add to each page a reference to the contributor(s) who wrote the source page, and to the contributor(s) who translated/reviewed it.

This is a great idea. Would you mind opening a specific issue for this?
This may require a specific development. Pinging @adamziel for this.

could you explain the process to create a branch please?

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/

At #1798 you have more tips and instructions to contribute to Playground Docs translations

adamziel · 2024-09-24T12:33:27Z

In addition, I think it would be a good idea to add to each page a reference to the contributor(s) who wrote the source page, and to the contributor(s) who translated/reviewed it.

This is a great idea. Would you mind opening a specific issue for this? This may require a specific development. Pinging @adamziel for this.

Docusaurus doesn't seem to support it – there's quite a few people requesting that feature: facebook/docusaurus#6218 (comment)

I haven't found any plugins either. We'd need to build that one from scratch. Let's track it in a separate issue.

## Motivation for the change, related issues With the merge of #1766 translations are enabled for Playground Docs. Files can be translated but also web parts. This PR incorporates JSON files with messages to translate for each language. This files have been generated by running from from `packages/docs/site`: ``` npm run write-translations -- --locale fr npm run write-translations -- --locale es ``` These files still need to be translated. This PR just adds them for the sake of simplifying the work of contributors translating Playground Docs for a specific language.

i18n init

3442def

juanmaguitar mentioned this pull request Sep 15, 2024

Docs: better paths for links #1765

Merged

juanmaguitar requested a review from adamziel September 15, 2024 17:34

juanmaguitar mentioned this pull request Sep 15, 2024

Translate the playground documentation #1720

Closed

juanmaguitar added the [Type] Documentation Improvements or additions to documentation label Sep 16, 2024

juanmaguitar requested review from bgrgicak and brandonpayton September 17, 2024 10:57

adamziel added the Needs Author's Reply label Sep 18, 2024

Merge branch 'trunk' into docs/i18n

b0f9bfd

adamziel removed the Needs Author's Reply label Sep 18, 2024

Merge branch 'trunk' into docs/i18n

27ffda1

bgrgicak reviewed Sep 19, 2024

View reviewed changes

packages/docs/site/docusaurus.config.js Outdated Show resolved Hide resolved

bgrgicak requested changes Sep 19, 2024

View reviewed changes

packages/docs/site/docusaurus.config.js Outdated Show resolved Hide resolved

packages/docs/site/i18n/es/code.json Show resolved Hide resolved

adamziel added the Needs Author's Reply label Sep 19, 2024

Merge branch 'trunk' into docs/i18n

150524a

adamziel removed the Needs Author's Reply label Sep 19, 2024

juanmaguitar requested a review from bgrgicak September 19, 2024 13:33

bgrgicak approved these changes Sep 20, 2024

View reviewed changes

juanmaguitar added 3 commits September 20, 2024 09:56

Added french language

12009df

Merge branch 'docs/i18n' of github.com:wordpress-juanmaguitar/wordpre…

4db9dc7

…ss-playground into docs/i18n

Merge branch 'trunk' into docs/i18n

e5face2

juanmaguitar merged commit 78a35de into WordPress:trunk Sep 20, 2024
4 of 5 checks passed

adamziel mentioned this pull request Sep 23, 2024

Blueprints: Directory Resources #1793

Merged

8 tasks

juanmaguitar mentioned this pull request Sep 24, 2024

Docs: fix links intro fr #1795

Merged

juanmaguitar mentioned this pull request Sep 24, 2024

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

Open

juanmaguitar mentioned this pull request Sep 25, 2024

Docs: translation i18n messages - JSON files #1807

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: i18n setup #1766

Docs: i18n setup #1766

juanmaguitar commented Sep 15, 2024 •

edited

Loading

bgrgicak commented Sep 18, 2024

juanmaguitar commented Sep 18, 2024

bgrgicak left a comment

juanmaguitar commented Sep 19, 2024 •

edited

Loading

bgrgicak left a comment

jennydupuy commented Sep 23, 2024

adamziel commented Sep 23, 2024

jennydupuy commented Sep 24, 2024

juanmaguitar commented Sep 24, 2024

juanmaguitar commented Sep 24, 2024 •

edited

Loading

adamziel commented Sep 24, 2024

Docs: i18n setup #1766

Docs: i18n setup #1766

Conversation

juanmaguitar commented Sep 15, 2024 • edited Loading

Motivation for the change, related issues

Implementation details

Testing Instructions (or ideally a Blueprint)

Notes

UI element to change language

Process to translate one page in a language

bgrgicak commented Sep 18, 2024

juanmaguitar commented Sep 18, 2024

bgrgicak left a comment

Choose a reason for hiding this comment

juanmaguitar commented Sep 19, 2024 • edited Loading

bgrgicak left a comment

Choose a reason for hiding this comment

jennydupuy commented Sep 23, 2024

adamziel commented Sep 23, 2024

jennydupuy commented Sep 24, 2024

juanmaguitar commented Sep 24, 2024

juanmaguitar commented Sep 24, 2024 • edited Loading

adamziel commented Sep 24, 2024

juanmaguitar commented Sep 15, 2024 •

edited

Loading

juanmaguitar commented Sep 19, 2024 •

edited

Loading

juanmaguitar commented Sep 24, 2024 •

edited

Loading