Traducir el contenido¶

Aunque el inglés es un idioma muy común entre los desarrolladores de software, hay muchos desarrolladores que no hablan inglés o no lo hablan con fluidez. Se trata de una incidencia de accesibilidad para los desarrolladores, por lo que queremos ofrecer nuestra documentación en tantos idiomas como sea posible.

Lamentablemente, el equipo central de BeeWare está formado, en su mayoría, por personas monolingües de habla inglesa. Necesitamos tu ayuda para traducir nuestra documentación a otros idiomas.

Utilizamos Weblate para gestionar nuestras traducciones. Weblate es una herramienta que nos permite tratar cada párrafo del contenido de nuestra documentación como una lista de tareas pendientes en la que podemos trabajar de una en una.

Utilizamos DeepL para que la traducción automática produzca una primera pasada de las traducciones. Las traducciones automáticas distan mucho de ser perfectas, pero suelen ser suficientemente buenas como primer borrador. Se espera que sean editadas, revisadas y mejoradas estas traducciones automáticas cuando sea necesario.

Contribución de traducciones¶

Traducir contenido

Primeros pasos con la traducción¶

Si quieres contribuir a los esfuerzos de traducción de BeeWare, necesitarás una cuenta en Weblate. Crea una cuenta nueva si aún no la tienes y haznos saber que estás interesado en ayudar con las traducciones.

Existen dos opciones para hacernos saber que desea colaborar con las traducciones:

Si estás en Discord, únete al servidor BeeWare, y dirígete al canal #translations.
Si no estás en Discord, puedes crear una incidencia nueva en el repositorio BeeWare.

En ambos casos, deje un mensaje incluyendo la siguiente información:

Tu nombre de usuario en Weblate
El idioma al cual tiene previsto traducir los contenidos

Una vez que tengamos esta información, te añadiremos al equipo.

Añadir una traducción nueva¶

Si el idioma en la que quiere colaborar aún no existe, hay algunos pasos adicionales necesarios antes que pueda comenzar:

Crea el archivo /docs/mkdocs.language-code.yml, con contenido específico para cada idioma.
Actualice tox.ini para incluir los nuevos comandos de construcción de idioma.
Actualice /docs/config.yml para incluir el idioma bajo extra: alternate:.

Lo siguiente demuestra los cambios necesarios utilizando el alemán como un ejemplo; ya existe una traducción al alemán; sustituya las referencias al alemán, de u otro contenido para el idioma al que se dirija.

Un archivo de configuración nuevo de MkDocs¶

En primer lugar, cree un archivo nuevo llamado mkdocs.de.yml en el directorio docs, con el siguiente contenido:

INHERIT: config.yml
site_name: BeeWare Documentación
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  language_url: de/
  translation_type: machine
  header:
    About: Acerca de
    Documentation: Documentación
    Community: Comunidad
    Contributing: Colaborar
    News: Noticias
    Sponsor: Patrocinadores

Aquí está lo que ocurre en este archivo:

Este archivo hereda el contenido de configuración desde config.yml.
El valor site_name está traducido.
El valor site_url es la URL del sitio del proyecto, seguida del código de idioma.
El docs_dir sería el código del idioma.
El valor theme: language: sería el código del idioma, como especificado por el tema MkDocs Material. Para la mayoría de los idiomas, este será el mismo que el código de idioma docs_dir; pero para algunos (en particular idiomas con variantes locales como zh_CN), hay diferencias.
El extra: language_url: sería el código del idioma, seguido de una sola barra torcida, p.e., de/ para alemán.
El extra: translation_type: sería machine hasta que la traducción alcance el 100% por primera vez, momento en el cual sería human. Se revertirá a machine desde human si retrocede por debajo del 90%.
El contenido entre extra: header son las traducciones de los títulos que aparecen en la barra de encabezado. Esta definición no es necesaria en el sitio web principal de BeeWare; solo se requiere en otros sitios (como el tutorial, o la documentación del proyecto).

Actualizar `tox.ini`¶

Tendrás que hacer varios cambios en el archivo tox.ini.

Añadirías lo siguiente:

