Traducción de contenidos¶

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 un problema 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 de 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 estas traducciones automáticas sean editadas, revisadas y mejoradas cuando sea necesario.

Contribución de traducciones¶

Traducir contenido

Empezar a traducir¶

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 nueva incidencia en el repositorio BeeWare.

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

Tu nombre de usuario de Weblate
La lengua a la que tiene previsto traducir los contenidos

Cuando tengamos esta información, te añadiremos al equipo.

Añadir una nueva traducción¶

Si la lengua en la que quiere colaborar aún no existe, deberá seguir algunos pasos antes de empezar:

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

A continuación se muestran los cambios necesarios utilizando el alemán como 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 nuevo archivo de configuración de MkDocs¶

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

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

Esto es lo que ocurre en este archivo:

Este archivo hereda el contenido de configuración de config.yml.
Se traduce el valor site_name.
El valor site_url es la URL del sitio del proyecto, seguida del código de idioma.
El docs_dir debe ser el código del idioma.
El valor theme: language: debe ser 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: translation_type: debe ser machine hasta que la traducción alcance el 100% por primera vez, momento en el que debe ser human. Se revertirá a machine desde human si retrocede por debajo del 90%.

Actualizar `tox.ini`¶

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

Añadirías lo siguiente:

La nueva bandera de entorno de código de idioma a la línea de cabecera que comienza [testenv:docs, con el código de idioma precedido por un -, sin espacios incluidos, por ejemplo, -de.
El nuevo código de lenguaje de exclusión al primer comando, que comienza con !lint, precedido por -!, sin espacios incluidos, por ejemplo, -!de.
El código del nuevo idioma al final de la línea que empieza por translate : build_po_translations.
El nuevo código de idioma al final de la línea que empieza por translate : update_machine_translations.
Un nuevo comando, que comienza, por ejemplo, con de : build_md_translations para el alemán, después de los otros comandos específicos de idioma existentes que coincide con el contenido esos comandos con el nuevo código de idioma.
El nuevo código de idioma al final de la línea que empieza por all,serve :.

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:

    - name: Deutsch
      link: /de/
      lang: de

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

La nueva lengua ya está lista para empezar a traducirse.

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 fuerte modismo inglés, 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 deben traducirse ni actualizarse:

Comandos. Por ejemplo, en "You should run `briefcase create`.", sólo "You should run" debe ser traducido.
Espacios de nombres, como nombres de clases, métodos o atributos.
URLs 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 la URL completa se incluye en la cadena, como [Link text](https://example.com), la URL debe omitirse para la traducción.
Enlaces de referencia que contengan nombres de clases, métodos o atributos. Deben dejarse como están, incluidos los puntos suspensivos. Todas las partes del enlace de ejemplo que se muestra aquí no se traducirían.
```
[`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 renderizarla; vea la documentación de Macros para ejemplos.
Anclas personalizadas. Se encuentran después de las cabeceras o encima de algún contenido, y se formatean como { #anchor }.
Sintaxis de la admonición. En el siguiente ejemplo, 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 | Page Title

Content.

///
```
Tildes. 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 puntos deberían traducirse:

Texto del enlace. En la sintaxis de los enlaces, el texto va antes de la URL y va entre corchetes, como en [Texto del enlace](URL). Los enlaces Markdown estándar deben aparecer 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 se traduciría de la siguiente manera:
```
[Link text][link-content]
```
Títulos y contenido de la admonición. En el ejemplo anterior, "Título de la página" y "Contenido" deben traducirse.

Weblate¶

Utilizamos Weblate para la traducción de nuestros contenidos. Cuando añadimos una nueva traducción, utilizamos DeepL para que la traducción automática produzca una primera pasada de las traducciones. Esto significa que, normalmente, el contenido que vas a traducir 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 compilació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 compilació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 compilación correspondiente. Esto mostrará el estado de la compilación más reciente del sitio. Si la compilación falla, consulta el registro de compilación y comprueba si puedes identificar el origen del problema.