Skip to main content

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.

1

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.

LOCTEXT richiede due argomenti: una chiave e una stringa di origine. La chiave deve essere univoca nel relativo spazio dei nomi. Il programma di raccolta del testo di UE usa queste chiavi per tenere traccia delle traduzioni tra culture. NSLOCTEXT consente di specificare esplicitamente lo spazio dei nomi; LOCTEXT usa quello definito dalla macro LOCTEXT_NAMESPACE che lo racchiude.
FText Basics
// 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)
);
MainMenuWidget.cpp
// 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.
Non costruisca mai testo rivolto agli utenti con FString::Printf o mediante concatenazione di stringhe. Questi metodi ignorano completamente la pipeline di localizzazione: il testo risultante non può essere raccolto, tradotto o visualizzato correttamente nelle lingue RTL. Usi sempre FText::Format con pattern LOCTEXT.
2

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.

Localization Dashboard Workflow
# 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 Language
Esegua 'Gather Text' dopo ogni modifica al codice che aggiunge o cambia macro LOCTEXT. Se omette questo passaggio, le nuove stringhe non appariranno nei file .po e i traduttori non le vedranno. Aggiunga un passaggio di raccolta all'automazione della compilazione per rilevarle automaticamente.
3

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

StringTableUsage.cpp
// 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 Key
Le String Table vengono raccolte automaticamente da Localization Dashboard. Non servono macro LOCTEXT per le stringhe definite in una String Table: basta richiamarle tramite ID della tabella e chiave in C++ o Blueprint.
4

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

MainMenuWidget.cpp
// 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 Examples
// 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());
Anche gli argomenti di FText::Format devono essere FText, non FString non elaborati. Usi FText::FromString() per convertire valori FString, FText::AsNumber() per formattare i numeri in base alla cultura e FText::AsCurrency() per i prezzi. La concatenazione di FString non elaborati produce testo che non rispetta le regole di formattazione della lingua.
5

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 Patterns
// 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")
Espanda il menu della proprietà text nel pannello Blueprint Details per vedere i campi Key, Namespace e Source String. Una Key significativa facilita notevolmente l'identificazione delle stringhe nel file .po da parte dei traduttori.
6

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.

ICU Plural & Gender Rules
// 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)"
Non codifichi mai direttamente count == 1 per rilevare il singolare. Il francese considera 0 singolare. Il russo ha forme separate per 'few' e 'many'. L'arabo ha 6 forme plurali. Lasci che le regole del plurale ICU gestiscano la logica: definisca tutte le forme richieste e UE selezionerà quella corretta per ogni cultura.
7

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.

Packaging & Testing Workflow
# 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.
Se una cultura non è elencata in Project Settings > Packaging > Localizations to Package, i relativi file .locres vengono esclusi dalla compilazione. I giocatori che selezionano tale lingua durante l'esecuzione vedranno testo di fallback o stringhe vuote. Verifichi sempre che le impostazioni del pacchetto corrispondano alle culture supportate.
8

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 (C++)
// 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);
Chiami ULocaleChain::Configure() una volta all'avvio per caricare 75 catene di fallback integrate che coprono 11 famiglie linguistiche. Usi ConfigureWithOverrides per una personalizzazione agevole nei Blueprint oppure ConfigureCustom in C++ per il pieno controllo del comportamento di fallback.

Automatizzare la qualità

Con i18n-validate, rilevi chiavi mancanti e segnaposto non validi prima del rilascio. Testi l'interfaccia con le pseudotraduzioni di i18n-pseudo prima che arrivino le traduzioni reali.

Problemi comuni

Uso di FString per il testo rivolto agli utenti

FString ignora l'intera pipeline di localizzazione. Il testo creato con FString::Printf o mediante concatenazione di stringhe non può essere raccolto, tradotto o visualizzato correttamente nelle lingue RTL. Usi sempre FText con macro LOCTEXT e FText::Format per le stringhe visibili agli utenti.

#undef LOCTEXT_NAMESPACE mancante

Dimenticare #undef LOCTEXT_NAMESPACE alla fine di un file .cpp fa propagare lo spazio dei nomi alle unità di traduzione successive. Le stringhe di altri file ricevono silenziosamente spazi dei nomi errati e le traduzioni appaiono nel contesto sbagliato.

Logica plurale codificata direttamente

Scrivere 'count == 1 ? singular : plural' ignora le regole CLDR. Il francese considera 0 singolare, il russo ha 4 forme plurali e l'arabo 6. Usi la sintassi plurale ICU nei pattern FText e lasci che UE gestisca le regole per ogni cultura.

Mancata compilazione dopo l'importazione

L'importazione dei file .po aggiorna i dati di testo, ma non genera i binari .locres. Durante l'esecuzione, il gioco continua a caricare le vecchie traduzioni compilate. Esegua sempre 'Compile' in Localization Dashboard dopo l'importazione oppure aggiunga il passaggio all'automazione della compilazione.

Struttura del progetto consigliata

Project Structure
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.uproject

Provi subito i18n Agent

Trascinare qui il file di traduzione

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

oppure fare clic per selezionarlo

Lingue di destinazione

Nessuna registrazione richiestaPreventivo immediato

Domande frequenti