Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Localização usando gettext (arquivos PO)

Além de importar traduções no formato CSV, o Godot também suporta arquivos de tradução no formato GNU gettext (arquivos textuais .po e compilados .mo).

Nota

Para obter uma introdução ao gettext, consulte A Quick Gettext Tutorial. Ele foi escrito com projetos em C em mente, mas muitos dos conselhos também se aplicam ao Godot (com exceção de xgettext).

Para a documentação completa, consulte GNU Gettext.

Vantagens

  • O gettext é um formato padrão, que pode ser editado com qualquer editor de texto ou ferramentas GUI como Poedit. Isso é relevante pois oferece diversas ferramentas para tradutores, como marcação de strings desatualizadas e identificação de strings não traduzidas.

  • gettext é suportado por plataformas de tradução como Transifex e Weblate, o que torna mais fácil para as pessoas colaborarem na localização.

  • Em comparação com CSV, arquivos gettext funcionam melhor com sistemas de controle de versão como Git, pois cada localidade possui seu próprio arquivo de mensagens.

  • Strings multilinha são mais convenientes de editar em arquivos PO do gettext do que em arquivos CSV.

Desvantagens

  • Arquivos PO do gettext têm um formato mais complexo que CSV e podem ser mais difíceis de entender para iniciantes em localização de software.

  • Pessoas que mantêm arquivos de localização terão que instalar ferramentas gettext em seus sistemas. No entanto, como o Godot não usa arquivos de objeto de mensagem compilados (.mo), os tradutores podem testar seu trabalho sem ter que instalar ferramentas gettext.

  • gettext PO files usually use English as the base language. Translators will use this base language to translate to other languages. You could still use other languages as the base language, but this is not common.

Instalando ferramentas gettext

As ferramentas gettext de linha de comando são necessárias para executar operações de manutenção, como atualizar arquivos de mensagens. Portanto, é altamente recomendável instalá-las.

  • Windows: Baixe um instalador a partir desta página. Qualquer arquitetura e tipo binário (compartilhado ou estático) funciona; em caso de dúvida, escolha o instalador estático de 64 bits.

  • macOS: Instale o gettext usando Homebrew com o comando brew install gettext, ou usando MacPorts com o comando sudo port install gettext.

  • Linux: Na maioria das distribuições, instale o pacote gettext do gerenciador de pacotes de sua distribuição.

Para uma ferramenta de interface gráfica (GUI), você pode obter o Poedit em seu site oficial. A versão básica é de código aberto e está disponível sob a licença MIT.

Criação do template PO

Geração automática usando o editor

O editor pode gerar um template PO automaticamente a partir de arquivos de cena e scripts GDScript especificados. Essa geração de POT também suporta contextos de tradução e pluralização se usados em um script, com o segundo argumento opcional de tr() e o método tr_n().

Abra Project > Project Settings > Localization > Template Generation, então use o botão Add… para especificar o caminho das cenas e scripts do seu projeto que contêm as strings localizáveis:

Criando um template PO na aba Localization > Template Generation das Configurações do Projeto

Criando um template PO na aba Localization > Template Generation das Project Settings

Após adicionar pelo menos uma cena ou script, clique em Generate no canto superior direito e especifique o caminho de saída com extensão .pot. Esse arquivo pode ser colocado em qualquer lugar do projeto, mas recomenda-se mantê-lo em uma subpasta como locale, já que cada localidade será definida em seu próprio arquivo.

Veja abaixo como adicionar comentários para os tradutores ou excluir algumas strings de serem adicionadas ao template PO em arquivos GDScript.

Você pode então prosseguir para a seção de criar um arquivo de mensagens a partir de um template PO.

Nota

Lembre-se de regenerar o template PO após fazer quaisquer alterações nas strings localizáveis, ou após adicionar novas cenas ou scripts. Caso contrário, as novas strings adicionadas não serão localizáveis e os tradutores não poderão atualizar as traduções de strings desatualizadas.

Criação manual

Se a geração automática não atender às necessidades, é possível criar um template PO manualmente em um editor de texto. Esse arquivo pode ser colocado em qualquer lugar do projeto, mas recomenda-se mantê-lo em uma subpasta, já que cada localidade será definida em seu próprio arquivo.

Crie um diretório chamado locale no projeto. Nesse diretório, salve um arquivo chamado messages.pot com o seguinte conteúdo:

# 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 ""

Mensagens em gettext são feitas de pares msgid e msgstr. msgid é a string fonte (geralmente em inglês), msgstr será a string traduzida.

Aviso

O valor msgstr em arquivos de modelo PO (.pot) deve sempre estar vazio. A localização será feita nos arquivos .po gerados.

Criando um arquivo de mensagens a partir de um modelo PO

O comando msginit é usado para transformar um modelo PO em um arquivo de mensagens. Por exemplo, para criar um arquivo de localização em francês, use o seguinte comando enquanto estiver no diretório locale:

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

O comando acima criará um arquivo chamado fr.po no mesmo diretório do modelo PO.

Alternativamente, você pode fazer isso graficamente usando o Poedit ou enviando o arquivo POT para a plataforma web de sua escolha.

Carregando um arquivo de mensagens no Godot

Para registrar um arquivo de mensagens como uma tradução em um projeto, abra as Project Settings (Configurações do Projeto), vá para Localization > Translations, clique em Add… e escolha o arquivo .po ou .mo na caixa de diálogo de arquivos. A localidade será inferida da propriedade "Language: <code>\n" no arquivo de mensagens.