El indicador nuevo del código de idioma del entorno a la línea de cabecera que comienza por [testenv:docs, con el código de idioma precedido por un -, sin espacios incluidos, p.e., -de.
El nuevo código de idioma de exclusión al primer comando, que comienza con !lint, precedido por -!, sin espacios incluidos, por ejemplo, -!de.
El código de idioma nuevo para la línea que comienza con translate : build_po_translations.
El código de idioma nuevo para la línea que comienza por translate : update_machine_translations
Un comando nuevo, que comienza, por ejemplo, con de : build_md_translations para alemán, en orden alfabético dentro de los comandos específicos del idioma existentes que coinciden con el contenido de esos comandos, con el código nuevo de idioma.
El código nuevo de idioma para la línea que comienza con all:.

Actualizar `config.yml`¶

Añade el idioma a config.yml para que aparezca en el selector de idioma de la cabecera. Busque la sección que empieza por extra: y, a continuación, localice la subsección que empieza por alternate:. Para el alemán, añada lo siguiente:

- nombre: Alemán
        enlace: /de/
        idioma: de

El nombre del idioma debe traducirse al idioma. El enlace debe incluir el /s.

Ejecutar `tox translate`¶

Ahora puede ejecutar tox -e docs-translate. Esto generará un archivo de traducción vacío; si tiene una cuenta DeepL, puede utilizarla para rellenar las traducciones automáticas iniciales. Si no tiene una cuenta DeepL, no se preocupe: nosotros mismos realizaremos las traducciones iniciales antes de aceptar la solicitud de incorporación de cambios.

Pautas de traducción¶

Una vez que te hayan añadido al equipo, es hora de iniciar sesión en Weblate y empezar a trabajar en la traducción de cadenas.

El tono frente a la traducción palabra por palabra¶

Es más importante mantener el tono del texto inglés que esforzarse por traducir palabra por palabra. Tratamos de ser amables y un poco coloquiales en nuestros contenidos; intenta mantener ese espíritu en tus traducciones.

Si el texto en inglés contiene un modismo inglés fuerte, no se sienta obligado a mantener el modismo, si hay un análogo en su idioma que funcionaría igualmente bien. Si el término o frase del texto en inglés es especialmente idiomático o de argot, no tema decirnos que deberíamos considerar la posibilidad de cambiarlo. Incluso para los angloparlantes, los modismos y el argot pueden plantear dificultades. A veces tenemos que cambiar el texto inglés para que resulte más sencillo tanto para los traductores como para los lectores.

¿Debo traducirlo?¶

Los siguientes elementos no serían traducidos ni actualizados:

Comandos. Por ejemplo, en "You should run `briefcase create`.", sólo "You should run" sería traducido.
Espacios de nombres, como nombres de clase, método o atributo.
Las URL de enlaces. Los enlaces Markdown estándar deben aparecer en Weblate como [Link text]{1}, donde 1 es la posición del enlace en la cadena con referencia a otros posibles enlaces. Si se incluye en la cadena la URL completa, como [Link text](https://example.com), la URL debería omitirse para la traducción.
Enlaces de referencia que contengan nombres de clase, método o atributo. Deben dejarse como están, incluidos los puntos suspensivos. Todas las partes del enlace de ejemplo que se muestra aquí no sería traducido.
```
[`Class.attribute`][Class.attribute]
```
El contenido del enlace de un enlace de Referencia. Por ejemplo, link-content se omitiría en lo siguiente:
```
[Link text][link-content]
```
Directivas Jinja. Se trata de cualquier contenido envuelto dentro de dos pares de llaves coincidentes, o un par de llaves coincidentes con signos de porcentaje en cada extremo. Nota: Incluir un ejemplo de la sintaxis aquí hace que el plugin Macros intente representarla; consulte la documentación de Macros para ejemplos.
Anclas personalizadas. Se encuentran tras cabeceras o encima de algún contenido, y se dan formato como { #anchor }.
Sintaxis de admonición. En el ejemplo de a continuación, la palabra «admonición» no debe traducirse. Esto es válido para todos los estilos de amonestación, incluyendo notas, advertencias, etc. Consulte la siguiente sección para obtener información sobre la traducción del resto del contenido.
```
/// admonition | Título de la página

Contenido.

///
```
Tildes. Están pensadas para permanecer como tildes graves; se utilizan para dar formato tanto al código en línea como a los bloques de código.
La sintaxis para incluir contenido externo. Esto es cualquier cosa en la misma línea que -8<-, o en las líneas entre dos -8<- en líneas separadas.

Los siguientes elementos serían traducidos:

Texto del enlace. En la sintaxis de los enlaces, el texto va antes de la URL, y están encerrados entre corchetes, como en [Texto del enlace](URL). Los enlaces Markdown estándar aparecerían en Weblate como [Texto del enlace]{1}, donde 1 es la posición del enlace en la cadena con referencia a otros posibles enlaces.
Texto del enlace de referencia. Por ejemplo, Link text sería traducida de la siguiente manera:
```
[Link text][link-content]
```
Títulos y contenido de la admonición. En el ejemplo anterior de admonición, "Título de la página" y "Contenido" serían traducidas.

Weblate¶

Utilizamos Weblate para la traducción de nuestros contenidos. Cuando añadimos una traducción nueva, utilizamos DeepL para que la traducción automática produzca una primera pasada de las traducciones. Esto significa que, normalmente, el contenido que estás traduciendo ya está traducido automáticamente. La expectativa es que tú, como traductor, revises, edites y mejores la traducción automática existente.

Weblate procesa todo cadena por cadena. Agrupa los cambios y, cada dos horas, envía una confirmación masiva con todas las cadenas que han cambiado en ese intervalo. Por lo tanto, los cambios pueden tardar un par de horas en aparecer en el sitio web, pero puede esperar que la actualización aparezca en cuatro horas.

Si después de ese tiempo, tus cambios aún no aparecen, la causa probable es un error de marcado, lo que provoca un fallo en la construcción de la documentación para ese idioma. Cualquier problema de marcado en cualquier cadena bloqueará la publicación de toda la traducción. Puedes estar atento a la página de compilación de tu idioma para ver si se ha compilado correctamente. El enlace tiene un formato similar a este enlace a la página de creación en francés https://app.readthedocs.org/projects/beewareorg/; cambia el código de idioma por el de tu idioma para ver la página de creación correspondiente. Esto mostrará el estado de la construcción más reciente del sitio. Si la construcción falla, consulta el registro de compilación y comprueba si puedes identificar el origen del problema.