Localización usando gettext¶

In addition to Importar traducciones in CSV format, Godot also supports loading translation files written in the GNU gettext format (text-based .po and compiled .mo since 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 un formato estándar, que puede ser editado usando cualquier editor de texto o editores GUI como Poedit.
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.
People who maintain localization files will have to install gettext tools on their system. However, as Godot supports using text-based message files (.po), translators can test their work without having to install gettext tools.

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¶

To register a messages file as a translation in a project, open the Project Settings, then go to the Localization tab. In Translations, click Add… then choose the .po or .mo file in the file dialog. The locale will be inferred from the "Language: <code>\n" property in the messages file.

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¶

After updating the PO template, you will have to update message files so that they contain new strings, while removing strings that are no longer present in the PO template. This can be done automatically using the msgmerge tool:

# 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

After running msgmerge, strings which were modified in the source language will have a "fuzzy" comment added before them in the .po file. This comment denotes that the translation should be updated to match the new source string, as the translation will most likely be inaccurate until it's updated.

Strings with "fuzzy" comments will not be read by Godot until the translation is updated and the "fuzzy" comment is removed.

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.

Using binary MO files (useful for large projects only)¶

For large projects with several thousands of strings to translate or more, it can be worth it to use binary (compiled) MO message files instead of text-based PO files. Binary MO files are smaller and faster to read than the equivalent PO files.

You can generate a MO file with the command below:

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

If the PO file is valid, this command will create a fr.mo file besides the PO file. This MO file can then be loaded in Godot as described below.

The original PO file should be kept in version control so you can update your translation in the future. In case you lose the original PO file and wish to decompile a MO file into a text-based PO file, you can do so with:

msgunfmt fr.mo > fr.po

The decompiled file will not include comments or fuzzy strings, as these are never compiled in the MO file in the first place.