Nota

Veja Internacionalizando jogos para mais informações sobre como importar e testar traduções no Godot.

Atualizando arquivos de mensagem para seguir o modelo PO

Após atualizar o modelo PO, você terá que atualizar os arquivos de mensagens para que contenham novas strings, enquanto remove as strings que não estão mais presentes no modelo PO. Isto pode ser feito automaticamente utilizando a ferramenta msgmerge:

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

Se você deseja manter um backup do arquivo da mensagem original (que seria salvo como fr.po~ neste exemplo), remova o argumento --backup=none.

Nota

Após executar o msgmerge, as strings que foram modificadas no idioma de origem receberão um comentário "fuzzy" antes delas no arquivo .po. Esse comentário indica que a tradução deve ser atualizada para corresponder à nova string de origem, pois a tradução provavelmente estará incorreta até que seja atualizada.

As strings com comentários "fuzzy" não serão lidas pelo Godot até que a tradução seja atualizada e o comentário "fuzzy" seja removido.

Verificando a validade de um arquivo ou modelo PO

É possível verificar se a sintaxe de um arquivo gettext é válida.

Se você abrir com o Poeditor, ele exibirá os avisos apropriados caso haja erros de sintaxe. Você também pode verificar executando o comando do gettext abaixo:

msgfmt fr.po --check

Se houver erros de sintaxe ou avisos, eles serão exibidos no console. Caso contrário, msgfmt não exibirá nada.

Usando arquivos MO binários (útil apenas para grandes projetos)

Para grandes projetos com vários milhares de strings para traduzir ou mais, pode valer a pena usar arquivos de mensagem MO binários (compilados) em vez de arquivos PO baseados em texto. Os arquivos MO binários são menores e mais rápidos de ler do que os arquivos PO equivalentes.

Você pode gerar um arquivo MO com o comando abaixo:

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

Se o arquivo PO for válido, este comando criará um arquivo fr.mo ao lado do arquivo PO. Esse arquivo MO pode então ser carregado no Godot conforme descrito acima.

O arquivo PO original deve ser mantido no controle de versão para que você possa atualizar sua tradução no futuro. Caso perca o arquivo PO original e deseje descompilar um arquivo MO em um arquivo PO baseado em texto, você pode fazer isso com:

msgunfmt fr.mo > fr.po

O arquivo descompilado não incluirá comentários ou strings fuzzy, pois estes nunca são compilados no arquivo MO em primeiro lugar.

Extração de strings localizáveis de arquivos GDScript

O plugin de editor nativo reconhece uma variedade de padrões no código-fonte para extrair strings localizáveis de arquivos GDScript, incluindo, mas não se limitando a:

  • chamadas a tr(), tr_n(), atr() e atr_n();

  • atribuição das propriedades text, placeholder_text e tooltip_text;

  • chamadas a add_tab(), add_item(), set_tab_title() e outras;

  • filtros de FileDialog como \"*.png ; PNG Images\".

Nota

O argumento ou operando da direita deve ser uma string constante, caso contrário, o plugin não será capaz de avaliar a expressão e a ignorará.

Se o plugin extrair strings desnecessárias, você pode ignorá-las com o comentário NO_TRANSLATE. Você também pode fornecer informações adicionais para os tradutores usando o comentário TRANSLATORS:. Esses comentários devem ser colocados na mesma linha do padrão reconhecido ou precedê-lo.

$CharacterName.text = "???" # NO_TRANSLATE

# NO_TRANSLATE: Language name.
$TabContainer.set_tab_title(0, "Python")

item.text = "Tool" # TRANSLATORS: Up to 10 characters.

# TRANSLATORS: This is a reference to Lewis Carroll's poem "Jabberwocky",
# make sure to keep this as it is important to the plot.
say(tr("He took his vorpal sword in hand. The end?"))

Uso de contexto

O parâmetro context pode ser usado para diferenciar a situação em que uma tradução é utilizada ou para diferenciar palavras polissêmicas (palavras com múltiplos significados).

Por exemplo:

tr("Start", "Main Menu")
tr("End", "Main Menu")
tr("Shop", "Main Menu")
tr("Shop", "In Game")

Em um arquivo PO do gettext, uma string com contexto pode ser definida da seguinte forma:

# Example of a string with a translation context.
msgctxt "Main Menu"
msgid "Shop"
msgstr ""

# A different source string that is identical, but with a different context.
msgctxt "In Game"
msgid "Shop"
msgstr ""

Atualização de arquivos PO

Some time or later, you'll add new content to your game, and there will be new strings that need to be translated. When this happens, you'll need to update the existing PO files to include the new strings.

Primeiro, gere un novo arquivo POT contendo todas as strings existentes mais as novas strings adicionadas. Depois disso, mescle os arquivos PO existentes com o novo arquivo POT. Existem duas maneiras de fazer isso:

  • Use um editor de gettext, e ele deve ter uma opção para atualizar um arquivo PO a partir de um arquivo POT.

  • Use a ferramenta msgmerge do gettext:

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

Se você deseja manter um backup do arquivo da mensagem original (que seria salvo como fr.po~ neste exemplo), remova o argumento --backup=none.

Geração de POT via plugin customizado

If you have any extra file format to deal with, you could write a custom plugin to parse and extract the strings from the custom file. This custom plugin will extract the strings and write into the POT file when you hit Generate POT. To learn more about how to create the translation parser plugin, see EditorTranslationParserPlugin.