Ansel utiliza Gettext  para traducir todas las partes del proyecto:

  • La aplicación del software (escrita en C),
  • El sitio web (plantillas Hugo y contenido Markdown),
  • La documentación/manual de usuario, insertado en el sitio web como un módulo (plantillas Hugo y contenido Markdown también).

Esto asegura que se pueda utilizar el mismo flujo de trabajo para traducir todos los archivos, pero también que algunas cadenas traducidas se puedan compartir (por ejemplo, los controles GUI traducidos de las aplicaciones se pueden insertar directamente en la documentación).

Organización de archivos de traducción

El código fuente del sitio web, documentación y software contiene un subdirectorio inmediato po/, que contiene:

  • un archivo .pot que contiene todas las líneas disponibles, traducibles en su idioma original (en inglés),
  • muchos archivos .po que coinciden con las cadenas traducibles en su idioma original con su traducción (un archivo por idioma).

Los archivos de traducción están todos nombrados siguiendo la convención código-de-idioma.po. Por ejemplo:

  • para alemán,
    • la traducción del software es de.po,
    • la traducción del sitio web es content.de.po,
    • la traducción de la documentación es content.de.po,
  • para portugués brasileño,
    • la traducción del software es pt_BR.po,
    • la traducción del sitio web es content.pt_br.po,
    • la traducción de la documentación es content.pt_br.po.

Traducir cuando no puedes usar CLI/Git

Necesitarás localizar el archivo .po relevante para tu idioma para la parte del proyecto que deseas traducir:

  1. Descarga este archivo y ábrelo con Poedit ,
  2. Realiza las correcciones y ediciones necesarias,
  3. Agrega tu nombre en un comentario para las cadenas que traduzcas si deseas ser acreditado en la página:
    • Las cadenas traducidas automáticamente tendrán TRANSLATOR ChatGPT allí, una vez que verifiques esas cadenas, por favor elimina esta línea,
    • Luego agrega un comentario que contenga TRANSLATOR Tu Nombre en una nueva línea. Mantén a otros contribuyentes (que no sean ChatGPT) allí, si los hay.
  4. Guarda el archivo y:
    • Alternativa 1 (más fácil para el colaborador, más pasos para el mantenedor): déjalo en mi nube privada ,
    • Alternativa 2 (más pasos para el colaborador, más fácil para el mantenedor): compromételo con Git y abre una solicitud de extracción contra el repositorio adecuado de Github.

Translating for power users

Esto actualizará el archivo .pot usando el código fuente del proyecto. Necesitarás tener Git instalado, y Hugo 0.146  instalado en tu computadora.

  1. Clona el código fuente del proyecto relevante:
    • el software:
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel.git
3$ cd ansel
    • el sitio web:
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-website.git
3$ cd ansel-website
    • la documentación:
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-doc.git
3$ cd ansel-doc
    Luego, actualizarás el repositorio usando:
    1$ git pull
  2. Actualiza el archivo .pot y todos los archivos .po desde el código fuente (este paso funciona igual para los 3 proyectos):
    1$ sh tools/update-translations.sh
  3. Traduce el archivo .po relevante usando Poedit o directamente en un editor de texto (ver Traducir cuando no puedes usar CLI/Git),
  4. Prueba y revisa tu traducción:
    • Para el software, necesitarás compilar Ansel en tu SO. Por favor, consulta la documentación.
    • Para el sitio web y la documentación, puedes ejecutar:
      1sh build-modules.sh
2hugo
    Presta atención a cualquier error crítico de po4a, especialmente por caracteres \n que no coinciden, y errores de Hugo, especialmente con respecto a la sintaxis de shortcodes.
  5. Para el sitio web y la documentación, limpia los archivos Markdown traducidos (generados automáticamente por po4a usando el archivo .po) antes de comprometer, usando:
    1sh tools/build-translations.sh --remove
  6. Compromete todos los archivos .pot y .po y abre una solicitud de extracción contra el repositorio de Github relevante. Nunca comprometa archivos .md (Markdown) traducidos.

Translating images

Lo siguiente se aplica solo al sitio web y a la documentación.

Las imágenes también se pueden traducir, por ejemplo, capturas de pantalla de aplicaciones. Las imágenes se almacenan en la carpeta assets/ si se reutilizan en varias páginas (recursos globales), de lo contrario, se almacenan en la misma carpeta que el archivo Markdown que las usa (recursos locales). Tanto si son globales como locales, el proceso de traducción es el mismo, solo cambia la carpeta base.

