
Guia completa per localitzar jocs amb Godot
Des de TranslationServer fins a les fonts alternatives: localitzi el seu joc de Godot amb fitxers CSV i PO, GDScript i traducció automatitzada amb IA.
Fonaments de TranslationServer
El TranslationServer integrat de Godot és el nucli del sistema de localització. Carrega els recursos de traducció en iniciar-se i resol les claus mitjançant la funció tr(). Totes les crides de GDScript a tr() passen per TranslationServer, sense necessitat de biblioteques addicionals.
# 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)Fitxers de traducció CSV
CSV és el format més senzill per a les traduccions de Godot. Un sol fitxer conté tots els idiomes en columnes. La primera columna és la clau i cadascuna de les columnes següents és una configuració regional. Godot importa automàticament els fitxers .csv i genera recursos .translation.
# 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!"# 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 filesFitxers de traducció PO / Gettext
Els fitxers PO (Portable Object) són l’estàndard del sector per localitzar programari. Godot 4.x admet PO de manera nativa, amb plurals, desambiguació contextual i comentaris per als traductors. Creï un fitxer .po per idioma dins d’un directori locale/.
# 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枚のコインを集めました。"# 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)Ús de les traduccions en GDScript
Utilitzi tr() en qualsevol punt de GDScript per traduir cadenes. Combini-la amb l’operador % de GDScript per formatar cadenes. Per gestionar les configuracions regionals de manera robusta, creï un script Autoload que s’encarregui de detectar-les, conservar-les i canviar-les mitjançant senyals.
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 — 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()Plurals i marcadors de posició
Godot gestiona els plurals mitjançant les formes plurals dels fitxers PO. Cada idioma defineix la seva pròpia fórmula de plural a la capçalera PO. L’operador % de GDScript gestiona els marcadors de posició posicionals (%s per a cadenes i %d per a enters). Per als marcadors de posició amb nom, utilitzi String.replace().
# 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 монет."# 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))Fonts alternatives per a CJK, àrab i altres sistemes d’escriptura
És probable que la font principal del seu joc no inclogui glifs per als sistemes d’escriptura japonès, coreà, xinès, àrab o tailandès. Godot 4.x admet cadenes de fonts alternatives: quan falta un glif a la font principal, Godot comprova les fonts alternatives en ordre. Sense aquesta configuració, el text no llatí es renderitza com a quadrats buits.
# 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)# 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_RTLLocalització d’escenes i de la interfície
Hi ha tres maneres de localitzar escenes de Godot: traduir-les a _ready() mitjançant tr(), utilitzar la propietat Traducció automàtica de l’editor o carregar escenes completament diferents per als idiomes que necessiten disposicions diferents, com els idiomes RTL.
# 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())Alternatives intel·ligents de configuració regional amb LocaleChain
TranslationServer de Godot recorre directament a la configuració regional predeterminada del projecte quan falta una variant regional. Un jugador amb pt-BR que només disposi de traduccions pt-PT veurà el text en anglès en lloc de portuguès. LocaleChain ho resol combinant traduccions de cadenes de reserva configurables dins de TranslationServer durant la configuració.
# 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()Automatització de les traduccions de jocs
Un cop completada la configuració de localització, tradueixi els fitxers CSV o PO mitjançant IA. Automatitzi la traducció de les cadenes del joc, el text de la interfície, les descripcions d’objectes i els diàlegs directament des de l’IDE o la cadena de CI/CD.
# 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 headersAutomatització de la qualitat de la traducció
Errors habituals
Els fitxers de traducció no s’han importat
Les comes o cometes dels valors CSV trenquen l’anàlisi
El text CJK o àrab es mostra com a quadrats buits
Nombre incorrecte de formes plurals a la capçalera PO
El codi substitueix la traducció automàtica
Estructura de projecte recomanada
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.cfgTraduir també:
Provar i18n Agent ara
Arrossegar aquí el fitxer de traducció
JSON, YAML, PO, XML, CSV, Markdown, Properties
o fer clic per explorar
Idiomes de destinació
configuracions regionals de reserva amb locale-chain-godot
Quan falta una clau de traducció en una configuració regional com pl_PL, Godot salta directament a la configuració regional predeterminada del projecte en lloc de comprovar primer la configuració regional superior pl.
# Instal·lació des de la biblioteca de recursos de Godot
# Cerca: locale-chain-godotvar lc = LocaleChain.new()
lc.configure({
"pl": ["pl_PL", "en"],
"pt_BR": ["pt", "en"],
"zh_Hant_HK": ["zh_Hant", "zh", "en"],
})Consulti la nostra guia de configuracions regionals de reserva per veure la llista completa de frameworks compatibles i les 75 cadenes integrades. Learn more →