La guida completa alla localizzazione di Unreal Engine
Dalle macro FText alle catene di fallback: localizzi il gioco UE5 con Localization Dashboard, String Table, C++, Blueprint e traduzione automatizzata.
FText e la pipeline di localizzazione
FText è il tipo di stringa di Unreal Engine che supporta la localizzazione. Ogni stringa del gioco rivolta agli utenti, come etichette dell'interfaccia, dialoghi, descrizioni comando e notifiche, deve usare FText per partecipare alla pipeline di localizzazione. FString è riservato alla logica interna.
// FText is UE's localization-aware string type.
// ALWAYS use FText for user-facing text, never FString.
// LOCTEXT: localize a literal string (most common)
FText Title = LOCTEXT("MainMenuTitle", "Start Game");
// NSLOCTEXT: specify namespace explicitly
FText Msg = NSLOCTEXT("UI", "WelcomeMessage", "Welcome, adventurer!");
// INVTEXT: invariant text (never translated — debug/logging only)
FText Debug = INVTEXT("Debug overlay active");
// FText::Format: safe variable interpolation
FText Greeting = FText::Format(
LOCTEXT("PlayerGreeting", "Hello, {PlayerName}!"),
FText::FromString(PlayerName)
);// In a UMG Widget (C++)
void UMainMenuWidget::NativeConstruct()
{
Super::NativeConstruct();
// Bind localized text to UI elements
if (TitleLabel)
{
TitleLabel->SetText(LOCTEXT("GameTitle", "My Epic Game"));
}
if (PlayButton)
{
PlayButton->SetText(LOCTEXT("PlayButtonLabel", "Play Now"));
}
}
// IMPORTANT: Always use LOCTEXT for UMG widget text.
// Setting text via FString bypasses the localization pipeline.Configurare Localization Dashboard
Localization Dashboard è lo strumento integrato di UE per gestire le traduzioni. Raccoglie dal codice sorgente tutte le stringhe LOCTEXT e NSLOCTEXT, le esporta come file .po da tradurre e compila i risultati in file binari .locres, caricati da UE durante l'esecuzione.
# 1. Open the Localization Dashboard:
# Window > Localization Dashboard
# 2. Add a localization target (e.g., "Game")
# 3. Add cultures:
# Click "Add New Culture" > select languages (de, ja, fr, es, ko, zh-Hans...)
# 4. Gather text:
# Click "Gather Text" — UE scans all LOCTEXT/NSLOCTEXT macros
# 5. Export translations:
# Click "Export" to generate .po files for each culture
# 6. Import translations:
# After translating .po files, click "Import"
# 7. Compile translations:
# Click "Compile" to generate .locres binary files
# 8. Preview:
# Editor Preferences > Region & Language > Preview Game LanguageUsare String Table per il testo basato sui dati
Le String Table consentono di definire le stringhe localizzate in una risorsa centralizzata anziché distribuire macro LOCTEXT tra i file sorgente. Sono ideali per il testo dell'interfaccia, i dialoghi e tutte le stringhe che designer o autori devono modificare senza intervenire sul codice. Le String Table possono essere definite come risorse UE o importate da CSV.
// StringTables provide a data-driven approach to localization.
// Define strings in a CSV asset instead of scattering LOCTEXT across code.
// 1. Create a String Table asset:
// Content Browser > Right-click > Miscellaneous > String Table
// 2. Or define via CSV (importable into UE):
// Key,SourceString
// MainMenu_Title,Start Game
// MainMenu_Continue,Continue
// MainMenu_Settings,Settings
// MainMenu_Quit,Quit to Desktop
// HUD_Health,Health
// HUD_Ammo,Ammo: {0}
// Dialog_Merchant_Greeting,Welcome to my shop!
// 3. Reference in C++:
FText Title = FText::FromStringTable(
FName(TEXT("/Game/Localization/ST_MainMenu")),
TEXT("MainMenu_Title")
);
// 4. Reference in Blueprints:
// Use the "Make Text from String Table" node
// Set Table ID and KeyPattern di localizzazione C++
In C++, definisca un LOCTEXT_NAMESPACE all'inizio di ogni file .cpp e usi LOCTEXT per tutte le stringhe rivolte agli utenti. Usi FText::Format per i contenuti dinamici con variabili. Annulli sempre la definizione dello spazio dei nomi alla fine del file per evitare propagazioni indesiderate.
// Define a namespace at the top of each .cpp file
// All LOCTEXT calls in this file use this namespace
#define LOCTEXT_NAMESPACE "MyGame.MainMenu"
#include "MainMenuWidget.h"
void UMainMenuWidget::NativeConstruct()
{
Super::NativeConstruct();
// These use the "MyGame.MainMenu" namespace automatically
TitleText->SetText(LOCTEXT("Title", "Main Menu"));
PlayText->SetText(LOCTEXT("PlayButton", "Play"));
SettingsText->SetText(LOCTEXT("SettingsButton", "Settings"));
QuitText->SetText(LOCTEXT("QuitButton", "Quit"));
}
// CRITICAL: Always undefine at the end of the file
#undef LOCTEXT_NAMESPACE// FText::Format — the safe way to build localized strings
// NEVER use FString::Printf or string concatenation for user-facing text.
// Named arguments (recommended)
FText ItemPickup = FText::Format(
LOCTEXT("ItemPickup", "You picked up {ItemName} x{Count}"),
FText::FromString(ItemName),
FText::AsNumber(Count)
);
// FText::AsNumber respects locale formatting:
// English: 1,234,567
// German: 1.234.567
// French: 1 234 567
// FText::AsCurrency for prices:
FText Price = FText::AsCurrency(
9.99,
TEXT("USD"),
&FInternationalization::Get().GetCurrentCulture().Get()
);
// FText::AsDate and FText::AsTime for dates:
FText DateStr = FText::AsDate(FDateTime::Now());Localizzazione dei Blueprint
Tutte le proprietà Text nei Blueprint sono FText per impostazione predefinita e sono quindi già pronte per la localizzazione. Imposti Key e Namespace nel pannello dei dettagli della proprietà per rendere le stringhe rilevabili. Usi il nodo Format Text per i contenuti dinamici con variabili.
// Blueprint Localization Basics:
//
// 1. All Text properties in Blueprints are FText by default
// (already localization-ready)
//
// 2. Set the Text property in the Details panel
// Expand the dropdown to set:
// - Key: unique identifier for translation
// - Namespace: grouping for organization
// - Source String: the text to display/translate
//
// 3. For dynamic text, use the "Format Text" node:
// Format: "Hello, {PlayerName}!"
// Connect a "Find" pin named "PlayerName" to your variable
//
// 4. For plurals, use "Text Format with Arguments":
// Pattern: "{Count}|plural(one=item,other=items)"
//
// 5. Culture switching at runtime:
// Use "Set Current Culture" node
// Input: culture code string (e.g., "de", "ja", "fr")Gestire plurali e genere
Unreal Engine supporta il formato dei messaggi ICU per plurali e testo che dipende dal genere. Definisca le regole del plurale nelle stringhe di origine e UE selezionerà automaticamente la forma corretta in base alle regole CLDR della cultura attiva.
// UE uses ICU message format for plurals.
// Define plural rules in your .po or String Table:
// English source:
// "{Count}|plural(one=You have # item,other=You have # items)"
// German translation:
// "{Count}|plural(one=Du hast # Gegenstand,other=Du hast # Gegenstaende)"
// Arabic translation (6 forms):
// "{Count}|plural(zero=لا عناصر,one=عنصر واحد,two=عنصران,few=# عناصر,many=# عنصرًا,other=# عنصر)"
// Japanese (1 form):
// "{Count}|plural(other=アイテム#個)"
// In C++:
FText ItemCount = FText::Format(
LOCTEXT("ItemCount",
"{Count}|plural(one=You have {Count} item,other=You have {Count} items)"),
ItemCount
);
// Gender-dependent text:
// "{Gender}|gender(masculine=Il est,feminine=Elle est) prêt{Gender}|gender(masculine=,feminine=e)"Creare il pacchetto e testare la localizzazione
Prima del rilascio, verifichi che tutte le culture di destinazione abbiano file .locres compilati e che il testo venga visualizzato correttamente durante l'esecuzione. Usi l'anteprima della cultura nell'Editor, le sostituzioni della cultura da riga di comando e i controlli automatici per rilevare traduzioni mancanti o non valide.
# Compile and test localization before packaging:
# 1. Editor Preferences > Region & Language > Preview Game Language
# Set to each target language and verify all text renders correctly.
# 2. Command-line culture override for testing:
MyGame.exe -culture=ja
# 3. Packaging settings:
# Project Settings > Packaging > Localizations to Package
# Select all cultures you want to include in the build.
# 4. Verify .locres files exist after packaging:
MyGame/Content/Localization/Game/
├── en/
│ └── Game.locres
├── de/
│ └── Game.locres
├── ja/
│ └── Game.locres
├── fr/
│ └── Game.locres
└── ko/
└── Game.locres
# 5. Runtime culture switching:
# FInternationalization::Get().SetCurrentCulture(TEXT("ja"));
# This reloads all FText strings from the new culture's .locres files.Aggiungere catene di fallback
La localizzazione predefinita di Unreal Engine applica il fallback soltanto lungo la gerarchia dei sottotag IETF. Se manca una traduzione, un utente pt-BR riceve l'inglese anziché una traduzione pt-PT perfettamente valida. locale-chain-ue aggiunge catene laterali configurabili tramite FTextLocalizationManager, affinché gli utenti regionali vedano sempre la traduzione disponibile più vicina.
// locale-chain-ue: Smart fallback chains for UE5
// Problem: UE falls back to default when a locale is missing.
// pt-BR user gets English instead of pt-PT translations.
// Solution: One function call at startup.
#include "LocaleChain.h"
void UMyGameInstance::Init()
{
Super::Init();
ULocaleChain::Configure(); // Load 75 built-in fallback chains
}
// Now resolve strings with per-key fallback:
FString Greeting = ULocaleChain::Resolve(
TEXT("greeting"), TEXT("MyNamespace")
);
// pt-BR user: tries pt-BR -> pt-PT -> pt -> default
// Custom overrides:
TMap<FString, FString> Overrides;
Overrides.Add(TEXT("pt-BR"), TEXT("pt")); // Simplify chain
Overrides.Add(TEXT("sv-FI"), TEXT("sv")); // Add new chain
ULocaleChain::ConfigureWithOverrides(Overrides);
// Full control (C++ only):
TMap<FString, TArray<FString>> Custom;
Custom.Add(TEXT("pt-BR"), {TEXT("pt-PT"), TEXT("pt")});
Custom.Add(TEXT("es-MX"), {TEXT("es-419"), TEXT("es")});
ULocaleChain::ConfigureCustom(Custom, false);Automatizzare la qualità
Problemi comuni
Uso di FString per il testo rivolto agli utenti
#undef LOCTEXT_NAMESPACE mancante
Logica plurale codificata direttamente
Mancata compilazione dopo l'importazione
Struttura del progetto consigliata
MyUnrealProject/
├── Config/
│ └── Localization/
│ └── Game.ini # Localization target config
├── Content/
│ └── Localization/
│ ├── Game/
│ │ ├── Game.manifest # Gather manifest
│ │ ├── en/
│ │ │ ├── Game.po # Source strings (.po)
│ │ │ └── Game.locres # Compiled binary
│ │ ├── de/
│ │ │ ├── Game.po
│ │ │ └── Game.locres
│ │ ├── ja/
│ │ │ ├── Game.po
│ │ │ └── Game.locres
│ │ └── fr/
│ │ ├── Game.po
│ │ └── Game.locres
│ └── StringTables/
│ ├── ST_MainMenu.uasset # String Table asset
│ └── ST_HUD.uasset
├── Plugins/
│ └── LocaleChain/ # locale-chain-ue plugin
│ ├── LocaleChain.uplugin
│ └── Source/
│ └── LocaleChain/
├── Source/
│ └── MyGame/
│ ├── UI/
│ │ ├── MainMenuWidget.h
│ │ └── MainMenuWidget.cpp # LOCTEXT macros here
│ └── MyGameInstance.cpp # ULocaleChain::Configure()
└── MyUnrealProject.uprojectProvi subito i18n Agent
Trascinare qui il file di traduzione
JSON, YAML, PO, XML, CSV, Markdown, Properties
oppure fare clic per selezionarlo
Lingue di destinazione