Como funciona a localização no Godot Engine?

O Godot utiliza TranslationServer, um sistema integrado que carrega ficheiros CSV ou PO e resolve chaves através de tr(). Adicione os ficheiros em Project Settings, defina a região com TranslationServer.set_locale() e chame tr('KEY') em qualquer parte de GDScript. Não precisa de bibliotecas externas.

Devo utilizar CSV ou PO nas traduções do Godot?

CSV é mais simples: todos os idiomas num ficheiro, fácil de editar em folhas de cálculo. Utilize-o em projetos pequenos ou médios com cadeias simples. PO aceita plurais, desambiguação e comentários; utilize-o em projetos grandes ou jogos que precisem de pluralização. Pode combinar ambos.

Como trato a pluralização no Godot?

Utilize ficheiros PO com msgid_plural e várias entradas msgstr. Cada idioma define a fórmula no cabeçalho Plural-Forms. O Godot seleciona automaticamente a forma correta com base no número. CSV não aceita plurais, uma das principais razões para utilizar PO.

Como apresento caracteres CJK no Godot?

Adicione fontes de recurso em Theme ou LabelSettings. É provável que a fonte principal não contenha glifos japoneses, coreanos ou chineses. Adicione Noto Sans JP, KR e SC. Quando falta um glifo, o Godot verifica as fontes de recurso por ordem.

O Godot aceita idiomas da direita para a esquerda (RTL)?

Sim. Godot 4.x inclui compatibilidade BiDi —bidirecional—. Defina text_direction como RTL em Label e RichTextLabel. Para espelhar toda a interface, defina layout_direction como RTL nos contentores. Teste conteúdo LTR/RTL misto para garantir a ordem correta.

Posso automatizar as traduções de jogos Godot?

Sim. Depois de concluir a localização, ferramentas como o i18n Agent traduzem os ficheiros CSV ou PO diretamente no IDE. Mantém o ficheiro de origem e a ferramenta gera os restantes idiomas, preservando a estrutura das colunas CSV, as formas plurais PO e os marcadores.

O que é LocaleChain para Godot?

LocaleChain é um plugin Godot de código aberto que acrescenta cadeias inteligentes. Por predefinição, o Godot recorre à região do projeto quando falta uma variante. LocaleChain permite que pt-BR recorra a pt-PT antes de inglês, es-MX a es-419 antes de espanhol, etc. Configuração numa linha, sem alterar as chamadas tr().

O guia completo da localização de jogos no Godot

Name: i18n Agent
Price: 0.01 EUR
Author: i18n Agent

De TranslationServer às fontes de recurso: localize o seu jogo Godot com CSV, ficheiros PO, GDScript e tradução automatizada com IA.

Princípios de TranslationServer

TranslationServer integrado no Godot é o núcleo do sistema. Carrega recursos no arranque e resolve chaves através de tr(). Todas as chamadas GDScript passam por TranslationServer, sem bibliotecas adicionais.

TranslationServer basics

# TranslationServer is Godot's built-in localization system.
# It loads translations at startup and resolves keys via tr().

# Set the game's locale
TranslationServer.set_locale("ja")

# Get the current locale
var current = TranslationServer.get_locale()  # "ja"

# Translate a key — works everywhere in GDScript
var text = tr("MENU_START")  # "ゲームスタート"

# Translate with context (Godot 4.x)
var text = tr("OPEN", "verb")    # "Open" (action)
var text = tr("OPEN", "adj")     # "Open" (state)

TranslationServer aceita CSV, PO —Gettext— e .translation —binário—. Deteta automaticamente a região do sistema através de OS.get_locale() e seleciona o recurso correspondente. Pode alterá-la a qualquer momento com TranslationServer.set_locale().

Ficheiros de tradução CSV

CSV é o formato mais simples no Godot. Um ficheiro contém todos os idiomas em colunas. A primeira é a chave e as restantes são regiões. O Godot importa automaticamente .csv e gera recursos .translation.

translations.csv

# translations.csv
# First column = key, subsequent columns = locale codes
keys,en,ja,de,es
MENU_START,Start Game,ゲームスタート,Spiel starten,Iniciar juego
MENU_SETTINGS,Settings,設定,Einstellungen,Configuración
MENU_QUIT,Quit,終了,Beenden,Salir
ITEM_SWORD,Sword,剣,Schwert,Espada
ITEM_SHIELD,Shield,盾,Schild,Escudo
DIALOG_GREETING,"Hello, adventurer!",冒険者よ、こんにちは！,"Hallo, Abenteurer!","¡Hola, aventurero!"

Importing CSV translations

# In Godot Editor:
# 1. Place your .csv file in the project (e.g., res://translations.csv)
# 2. Godot auto-imports it — creates .translation resources
# 3. Go to Project > Project Settings > Localization > Translations
# 4. Add the generated .translation files

