Pular para o conteúdo principal

Contribuições para traduções

Você pode ajudar a traduzir a documentação do Playground para qualquer idioma. Esta página fornece um guia abrangente sobre como contribuir para a tradução da documentação do Playground.

Como posso contribuir para as traduções?​

Usando o mesmo fluxo de trabalho que contribuir para qualquer outra página de documentação. Você pode fazer um fork do WordPress/wordpress-playground e criar PRs com suas alterações ou editar páginas diretamente usando a interface do GitHub.

info

Consulte Como posso contribuir? para saber mais sobre como contribuir para a Documentação do Playground

Detalhes de implementação das traduções​

info

Consulte a seção de Internacionalização da Documentação do Docusaurus para saber mais sobre o gerenciamento de traduções em um site Docusaurus (o motor por trás da Documentação do Playground).

Os idiomas disponíveis para o site de Documentação são definidos no docusaurus.config.js. Por exemplo:ff

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

As páginas de documentação traduzidas estão localizadas no repositório WordPress/wordpress-playground.

Sob packages/docs/site/i18n/ há uma pasta para cada idioma. Por exemplo, para es (Espanhol) há uma pasta packages/docs/site/i18n/es.

Sob cada pasta de idioma deve haver uma pasta docusaurus-plugin-content-docs/current. Por exemplo, para es (Espanhol) há uma pasta packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current.

Sob docusaurus-plugin-content-docs/current a mesma estrutura de arquivos da documentação original (mesma estrutura de arquivos que sob packages/docs/site/docs) deve ser replicada.

Por exemplo, para es (Espanhol) existem os seguintes arquivos traduzidos: packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/main/intro.md.

Se um arquivo não estiver disponível sob a pasta de um idioma, o arquivo original no idioma padrão será carregado.

Quando um novo idioma é adicionado (veja PR #1807) você pode executar npm run write-translations -- --locale <%LANGUAGE%> de packages/docs/site para gerar os arquivos JSON com mensagens que podem ser traduzidas para um idioma específico.

Com a configuração adequada do i18n no docusaurus.config.js e arquivos sob i18n, ao executar npm run build:docs da raiz do projeto, pastas específicas sob dist para cada idioma serão criadas.

Como testar um idioma localmente​

Para testar localmente um idioma existente você pode fazer:

  • Modificar (traduzir) qualquer arquivo sob um dos idiomas disponíveis: packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current
  • De /packages/docs/site execute a versão para o idioma que você gostaria de testar. Por exemplo, para testar es:
npm run dev -- --locale es

Seletor de Idioma - Elemento de interface para alterar o idioma​

O "Seletor de Idioma" é um elemento de interface fornecido pelo Docusaurus (o motor de documentação por trás da Documentação do Playground) que permite ao usuário alterar o idioma de uma página específica.

Para dar mais visibilidade a uma versão traduzida, o seletor de idioma pode ser exibido adicionando as seguintes linhas no docusaurus.config.js:

{
  type: 'localeDropdown',
  position: 'right',
},

Isso gerará um menu suspenso no cabeçalho para acessar diretamente uma versão em idioma de cada arquivo.

É fortemente recomendado que um idioma específico seja ativado neste Menu Suspenso apenas quando houver uma quantidade razoável de páginas traduzidas. Se for ativado com poucas páginas traduzidas, a experiência que o usuário terá é que sempre que mudarem para o idioma, nenhuma página estará traduzida para esse idioma.

Tornando um idioma publicamente disponível no Seletor de Idioma​

Todos os idiomas estão disponíveis quando a configuração i18n para um idioma é feita e a estrutura correta de arquivos está disponível sob i18n.

Essas versões de idioma da documentação devem ser ocultadas no seletor de idioma até que haja uma quantidade razoável de páginas traduzidas para esse idioma. Para ser mais preciso, a recomendação é tornar um idioma publicamente disponível no Seletor de Idioma apenas quando pelo menos a seção Documentação estiver completamente traduzida para um idioma específico, incluindo as seguintes seções:

Mesmo que o seletor de idioma não exiba um idioma específico, o trabalho de adicionar páginas traduzidas ainda pode progredir, pois as páginas traduzidas se tornarão publicamente disponíveis uma vez que os PRs contendo os arquivos traduzidos sejam mesclados.

Assumindo que o idioma fr seja o primeiro idioma com as páginas do hub de Documentação (Guia de Início Rápido, Instância web do Playground, Sobre o Playground, Guias,...) completamente traduzidas para Francês, o docusaurus.config.js deve ficar assim nessa branch para que npm run build:docs gere adequadamente o subsite fr e exiba apenas o idioma francês no seletor de idioma localeDropdown:

  {
    "i18n": {
      "defaultLocale": "en",
      "path": "i18n",
      "locales": [
        "en",
        "fr"
      ],
      "localeConfigs": {
        "en": {
          "label": "English",
          "path": "en"
        },
        "fr": {
          "label": "French",
          "path": "fr"
        }
      }
    }
  },
  {
    "type": "localeDropdown",
    "position": "right"
  }

Testando o Seletor de Idioma localmente​

Quanto ao teste do localeDropdown localmente, descobri que embora seja exibido localmente, ele realmente não funciona localmente como esperado, pois as páginas traduzidas não são encontradas. Mas parece funcionar bem em produção.

Você pode testar o localeDropdown de qualquer fork e fazendo da raiz do projeto:

npm run build:docs
npm run deploy:docs

Isso gera três versões da documentação nas GitHub Pages do meu repositório forkado:

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/

Então, uma abordagem possível para testar o recurso localeDropdown é implantá-lo nas GitHub Pages de um repositório forkado.

Processo para traduzir uma página em um idioma​

O processo recomendado é copiar e colar o arquivo .md do caminho original (packages/docs/site/docs) no caminho do idioma desejado (packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current). É importante replicar a estrutura de arquivos em packages/docs/site/docs.

O arquivo sob packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current pode ser traduzido e um PR pode ser criado com as novas alterações.

Quando o PR for mesclado, a versão traduzida dessa página deve aparecer sob https://wordpress.github.io/wordpress-playground/{%LANGUAGE%}