Translate How to contribute pages to Brazilian Portuguese (#2329)

fellyph · web-flow · commit 4f4e0c4a169a · 2025-07-08T13:22:04.000+02:00
diff --git a/packages/docs/site/docs/main/contributing/coding-standards.md b/packages/docs/site/docs/main/contributing/coding-standards.md
@@ -6,14 +6,14 @@ slug: /contributing/coding-standards
 
 ## Error messages
 
-A good error message tells the user what to do next. Any ambiguity in errors thrown by Playground public APIs will prompt the developers to open issues.
+A good error message informs the user of the following steps to take. Any ambiguity in errors thrown by Playground public APIs will prompt the developers to open issues.
 
 Consider a network error, for example—can we infer the type of error and display a relevant message summarizing the next steps?
 
 -   **Network error**: "Your internet connection twitched. Try to reload the page.
 -   **404**: "Could not find the file".
 -   **403**: "The server blocked access to the file".
--   **CORS**: clarify it's a browser security feature and add a link to a detailed explanation (on MDN or another reliable source). Suggest the user move their file somewhere else, like raw.githubusercontent.com, and link to a resource explaining how to set up CORS headers on their servers.
+-   **CORS**: clarify it's a browser security feature and add a link to a detailed explanation (on MDN or another reliable source). Suggest the user move their file somewhere else, like `raw.githubusercontent.com`, and link to a resource explaining how to set up CORS headers on their servers.
 
 We handle code formatting and linting automatically. Relax, type away, and let the machines do the work.
 
@@ -23,7 +23,7 @@ Playground aims to keep the narrowest possible API scope.
 
 Public APIs are easy to add and hard to remove. It only takes one PR to introduce a new API, but it may take a thousand to remove it, especially if other projects have already consumed it.
 
--   Don't expose unnecessary function, class, constant, or other components.
+-   Don't expose unnecessary functions, classes, constants, or other components.
 
 ## Blueprints
 
diff --git a/packages/docs/site/docs/main/contributing/index.md b/packages/docs/site/docs/main/contributing/index.md
@@ -6,7 +6,7 @@ id: introduction
 
 # Contributing to WP Playground project
 
-WordPress Playground is an open-source project that welcomes all contributors—from code to design, documentation to triage.
+WordPress Playground is an open-source project that welcomes contributors of all kinds, from code to design, documentation to triage.
 
 ## How can I contribute?
 
@@ -34,13 +34,13 @@ Want to help sort through open issues and resolve potential bugs? Here's how:
 
 WordPress Playground and the WordPress project are strongly rooted in free and open source software. Specifically, WordPress Playground is licenced under GPLv2 (or later) from the [Free Software Foundation](https://www.fsf.org/). You can [read the text of the license here](https://github.com/WordPress/wordpress-playground/blob/trunk/LICENSE) and if that feels overwhelming, WordPress.org has a [friendly GPL Primer](https://make.wordpress.org/community/handbook/wordcamp-organizer/planning-details/gpl-primer/).
 
-As such, please be aware of the implications your contributions will fall under:
+As such, please be aware of the implications that your contributions will fall under:
 
 -   When you contribute, you agree to license your contributions under the GPLv2 (or later) license
 -   The GPL license has strong copyleft provisions that ensure all derivative works remain open-source and under the same license terms, thereby promoting a collaborative development environment.
 -   The GPL license encourages contributing any changes, bug fixes, or new features back to the original codebase.
 -   The GPL license ensures that the project remains free and open-source, not only in terms of cost but also with respect to the freedom to use, modify, and distribute the software.
 
-If you have any questions about how the above might effect your contributions, please feel free to reach out on WP Slack and the [`meta-playground` channel](https://wordpress.slack.com/archives/C04EWKGDJ0K).
+If you have any questions about how the above might affect your contributions, please feel free to reach out on WP Slack and the [`meta-playground` channel](https://wordpress.slack.com/archives/C04EWKGDJ0K).
 
 Thank you again for your contributions! 🎉
diff --git a/packages/docs/site/docs/main/contributing/translations.md b/packages/docs/site/docs/main/contributing/translations.md
@@ -48,22 +48,22 @@ 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 than under `packages/docs/site/docs`) should be replicated.
+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 exists: `packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/main/intro.md`
+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
+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](https://github.com/WordPress/wordpress-playground/pull/1807)) you can run `npm run write-translations -- --locale <%LANGUAGE%>` from `packages/docs/site` to generate the JSON files with messages that can be translated to 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.
+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`:
+-   From `/packages/docs/site` run the version for the language you'd like to test. For example, to test `es`:
 
 ```
 
@@ -73,7 +73,7 @@ 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 user to change the language of a specific page.
+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 at `docusaurus.config.js`
 
@@ -88,17 +88,17 @@ To give more visibility to a translated version the language switcher can be dis
 
 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 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.
+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 when the i18n setup for a language is done and the correct structure of files is available under `i18n`.
+All languages are available once the i18n setup for a language is complete and the correct file structure is in place under `i18n`.
 
 -   https://wordpress.github.io/wordpress-playground/
 -   https://wordpress.github.io/wordpress-playground/es/
 -   https://wordpress.github.io/wordpress-playground/fr/
 
-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 to only make a language publicly available on the Language Switcher when at least the [Documentation](https://wordpress.github.io/wordpress-playground/) section is completely translated for a specific language including the following sections:
+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 to only make a language publicly available on the Language Switcher 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)
@@ -109,7 +109,7 @@ These language versions of the docs should be hidden on the language switcher hi
 
 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
+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.
 
 ```
   {
@@ -140,9 +140,9 @@ Assuming the `fr` language is the first language with the Documentation hub page
 
 ### Testing the Language Switcher locally
 
-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.
+Regarding testing the `localeDropdown` locally, I have found that although it 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.
 
-You can test the `localeDropdown` from any fork and doing from the root of the project:
+You can test the `localeDropdown` from any fork and do so from the root of the project:
 
 ```
 npm run build:docs
@@ -159,10 +159,10 @@ https://<%GH-USER-WITH-FORK%>.github.io/wordpress-playground/fr/
 
 So, a possible approach to testing the `localeDropdown` feature is by deploying it to the GitHub Pages of a forked repository.
 
-## Process to translate one page in a language
+## 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%}
+When the PR is merged, the translated version of that page should appear under https://wordpress.github.io/wordpress-playground/{%LANGUAGE%}
diff --git a/packages/docs/site/docusaurus.config.js b/packages/docs/site/docusaurus.config.js
@@ -33,7 +33,7 @@ const config = {
 	i18n: {
 		defaultLocale: 'en',
 		path: 'i18n',
-		locales: ['en', 'es', 'fr', 'ja', 'pt-BR'],
+		locales: ['en', 'es', 'fr', 'ja', 'pt-br'],
 		localeConfigs: {
 			en: {
 				label: 'English',
@@ -51,7 +51,7 @@ const config = {
 				label: 'Japanese',
 				path: 'ja',
 			},
-			'pt-BR': {
+			'pt-br': {
 				label: 'Português (BR)',
 				path: 'pt-BR',
 			},
diff --git a/packages/docs/site/i18n/pt-BR/docusaurus-plugin-content-docs/current/main/contributing/coding-standards.md b/packages/docs/site/i18n/pt-BR/docusaurus-plugin-content-docs/current/main/contributing/coding-standards.md
@@ -0,0 +1,111 @@
+---
+slug: /contributing/coding-standards
+---
+
+<!--
+# Coding principles
+
+## Error messages
+
+A good error message tells the user what to do next. Any ambiguity in errors thrown by Playground public APIs will prompt the developers to open issues.
+-->
+
+# Princípios de codificação
+
+## Mensagens de erro
+
+Uma boa mensagem de erro informa ao usuário o que fazer a seguir. Qualquer ambiguidade nos erros lançados pelas APIs públicas do Playground levará os desenvolvedores a abrir issues.
+
+<!--
+Consider a network error, for example—can we infer the type of error and display a relevant message summarizing the next steps?
+
+-   **Network error**: "Your internet connection twitched. Try to reload the page.
+-   **404**: "Could not find the file".
+-   **403**: "The server blocked access to the file".
+-   **CORS**: clarify it's a browser security feature and add a link to a detailed explanation (on MDN or another reliable source). Suggest the user move their file somewhere else, like raw.githubusercontent.com, and link to a resource explaining how to set up CORS headers on their servers.
+-->
+
+Considere um erro de rede, por exemplo: podemos inferir o tipo de erro e exibir uma mensagem relevante resumindo os próximos passos?
+
+-   **Erro de rede**: "Sua conexão com a internet oscilou. Tente recarregar a página."
+-   **404**: "Não foi possível encontrar o arquivo".
+-   **403**: "O servidor bloqueou o acesso ao arquivo".
+-   **CORS**: esclareça que é um recurso de segurança do navegador e adicione um link para uma explicação detalhada (no MDN ou outra fonte confiável). Sugira que o usuário mova o arquivo para outro lugar, como raw.githubusercontent.com, e crie um link para um recurso que explique como configurar os cabeçalhos CORS em seus servidores.
+
+<!--
+We handle code formatting and linting automatically. Relax, type away, and let the machines do the work.
+-->
+
+Lidamos com a formatação e o linting do código automaticamente. Relaxe, digite e deixe as máquinas fazerem o trabalho.
+
+<!--
+## Public API
+
+Playground aims to keep the narrowest possible API scope.
+-->
+
+## API Pública
+
+O Playground visa manter o escopo de API o mais restrito possível.
+
+<!--
+Public APIs are easy to add and hard to remove. It only takes one PR to introduce a new API, but it may take a thousand to remove it, especially if other projects have already consumed it.
+
+-   Don't expose unnecessary functions, classes, constants, or other components.
+-->
+
+APIs públicas são fáceis de adicionar e difíceis de remover. Leva apenas um PR para introduzir uma nova API, mas pode levar mil para removê-la, especialmente se outros projetos já a consumiram.
+
+-   Não exponha funções, classes, constantes ou outros componentes desnecessários.
+
+<!--
+## Blueprints
+
+Blueprints are the primary way to interact with Playground. These JSON files describe a set of steps that Playground executes in order.
+-->
+
+## Blueprints
+
+Blueprints são a principal forma de interagir com o Playground. Estes arquivos JSON descrevem um conjunto de passos que o Playground executa em ordem.
+
+<!--
+### Guidelines
+
+Blueprint steps should be **concise and focused**. They should do one thing and do it well.
+
+-   If you need to create a new step, try refactoring an existing one first.
+-   If that's not enough, ensure the new step delivers a new capability. Don't replicate the functionality of existing steps.
+-   Assume the step would be called more than once.
+-   Assume it would run in a specific order.
+-   Add unit tests to verify that.
+-->
+
+### Diretrizes
+
+Os passos do Blueprint devem ser **concisos e focados**. Eles devem fazer uma coisa e fazê-la bem.
+
+-   Se você precisar criar um novo passo, tente refatorar um existente primeiro.
+-   Se isso não for suficiente, garanta que o novo passo entregue uma nova capacidade. Não replique a funcionalidade de passos existentes.
+-   Assuma que o passo será chamado mais de uma vez.
+-   Assuma que ele será executado em uma ordem específica.
+-   Adicione testes unitários para verificar isso.
+
+<!--
+Blueprints should be **intuitive and straightforward**.
+
+-   Don't require arguments that can be optional.
+-   Use plain argument. For example, `slug` instead of `path`.
+-   Define constants in virtual JSON files—don't modify PHP files.
+-   Define a TypeScript type for the Blueprint. That's how Playground generates its JSON schema.
+-   Write a function to handle a Blueprint step. Accept the argument of the type you defined.
+-   Provide a usage example in the doc string. It's automatically reflected in the docs.
+-->
+
+Blueprints devem ser **intuitivos e diretos**.
+
+-   Não exija argumentos que podem ser opcionais.
+-   Use argumentos simples. Por exemplo, `slug` em vez de `path`.
+-   Defina constantes em arquivos JSON virtuais — não modifique arquivos PHP.
+-   Defina um tipo TypeScript para o Blueprint. É assim que o Playground gera seu esquema JSON.
+-   Escreva uma função para lidar com um passo do Blueprint. Aceite o argumento do tipo que você definiu.
+-   Forneça um exemplo de uso na docstring. Ele é refletido automaticamente na documentação.
diff --git a/packages/docs/site/i18n/pt-BR/docusaurus-plugin-content-docs/current/main/contributing/index.md b/packages/docs/site/i18n/pt-BR/docusaurus-plugin-content-docs/current/main/contributing/index.md
diff --git a/packages/docs/site/i18n/pt-BR/docusaurus-plugin-content-docs/current/main/contributing/translations.md b/packages/docs/site/i18n/pt-BR/docusaurus-plugin-content-docs/current/main/contributing/translations.md
