Localización usando gettext

Además de Importar traducciones en formato CSV, Godot también admite la carga de archivos de traducción escritos en el formato GNU gettext (archivos de texto con extensión .po y compilados .mo desde Godot 3.5).

Nota

Para una introducción a gettext, mira en A Quick Gettext Tutorial. Está escrito con proyectos C en mente, pero muchos de los consejos también se aplican a Godot (con la excepción de xgettext).

Ventajas

  • gettext es un formato estándar, que puede ser editado usando cualquier editor de texto o editores GUI como Poedit.

  • Gettext es compatible con plataformas de traducción como Transifex y Weblate, lo que facilita la colaboración de las personas en la localización.

  • Comparado con CSV, gettext funciona mejor con sistemas de control de versiones como Git, ya que cada local tiene su propio archivo de mensajes.

  • Las cadenas multilínea son más convenientes para editar en los archivos gettext en comparación con los archivos CSV.

Desventajas

  • gettext es un formato más complejo que el CSV y puede ser más difícil de entender para las personas nuevas en la localización de software.

  • Las personas que mantienen archivos de localización deberán instalar las herramientas de gettext en su sistema. Sin embargo, como Godot admite el uso de archivos de mensajes en formato de texto (.po), los traductores pueden probar su trabajo sin tener que instalar las herramientas de gettext.

Advertencias

  • Como Godot utiliza su propio analizador de archivos PO entre bastidores (que es más limitado que la implementación de gettext de GNU de referencia), algunas características como la pluralización no están soportadas.

Instalando las herramientas gettext

Las herramientas de gettext de la línea de comando son necesarias para realizar operaciones de mantenimiento, como la actualización de los archivos de mensajes. Por lo tanto, se recomienda encarecidamente instalarlas.

  • Windows: Descargue un instalador de "esta página" <https://mlocati.github.io/articles/gettext-iconv-windows.html>`_. Cualquier arquitectura y tipo binario (compartido o estático) funciona; si tiene dudas, elija el instalador estático de 64 bits.

  • ** macOS: ** Instale gettext usando Homebrew con el comando brew install gettext, o usando MacPorts con el comando sudo port install gettext.

  • Linux: En la mayoría de las distribuciones, instala el paquete gettext del gestor de paquetes de tu distribución.

Creando la plantilla PO (POT) manualmente

Actualmente Godot no soporta la extracción de strings de código fuente usando xgettext, por lo que el archivo .pot debe ser creado manualmente. Este archivo puede ser colocado en cualquier lugar del directorio del proyecto, pero se recomienda mantenerlo en un subdirectorio, ya que cada locale será definido en su propio archivo.

Crear un directorio llamado "local" en el directorio del proyecto. En este directorio, guarda un archivo llamado messages.pot con el siguiente contenido:

# Don't remove the two lines below, they're required for gettext to work correctly.
msgid ""
msgstr ""

msgid "Hello world!"
msgstr ""

Los mensajes en gettext están hechos de pares de msgid y msgstr. msgid es la string fuente (usualmente en inglés), msgstr será la string traducida.

El valor msgstr en los archivos de plantillas PO (.pot) debe siempre estar vacío. La localización se hará en los archivos generados .po en su lugar.

Creando la plantilla PO (POT) usando pylabel

La herramienta Python pybabel tiene soporte para Godot y puede ser usada para crear y actualizar automáticamente el archivo POT de tus archivos y scripts de escenas.

Después de instalar babel y babel-godot, por ejemplo usando pip:

pip3 install babel babel-godot

Escriba un archivo de mapeo (por ejemplo babelrc) que indicará qué archivos necesita procesar pybabel (note que procesamos GDScript como Python, lo que generalmente es suficiente):

[python: **.gd]
encoding = utf-8

[godot_scene: **.tscn]
encoding = utf-8

Entonces puedes ejecutar pybabel así:

pybabel extract -F babelrc -k text -k LineEdit/placeholder_text -k tr -o godot-l10n.pot .

Use la opción -k para especificar lo que necesita ser extraído. En este caso, se traducirán los argumentos de tr(), así como las propiedades denominadas "text" (comúnmente utilizadas por los nodos Control) y la propiedad "placeholder_text" de LineEdit.

Creación de un archivo de mensajes a partir de una plantilla de PO

El comando msginit se usa para convertir una plantilla de PO en un archivo de mensajes. Por ejemplo, para crear un archivo de localización francés, usa el siguiente comando mientras estés en el directorio locale:

msginit --no-translator --input=messages.pot --locale=fr

El comando anterior creará un archivo llamado fr.po en el mismo directorio que la plantilla PO.

Alternativamente, puedes hacerlo gráficamente usando Poedit, o subiendo el archivo POT a la plataforma web de tu elección.

Cargando un archivo de mensajes en Godot

Para registrar un archivo de mensajes como una traducción en un proyecto, abra el Configuración del proyecto, y luego vaya a la pestaña Localización. En Traducciones, haz clic en Agregar... y luego elige el archivo .po en el diálogo de archivos. La localización se obtendrá a partir del "Language: <code>\n" propiedad en el archivo de mensajes.

Nota

Ver Internacionalizando los juegos para más información sobre la importación y prueba de traducciones en Godot.

Actualizando los archivos de mensajes para seguir la plantilla de PO

Después de actualizar la plantilla de PO, tendrá que actualizar los archivos de mensajes para que contengan nuevas strings, al tiempo que elimina las strings que ya no están presentes en la plantilla de PO eliminadas en la plantilla de PO. Esto se puede hacer automáticamente usando la herramienta msgmerge:

# The order matters: specify the message file *then* the PO template!
msgmerge --update --backup=none fr.po messages.pot

Si quieres mantener una copia de seguridad del archivo de mensajes original (que se guardaría como fr.po~ en este ejemplo), elimina el argumento -backup=none.

Nota

Después de ejecutar msgmerge, las cadenas que fueron modificadas en el idioma fuente tendrán un comentario fuzzy agregado antes de ellas en el archivo .po. Este comentario indica que la traducción debe actualizarse para que coincida con la nueva cadena fuente, ya que es probable que la traducción sea inexacta hasta que se actualice.

Las cadenas con comentarios "fuzzy" no serán leídas por Godot hasta que la traducción se actualice y se elimine el comentario "fuzzy".

Comprobación de la validez de un archivo PO o plantilla

Es posible comprobar si la sintaxis de un archivo gettext es válida ejecutando el siguiente comando:

msgfmt fr.po --check

Si hay errores de sintaxis o advertencias, se mostrarán en la consola. De lo contrario, msgfmt no emitirá nada.

Usar archivos binarios MO (útiles solo para proyectos grandes)

Para proyectos grandes con miles de cadenas para traducir o más, puede valer la pena utilizar archivos binarios MO (compilados) en lugar de archivos PO en formato de texto. Los archivos binarios MO son más pequeños y más rápidos de leer que los archivos PO equivalentes.

Puedes generar un archivo MO con el siguiente comando:

msgfmt fr.po --no-hash -o fr.mo

Si el archivo PO es válido, este comando creará un archivo "fr.mo" junto al archivo PO. Este archivo MO luego puede cargarse en Godot según se describe a continuación.

El archivo PO original debe mantenerse en el control de versiones para poder actualizar la traducción en el futuro. En caso de que pierdas el archivo PO original y desees descompilar un archivo MO en un archivo PO en formato de texto, puedes hacerlo utilizando el siguiente comando:

msgunfmt fr.mo > fr.po

El archivo descompilado no incluirá comentarios ni cadenas "fuzzy", ya que estos nunca se compilan en el archivo MO en primer lugar.