Coloque entre aspas duplas os valores com vírgulas ou quebras de linha. Nos que contêm aspas duplas, escape-as como "". Mantenha chaves curtas e descritivas: MENU_START é melhor do que menu_start_button_text_label.

Ficheiros de tradução PO / Gettext

PO (Portable Object) é a norma do setor na localização de software. Godot 4.x aceita nativamente PO com plurais, desambiguação e comentários. Crie um ficheiro .po por idioma num diretório locale/.

locale/ja.po

# translations.po — Gettext format for Godot
# Place in res://locale/ja.po

msgid ""
msgstr ""
"Language: ja\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Plural-Forms: nplurals=1; plural=0;\n"

# Simple translation
msgid "MENU_START"
msgstr "ゲームスタート"

# Translation with context (disambiguates identical source strings)
msgctxt "verb"
msgid "OPEN"
msgstr "開く"

msgctxt "adj"
msgid "OPEN"
msgstr "開いている"

# Plural form
msgid "You collected %d coin."
msgid_plural "You collected %d coins."
msgstr[0] "%d枚のコインを集めました。"

Loading PO files

# Project Settings > Localization > Translations
# Add each .po file:
#   res://locale/en.po
#   res://locale/ja.po
#   res://locale/de.po
#   res://locale/es.po

# Or load programmatically:
func _ready():
    var translation = load("res://locale/ja.po")
    TranslationServer.add_translation(translation)

Os PO aceitam msgctxt para desambiguação —por exemplo, 'OPEN' como verbo ou adjetivo—, msgid_plural para formas plurais e comentários dos tradutores —linhas #.— que explicam onde e como as cadeias são utilizadas.

Utilizar traduções em GDScript

Utilize tr() em qualquer parte de GDScript. Combine-o com o operador % para formatar cadeias. Para uma gestão robusta, crie um script Autoload que trate da deteção, persistência e seleção através de sinais.

Using tr() in scenes

extends Control

func _ready():
    # Simple key lookup
    $TitleLabel.text = tr("MENU_START")

    # With string formatting (positional)
    $GreetingLabel.text = tr("DIALOG_GREETING_NAME") % [player_name]

    # With multiple placeholders
    $StatusLabel.text = tr("PLAYER_STATUS") % [player_name, level, health]

    # Context-aware translation (Godot 4.x)
    $ActionButton.text = tr("OPEN", "verb")

    # Update UI when locale changes
    TranslationServer.set_locale("de")
    _update_ui()

func _update_ui():
    # Re-apply all translated strings
    $TitleLabel.text = tr("MENU_START")
    $GreetingLabel.text = tr("DIALOG_GREETING_NAME") % [player_name]

locale_manager.gd (Autoload)

# locale_manager.gd — Register as Autoload in Project Settings
extends Node

signal locale_changed(new_locale: String)

const SUPPORTED_LOCALES = ["en", "ja", "de", "es", "fr", "ko", "zh"]

func _ready():
    var system_locale = OS.get_locale_language()
    if system_locale in SUPPORTED_LOCALES:
        set_locale(system_locale)
    else:
        set_locale("en")

func set_locale(locale: String):
    TranslationServer.set_locale(locale)
    locale_changed.emit(locale)

func get_locale() -> String:
    return TranslationServer.get_locale()

Alterar a região com TranslationServer.set_locale() não atualiza automaticamente o texto já apresentado nas cenas. Tem de voltar a aplicar tr() a todas as etiquetas, botões e nós de texto visíveis. Utilize sinais do gestor regional para notificar as cenas.

Plurais e marcadores

Godot trata plurais pelas formas dos ficheiros PO. Cada idioma define a fórmula no cabeçalho. O operador % de GDScript trata marcadores posicionais —%s para cadeias e %d para inteiros—. Nos marcadores com nome, utilize String.replace().

Plural forms by language

# Godot uses Gettext PO plural rules.
# Each language defines its own plural formula.

# English (2 forms: one, other)
msgid "You collected %d coin."
msgid_plural "You collected %d coins."
msgstr[0] "You collected %d coin."
msgstr[1] "You collected %d coins."

# Japanese (1 form: other — no singular/plural distinction)
msgid "You collected %d coin."
msgid_plural "You collected %d coins."
msgstr[0] "%d枚のコインを集めました。"

# Russian (3 forms: one, few, many)
msgid "You collected %d coin."
msgid_plural "You collected %d coins."
msgstr[0] "Вы собрали %d монету."
msgstr[1] "Вы собрали %d монеты."
msgstr[2] "Вы собрали %d монет."

Placeholder formatting

# GDScript string formatting with tr()

# Positional placeholders with %
var msg = tr("SCORE_MSG") % [score]        # "Score: %d" → "Score: 1500"
var msg = tr("STATS") % [name, level, hp]  # "%s — Lv %d — HP: %d"

