Ir al contenido principal

Contribuciones a las traducciones

Puedes ayudar a traducir la documentación de Playground a cualquier idioma. Esta página proporciona una guía completa sobre cómo contribuir a la traducción de los documentos de Playground.

¿Cómo puedo contribuir a las traducciones?​

Usando el mismo flujo de trabajo que para contribuir a cualquier otra página de la documentación. Puedes hacer un fork de WordPress/wordpress-playground y hacer PRs con tus cambios, o editar las páginas directamente usando la interfaz de usuario de GitHub.

información

Consulta ¿Cómo puedo contribuir? para aprender más sobre cómo contribuir a la documentación de Playground.

Detalles de la implementación de las traducciones​

información

Consulta la sección de Internacionalización de la documentación de Docusaurus para aprender más sobre la gestión de traducciones en un sitio web de Docusaurus (el motor detrás de la documentación de Playground).

Los idiomas disponibles para el sitio de documentación se definen en packages/docs/site/docusaurus.config.js. Por ejemplo:

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

Las páginas de documentación traducidas se encuentran en el repositorio WordPress/wordpress-playground.

Dentro de packages/docs/site/i18n/, hay una carpeta para cada idioma. Por ejemplo, para es (español), hay una carpeta packages/docs/site/i18n/es.

Dentro de cada carpeta de idioma, debería haber una carpeta docusaurus-plugin-content-docs/current. Por ejemplo, para es (español), hay una carpeta packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current.

Dentro de docusaurus-plugin-content-docs/current, se debe replicar la misma estructura de archivos de la documentación original (la misma estructura de archivos que se encuentra en packages/docs/site/docs).

Por ejemplo, para es (español), existen los siguientes archivos traducidos: packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/main/intro.md

Si un archivo no está disponible en la carpeta de un idioma, se cargará el archivo original en el idioma por defecto.

Cuando se añade un nuevo idioma (ver PR #1807), puedes ejecutar npm run write-translations -- --locale <%LANGUAGE%> desde packages/docs/site para generar los archivos JSON que contienen los mensajes que se pueden traducir a un idioma específico.

Con la configuración adecuada de i18n en docusaurus.config.js y los archivos en i18n, al ejecutar npm run build:docs desde la raíz del proyecto, se crearán carpetas específicas para cada idioma en dist.

Cómo probar un idioma localmente​

Para probar un idioma existente localmente, puedes hacer lo siguiente:

  • Modifica (traduce) cualquier archivo en uno de los idiomas disponibles: packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current
  • Desde /packages/docs/site ejecuta la versión para el idioma que te gustaría probar. Por ejemplo, para probar es:

npm run dev:docs -- --locale es

Selector de idioma - Elemento de la interfaz de usuario para cambiar de idioma​

El "Selector de idioma" es un elemento de la interfaz de usuario proporcionado por Docusaurus (el motor de documentación detrás de Playground Docs) que permite a los usuarios cambiar el idioma de una página específica.

Para dar más visibilidad a una versión traducida, se puede mostrar el selector de idioma añadiendo las siguientes líneas a packages/docs/site/docusaurus.config.js


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

Esto generará un menú desplegable en la cabecera para acceder directamente a la versión de cada archivo en un idioma.

Se recomienda encarecidamente que un idioma específico se active en este menú desplegable solo cuando haya una cantidad considerable de páginas traducidas. Si se activa con pocas páginas traducidas, la experiencia del usuario será que cada vez que cambie de idioma, ninguna página estará traducida a ese idioma.

Hacer que un idioma esté disponible públicamente en el Selector de idioma​

Todos los idiomas están disponibles una vez que la configuración de i18n para un idioma está completa y la estructura de archivos correcta está en su lugar en i18n.

Estas versiones de la documentación en otros idiomas deben estar ocultas en el selector de idioma hasta que haya una cantidad considerable de páginas traducidas para ese idioma. Para ser más precisos, la recomendación es hacer que un idioma esté disponible públicamente en el Selector de idioma solo cuando al menos la sección de Documentación esté completamente traducida para un idioma específico, incluyendo las siguientes secciones:

Incluso si el selector de idioma no muestra un idioma específico, el trabajo de añadir páginas traducidas puede continuar, ya que las páginas traducidas estarán disponibles públicamente una vez que se fusionen los PRs que contienen los archivos traducidos.

Suponiendo que el idioma fr es el primer idioma con las páginas del hub de Documentación (Guía de inicio rápido, instancia web de Playground, Acerca de Playground, Guías,...) completamente traducidas al francés, el docusaurus.config.js debería verse así en esa rama para que npm run build:docs genere correctamente el subsitio fr y solo muestre el idioma francés en el selector 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"
  }

Probar el Selector de idioma localmente​

En cuanto a probar el localeDropdown localmente, he descubierto que aunque se muestra localmente, no funciona como se esperaba, ya que no se encuentran las páginas traducidas. Pero parece que funciona bien en producción.

Puedes probar el localeDropdown desde cualquier fork y hacerlo desde la raíz del proyecto:

npm run build:docs
npm run deploy:docs

Esto genera tres versiones de la documentación en las Páginas de GitHub de mi repositorio "forkeado":

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/

Un posible enfoque para probar la función localeDropdown es desplegarla en las Páginas de GitHub de un repositorio "forkeado".

Proceso para traducir una página a un idioma​

El proceso recomendado es copiar y pegar el archivo .md desde la ruta original (packages/docs/site/docs) a la ruta del idioma deseado (packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current). Es importante replicar la estructura de archivos que hay en packages/docs/site/docs.

El archivo en packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current puede ser traducido, y se puede crear un PR con los nuevos cambios.

Cuando el PR se fusione, la versión traducida de esa página debería aparecer en https://wordpress.github.io/wordpress-playground/{%LANGUAGE%}

Proceso de revisión​

Para facilitar el proceso de revisión, recomendamos mantener el contenido original comentado cerca del contenido traducido, por ejemplo:

<!--
👋 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.
-->

👋 ¡Hola! Bienvenido a la documentación de WordPress Playground.

Playground es una herramienta en línea para experimentar y aprender sobre WordPress. Este sitio (Documentación) es donde encontrarás toda la información que necesitas para empezar a usar Playground.

<!--
<p class="docs-hubs">The WordPress Playground documentation is distributed across four separate hubs (subsites):</p>
-->
<p class="docs-hubs">La documentación de WordPress Playground se distribuye en cuatro hubs (subsitios) separados:</p>

Para un proceso de revisión mejorado, busca revisores que coincidan con el idioma del PR. Solicita un revisor publicando en https://make.wordpress.org/polyglots/ e incluye la etiqueta de la configuración regional (por ejemplo, #ja para japonés). Esto notificará a los GTEs japoneses.