Skip to main content

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.

1

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 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 admet els formats CSV, PO (Gettext) i .translation (binari). Detecta automàticament la configuració regional del sistema mitjançant OS.get_locale() i selecciona el recurs de traducció corresponent. Pot substituir la configuració regional en qualsevol moment amb TranslationServer.set_locale().
2

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
# 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
Posi entre cometes dobles els valors que continguin comes o salts de línia. Als valors que continguin cometes dobles, escapi-les com a "". Faci servir claus curtes i descriptives: MENU_START és millor que menu_start_button_text_label.
3

Fitxers 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/.

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)
Els fitxers PO admeten msgctxt per a la desambiguació contextual (per exemple, 'OPEN' com a verb o com a adjectiu), msgid_plural per a les formes plurals i comentaris per als traductors (línies #.) que expliquen on i com s’utilitzen les cadenes.
4

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

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()
Canviar la configuració regional amb TranslationServer.set_locale() no actualitza automàticament el text que ja s’ha renderitzat a les escenes. Després de canviar-la, ha de tornar a aplicar manualment tr() a totes les etiquetes, els botons i els nodes de text visibles. Utilitzi senyals del gestor de configuracions regionals per avisar les escenes de la interfície que s’han d’actualitzar.
5

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

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))
No codifiqui mai de manera fixa una lògica de plural com 'if count == 1'. Les regles de plural varien enormement entre idiomes: l’anglès té 2 formes, el rus en té 3, l’àrab en té 6 i el japonès en té 1. Deixi que el sistema de plurals de PO gestioni automàticament la selecció. Els fitxers CSV no admeten plurals: utilitzi fitxers PO per a qualsevol contingut que necessiti formes plurals.
6

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.

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
Utilitzi la família tipogràfica Noto de Google, que cobreix gairebé tots els sistemes d’escriptura Unicode. Afegeixi Noto Sans JP, Noto Sans KR, Noto Sans SC i Noto Sans Arabic com a fonts alternatives. Per als jocs d’art píxel, consideri Noto Sans Mono o fonts de mapa de bits que incloguin subconjunts CJK. Tingui present la mida total de les fonts: les fonts CJK completes poden ocupar entre 15 i 20 MB cadascuna.
7

Localització 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.

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())
La traducció automàtica només funciona amb la propietat text del node. Si defineixi text dinàmicament al codi després de _ready(), se substitueix el resultat de la traducció automàtica. Per al text que s’actualitza dinàmicament, utilitzi sempre tr() explícitament al codi. Tingui en compte també que la traducció automàtica aplica tr() al valor de text literal; per tant, la propietat text ha de contenir la clau de traducció, no pas la cadena d’origen llegible.
8

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 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 és un complement escrit íntegrament en GDScript, sense extensions natives ni modificacions del motor. Instal·li'l des de l’AssetLib de Godot o copiï la carpeta addons/locale_chain/ al seu projecte. Funciona amb fitxers CSV, PO i .translation.
9

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.

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
Tradueixi de manera incremental. Quan afegeixi claus noves al fitxer d’origen, tradueixi només les diferències en lloc de tornar-ho a generar tot. Així es conserven les traduccions revisades per persones dels diàlegs narratius o del contingut culturalment sensible.

Automatització de la qualitat de la traducció

Detecti les claus que falten i els marcadors de posició malmesos abans de publicar amb i18n-validate. Provi la interfície amb pseudotraduccions mitjançant i18n-pseudo abans que arribin les traduccions reals.

Errors habituals

Els fitxers de traducció no s’han importat

Godot ha d’importar els fitxers .csv i .po abans que es puguin utilitzar. Si les traduccions no apareixen, comprovi que els fitxers constin a Configuració del projecte > Localització > Traduccions. Per als CSV, asseguri's que Godot hagi generat fitxers .translation al directori .godot/imported/.

Les comes o cometes dels valors CSV trenquen l’anàlisi

Els valors que continguin comes han d’anar entre cometes dobles. Els valors que continguin cometes dobles han d’escapar-les com a "". Si falta una cometa, tota la fila s’analitza incorrectament i sovint totes les columnes següents es desplacen sense cap avís.

El text CJK o àrab es mostra com a quadrats buits

La font principal no inclou glifs per a aquests sistemes d’escriptura. Afegeixi fonts alternatives al recurs Theme o LabelSettings. Sense fonts alternatives, els glifs que falten es renderitzen com a rectangles buits. Utilitzi variants de Noto Sans per obtenir una cobertura Unicode àmplia.

Nombre incorrecte de formes plurals a la capçalera PO

Si el valor nplurals de la capçalera PO no coincideix amb el nombre real d’entrades msgstr, Godot pot fallar o mostrar una forma plural incorrecta. Comprovi sempre que la capçalera Plural-Forms coincideixi amb l’especificació CLDR de cada idioma de destinació.

El codi substitueix la traducció automàtica

Definir la propietat text d’un node en GDScript després de _ready() substitueix el resultat de la traducció automàtica. Utilitzi exclusivament la traducció automàtica (defineixi text a l’editor i mai al codi) o bé utilitzi exclusivament tr() al codi. Barrejar totes dues opcions genera un comportament incoherent.

Estructura de projecte recomanada

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

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ó

No cal registrePressupost instantani

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.

Terminal
# Instal·lació des de la biblioteca de recursos de Godot
# Cerca: locale-chain-godot
Configuration
var 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 →

Preguntes freqüents sobre la localització amb Godot