Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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 4.0).

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.

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.

Creating the PO template

Automatic generation using the editor

Since Godot 4.0, the editor can generate a PO template automatically from specified scene and GDScript files. This POT generation also supports translation contexts and pluralization if used in a script, with the optional second argument of tr() and the tr_n() method.

Open the Project Settings' Localization > POT Generation tab, then use the Add… button to specify the path to your project's scenes and scripts that contain localizable strings:

Creating a PO template in the Localization > POT Generation tab of the Project Settings

Creating a PO template in the Localization > POT Generation tab of the Project Settings

After adding at least one scene or script, click Generate POT in the top-right corner, then specify the path to the output file. This file can be placed anywhere in the project directory, but it's recommended to keep it in a subdirectory such as locale, as each locale will be defined in its own file.

You can then move over to creating a messages file from a PO template.

Nota

Remember to regenerate the PO template after making any changes to localizable strings, or after adding new scenes or scripts. Otherwise, newly added strings will not be localizable and translators won't be able to update translations for outdated strings.

Manual creation

If the automatic generation approach doesn't work out for your needs, you can create a PO template by hand in a text editor. This file can be placed anywhere in the project directory, but it's recommended to keep it in a subdirectory, as each locale will be defined in its own file.

Create a directory named locale in the project directory. In this directory, save a file named messages.pot with the following contents:

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

# Example of a regular string.
msgid "Hello world!"
msgstr ""

# Example of a string with pluralization.
msgid "There is %d apple."
msgid_plural "There are %d apples."
msgstr[0] ""
msgstr[1] ""

# Example of a string with a translation context.
msgctxt "Actions"
msgid "Close"
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.

Advertencia

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.

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

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 above.

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.