Si, por ejemplo, deseas traducir el assets/screenshot.jpg para el idioma LANG (que es el código ISO del idioma, como de, nl, pt_br, zn_cn, etc.):

  1. agrega y compromete un nuevo archivo de imagen assets/screenshot.LANG.jpg al repositorio de Git de documentación o del sitio web,
  2. en el content.LANG.po, localiza la entrada que contiene la etiqueta Markdown de la imagen original, que será algo como ![texto alternativo](screenshot.jpg),
  3. traduce la etiqueta Markdown reemplazando la URL de la imagen, como ![texto alternativo traducido](screenshot.LANG.jpg,
  4. guarda y compromete el archivo content.LANG.po,
  5. crea una solicitud de extracción contra el repositorio del sitio web o docs de Ansel.

Herramientas automáticas y scripts de ayuda

Inicializar traducción de documentación con la del software

Debido a que la documentación y el software comparten las mismas cadenas para los controles GUI, puedes inicializar parcialmente las cadenas de documentación a partir de las del software si coinciden exactamente (incluida la capitalización). Esto requiere un intérprete de Python y el paquete regex (instalar con pip install -U regex). Desde el código fuente de la documentación, puedes llamar:

1$ python tools/merge-translations.py path/to/software path/to/doc

Traducción automática de documentación y sitio web con ChatGPT

ChatGPT-4o hace un trabajo bastante justo al traducir texto formateado en Markdown desde el inglés, aunque no en todos los idiomas. Necesitarás una clave API privada para almacenar en la carpeta de documentación o sitio web en un archivo .chatgpt.api_key. Luego, las llamadas a la API de ChatGPT no son gratuitas, y el pago mínimo de 5 US$ te dará aproximadamente el sitio web completamente traducido en 4 idiomas.

El script todo en uno se puede llamar usando:

1$ sh auto-translate.sh LANG

donde LANG es el código del idioma de destino (de, fr, pt_br, etc.). Esto procesará la traducción en lotes de 90 a 120 cadenas para cumplir con las limitaciones y umbrales de la API de ChatGPT. Esto:

  • analizará el archivo original po/content.LANG.po y exportará el lote a traducir en un archivo temporal po/content.LANG.txt,
  • enviará el archivo po/content.LANG.txt a ChatGPT y obtendrá la respuesta en po/content.LANG.generated.txt
  • solucionará la mayoría de las inconsistencias de formato comunes que ChatGPT puede introducir e inyectar las traducciones de nuevo en po/content.LANG.po,
  • construirá archivos Markdown traducidos (siguiendo la convención de nomenclatura página.LANG.md),
  • construirá el sitio web con Hugo.

Si todos estos pasos se completan sin errores, entonces estarás bien para ejecutar el script nuevamente para procesar el siguiente lote hasta la finalización. Si se muestran errores, necesitarás corregirlos. Solo ejecutamos un lote en cada llamada para darle al usuario la oportunidad de encontrar errores mientras no hay demasiados cambios para inspeccionar.

Errores comunes:

  • nada se traducirá: verifica la respuesta de ChatGPT dentro de po/content.LANG.generated.txt, a veces no puede entender su misión. Puedes intentar nuevamente, a veces funciona en la tercera llamada. Pero a menudo, no hay nada que hacer y algunos idiomas/cadenas no se pueden traducir en absoluto.
  • al construir el sitio web con Hugo, algunos shortcodes no se pueden encontrar. Esto se debe a que los shortcodes se declaran así: {{< nombre_del_shortcode >}}. A veces, ChatGPT intentará traducir nombre_del_shortcode y el shortcode ya no funcionará. La solución es recuperar el nombre en inglés para el shortcode y sus atributos,
  • lo mismo con los gráficos Mermaid , ChatGPT puede intentar traducir comandos y propiedades que no deberían ser traducidos,
  • las cadenas originales terminan con el carácter de nueva línea \n y las cadenas traducidas no (o viceversa). El script intenta sanear eso, pero algunos casos extremos no se manejan. Las cadenas msgid originales y su traducción msgstr en el archivo .po deben tener el mismo número de caracteres \n en los mismos lugares,
  • comillas dobles mal escapadas: las cadenas Gettext msgid y msgstr deben estar delimitadas por comillas dobles no escapadas " en cada extremo de la cadena. Cualquier otra comilla doble, dentro de la cadena Gettext, debe escapar usando \".

La mejor manera de corregir errores es abrir el archivo .po relevante en un editor de texto. Si no puedes encontrar y resolver el error, puedes intentar abrir el archivo en Poedit, pero al guardar, generalmente borrará completamente las cadenas defectuosas sin corregirlas, por lo que la traducción deberá comenzar de nuevo desde cero.

Construir archivos Markdown traducidos

Para el sitio web y la documentación, Hugo  maneja las traducciones de cualquier página dada new_page.md usando la convención de nombres new_page.LANG.md, donde LANG es el código del idioma. Hugo admite nativamente escribir manualmente estos archivos traducidos en la misma carpeta que su original, sin embargo, aquí los generamos usando el archivo de traducción .po y el programa po4a. Los scripts build-modules.sh y tools/auto-translate.sh manejan esto internamente, pero puedes querer generar esos archivos manualmente:

  1. Actualiza los archivos .pot y .po con el código fuente:
    1$ sh tools/update-translations.sh
  2. Crea los archivos .md traducidos:
    1$ sh tools/build-translations.sh --add
  3. Limpia los archivos .md traducidos:
    1$ sh tools/build-translations.sh --remove

Es importante no comprometer nunca los archivos .md traducidos con Git, ya que se regeneran solo por ese script al construir el sitio web. Esto es solo por la higiene del repositorio, no hay inconveniente técnico. Limpiar los .md traducidos antes de comprometerse asegura que no haya errores.

¿Perdido en la traducción?

Si tienes problemas o preguntas, no dudes en preguntar en el canal de traductores de Matrix  dedicado.

Notas para traductores

Política sobre mayúsculas

El proyecto darktable dio prioridad a poner todo en minúsculas, lo que hace que la GUI sea difícil de leer, especialmente para las herramientas que tienen varias oraciones. Las mayúsculas anclan visualmente el comienzo de oraciones y otros textos importantes, como botones, controles, etc. No es casualidad si todos los idiomas convergieron en usarlas (aunque el alemán tiene su particular manera de ponerlas en todas partes), ayudan a la legibilidad tanto si te gusta su estética o no.

El código fuente de Ansel reutiliza la mayoría de las etiquetas de darktable y agrega una mayúscula inicial en la mayoría de los lugares donde se necesitan (encabezados de los módulos, botones). Esto se hace mediante un poco de código usando la función C g_unichar_toupper() de Gtk Glib, de modo que el texto original en inglés permanezca en minúsculas para mantener la compatibilidad con las traducciones.

Esta solución programática funciona para caracteres no acentuados, sin importar el idioma utilizado (cadenas predeterminadas en inglés, o traducciones). Sin embargo, no funciona para caracteres iniciales acentuados, que no se capitalizarán. En este caso, se pide a los traductores que fuercen su traducción para usar caracteres acentuados iniciales en mayúscula siempre que sean gramaticalmente correctos en su idioma.

Las nuevas etiquetas o las etiquetas antiguas recientemente cambiadas (lo que rompería las traducciones de todos modos) obtendrán mayúsculas iniciales de ahora en adelante, en el código fuente (versión en inglés), por lo que esto debería arreglarse progresivamente.

Traducción de términos técnicos

Términos técnicos relacionados con la teoría del color y la colorimetría deben traducirse exactamente del inglés, con mucho cuidado porque estos términos pueden existir también en lenguaje común (es decir, no técnico) pero con un significado diferente. La Comisión Electrotécnica Internacional  proporciona un motor de búsqueda donde puedes buscar los términos técnicos en inglés y obtener las traducciones precisas en diferentes idiomas, incluidos los principales europeos así como el árabe y el chino.

Notas para los traductores francófonos

La traducción de darktable tiene rarezas incomprensibles para cualquiera que haya usado una computadora de escritorio durante más de 10 años. Aquí hay una lista rápida de errores a corregir:

  • ‘set’ se traduce como ‘positionné’ pero su traducción correcta es ‘réglé’. Es ilógico porque ‘settings’ se traduce correctamente como ‘réglages’. En Ansel, solo se posicionan máscaras (o sus nodos de control) en el plano 2D. El resto son ajustes.
  • ‘reset’ se traduce como ‘repositionné’ pero su traducción correcta es ‘réinitialiser’.
  • En inglés, un gran número de verbos tienen la misma grafía para su infinitivo y su participio pasado, e incluso existe como sustantivo (‘set’, en el ejemplo arriba, puede ser traducido como ‘fijado’ o ‘ajustar’ o como ‘conjunto’ en su forma substantivada). Si se requiere una acción (aún no realizada), en francés se debe usar el infinitivo. Si una acción ya está hecha, se debe usar el participio pasado. Las cosas se complican para los sustantivos porque el inglés no siempre requiere un determinante delante, por lo que hay que deducirlo del contexto. A observar: ‘click’ (hacer clic o clic), ’type’ (tipo o escribir/teclear), etc.
Translated from English by : ChatGPT. In case of conflict, inconsistency or error, the English version shall prevail.