# Named placeholders (manual replacement)
var template = tr("WELCOME_BACK")
var msg = template.replace("{player}", name).replace("{days}", str(days))

Nunca codifique diretamente lógica como 'if count == 1'. As regras variam muito: o inglês tem 2 formas, o russo 3, o árabe 6 e o japonês 1. Deixe o sistema PO selecionar automaticamente. CSV não aceita plurais; utilize PO em conteúdo que precise deles.

Fontes de recurso para CJK, árabe e outros

É provável que a fonte principal do jogo não contenha glifos japoneses, coreanos, chineses, árabes ou tailandeses. Godot 4.x aceita cadeias de fontes de recurso: se faltar um glifo, verifica outras fontes por ordem. Sem elas, o texto não latino aparece como quadrados vazios.

Font fallback setup

# Godot 4.x supports font fallback chains.
# When a glyph is missing from the primary font, fallbacks are checked in order.

# In the Editor:
# 1. Create a LabelSettings or Theme resource
# 2. Set the primary font (e.g., Noto Sans for Latin)
# 3. Add fallback fonts: Noto Sans JP, KR, SC, Arabic

# Programmatically:
func setup_fonts():
    var font = FontFile.new()
    font.load_dynamic_font("res://fonts/NotoSans-Regular.ttf")

    var fallback_jp = FontFile.new()
    fallback_jp.load_dynamic_font("res://fonts/NotoSansJP-Regular.ttf")
    font.add_fallback(fallback_jp)

    $Label.add_theme_font_override("font", font)

RTL support

# Right-to-left (RTL) support for Arabic, Hebrew, etc.

# In the Editor:
# Select your Control node > Layout > Text Direction = RTL

# Programmatically:
func setup_rtl():
    var locale = TranslationServer.get_locale()
    var rtl_locales = ["ar", "he", "fa", "ur"]

    if locale.substr(0, 2) in rtl_locales:
        $Label.text_direction = Control.TEXT_DIRECTION_RTL
        $Container.layout_direction = Control.LAYOUT_DIRECTION_RTL

Utilize a família Noto da Google, que abrange quase todas as escritas Unicode. Adicione Noto Sans JP, KR, SC e Arabic como recursos. Em jogos de píxeis, considere Noto Sans Mono ou fontes bitmap com subconjuntos CJK. Tenha em conta o tamanho total: fontes CJK completas podem ocupar 15 a 20 MB cada.

Localização de cenas e interface

Há três abordagens para localizar cenas do Godot: traduzir em _ready() através de tr(), utilizar a propriedade Auto Translate no editor ou carregar cenas totalmente diferentes nos idiomas que precisam de outras disposições —como RTL—.

Scene localization approaches

# Approach 1: Translate in _ready() using tr()
extends Control

func _ready():
    $StartButton.text = tr("MENU_START")
    $SettingsButton.text = tr("MENU_SETTINGS")
    $QuitButton.text = tr("MENU_QUIT")

# Approach 2: Use auto-translate in the editor
# Set the Text property to the translation key (e.g., "MENU_START")
# and enable "Auto Translate" on the node.

# Approach 3: Locale-specific scenes for complex layouts
func load_localized_scene():
    var locale = TranslationServer.get_locale().substr(0, 2)
    var path = "res://ui/main_menu_%s.tscn" % locale
    if ResourceLoader.exists(path):
        add_child(load(path).instantiate())
    else:
        add_child(load("res://ui/main_menu_en.tscn").instantiate())

Auto Translate só funciona na propriedade text do nó. Se definir text dinamicamente no código após _ready(), a tradução automática é substituída. Em texto dinâmico, utilize sempre tr() explicitamente. Note também que a tradução automática aplica tr() ao valor literal, pelo que text tem de conter a chave e não a cadeia legível de origem.

Recurso regional inteligente com LocaleChain

TranslationServer do Godot recorre diretamente à região predefinida quando falta uma variante. Um jogador pt-BR com apenas pt-PT vê inglês em vez de português. LocaleChain corrige isto ao combinar traduções de cadeias configuráveis em TranslationServer durante configure.

LocaleChain plugin

# LocaleChain for Godot — smart locale fallback
# Install from Godot AssetLib or copy addons/locale_chain/ into your project

# Problem: Godot's TranslationServer falls back directly to the default locale.
# A pt-BR player with only pt-PT translations sees English, not Portuguese.

# Solution: One-line setup
func _ready():
    LocaleChain.configure()  # Uses built-in fallback chains

# Now pt-BR falls back to pt-PT → pt → default
# es-MX falls back to es-419 → es → default
# zh-Hant-HK falls back to zh-Hant-TW → zh-Hant → default

# Custom configuration:
func _ready():
    # Override specific chains
    LocaleChain.configure({"pt-BR": ["pt"]})

    # Full custom — only your chains
    LocaleChain.configure(
        {"pt-BR": ["pt-PT", "pt"], "es-MX": ["es-419", "es"]},
        false  # don't merge defaults
    )

    # Reset to original state
    LocaleChain.reset()

LocaleChain é um suplemento GDScript puro, sem extensões nativas nem alterações do motor. Instale-o através de Godot AssetLib ou copie addons/locale_chain/ para o projeto. Funciona com CSV, PO e .translation.

Automatizar traduções de jogos

Depois de concluir a localização, traduza os ficheiros CSV ou PO com IA. Automatize as cadeias do jogo, texto da interface, descrições de objetos e diálogos diretamente no IDE ou pipeline de CI/CD.

Terminal

# Translate your Godot locale files with AI
# CSV files:
# In your IDE, ask your AI assistant:
> Translate translations.csv to Japanese, Korean, and German

# PO files:
> Translate locale/en.po to ja, ko, de

# Or use the CLI in CI/CD:
npx i18n-agent translate locale/en.po --lang ja,ko,de

# The tool preserves:
# - CSV column structure and delimiters
# - PO msgctxt, msgid_plural, and plural forms
# - Placeholder syntax (%s, %d, {name})
# - Comments and metadata headers

Traduza de forma incremental. Quando adicionar chaves ao ficheiro de origem, traduza apenas as diferenças em vez de gerar tudo novamente. Assim preserva traduções revistas por pessoas em diálogos narrativos ou conteúdo culturalmente sensível.

Automatizar a qualidade das traduções

Detete chaves em falta e marcadores danificados antes da publicação com i18n-validate. Teste a interface com pseudotraduções através de i18n-pseudo antes de chegarem as traduções reais.

Erros frequentes

Os ficheiros de tradução não foram importados

O Godot tem de importar .csv e .po antes de os utilizar. Se as traduções não aparecerem, confirme se os ficheiros constam de Project Settings > Localization > Translations. Em CSV, verifique se foram gerados .translation em .godot/imported/.

Valores CSV com vírgulas ou aspas quebram a análise

Os valores com vírgulas têm de ficar entre aspas duplas. Os que contêm aspas duplas devem escapá-las como "". Uma aspa em falta faz toda a linha ser analisada incorretamente e desloca silenciosamente as colunas seguintes.

O texto CJK ou árabe mostra quadrados vazios

A fonte principal não contém glifos para estas escritas. Adicione fontes de recurso em Theme ou LabelSettings. Sem elas, os glifos em falta aparecem como retângulos vazios. Utilize variantes Noto Sans para uma cobertura Unicode abrangente.

Número incorreto de formas plurais no cabeçalho PO

Se nplurals no cabeçalho não corresponder ao número real de entradas msgstr, o Godot pode falhar ou mostrar a forma errada. Confirme sempre se Plural-Forms corresponde à especificação CLDR de cada idioma.

Auto Translate substituído pelo código

Definir a propriedade text de um nó em GDScript após _ready() substitui o resultado automático. Utilize exclusivamente Auto Translate —defina o texto no editor, nunca no código— ou tr() no código. Misturá-los provoca comportamentos inconsistentes.

Estrutura de projeto recomendada

Project Structure

my_godot_game/
├── addons/
│   └── locale_chain/              # LocaleChain plugin (optional)
│       ├── fallback_map.gd
│       ├── locale_chain.gd
│       └── plugin.cfg
├── fonts/
│   ├── NotoSans-Regular.ttf       # Primary font (Latin)
│   ├── NotoSansJP-Regular.ttf     # Japanese fallback
│   ├── NotoSansKR-Regular.ttf     # Korean fallback
│   └── NotoSansArabic-Regular.ttf # Arabic fallback
├── locale/
│   ├── en.po                      # English (source)
│   ├── ja.po                      # Japanese
│   ├── de.po                      # German
│   ├── es.po                      # Spanish
│   └── ar.po                      # Arabic
├── translations.csv               # Alternative: CSV format
├── scenes/
│   └── ui/
│       ├── main_menu.tscn
│       └── settings_menu.tscn
├── scripts/
│   ├── locale_manager.gd          # Autoload for locale management
│   └── ui/
│       └── main_menu.gd
├── project.godot
└── export_presets.cfg

Também pode traduzir:

Experimente já o i18n Agent

Largue aqui o seu ficheiro de tradução

JSON, YAML, PO, XML, CSV, Markdown, Properties

ou clique para selecionar

Idiomas de destino

Sem registoEstimativa imediata

Recurso regional com locale-chain-godot

Quando falta uma chave numa região como pl_PL, o Godot passa diretamente para a região predefinida do projeto em vez de verificar primeiro a principal pl.