Skip to main content

Ghidul complet pentru localizarea în Unreal Engine

De la macrocomenzile FText la lanțurile de rezervă pentru setările regionale: localizați-vă jocul UE5 folosind Localization Dashboard, String Tables, C++, Blueprints și traducerea automată.

1

FText și fluxul de localizare

FText este tipul de șir din Unreal Engine care permite localizarea. Fiecare șir destinat utilizatorilor din joc — etichete ale interfeței, dialoguri, infobule și notificări — trebuie să folosească FText pentru a participa la fluxul de localizare. FString este destinat exclusiv logicii interne.

LOCTEXT necesită două argumente: o cheie și un șir sursă. Cheia trebuie să fie unică în spațiul său de nume. Colectorul de texte din UE folosește aceste chei pentru a urmări traducerile în diferite culturi. NSLOCTEXT vă permite să specificați explicit spațiul de nume, iar LOCTEXT folosește spațiul de nume definit de macrocomanda LOCTEXT_NAMESPACE înconjurătoare.
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.
Nu construiți niciodată text destinat utilizatorilor folosind FString::Printf sau concatenarea șirurilor. Acestea ocolesc complet fluxul de localizare — textul rezultat nu poate fi colectat, tradus sau afișat corect în limbile RTL. Folosiți întotdeauna FText::Format cu modele LOCTEXT.
2

Configurați Localization Dashboard

Localization Dashboard este instrumentul integrat în UE pentru administrarea traducerilor. Acesta colectează toate șirurile LOCTEXT și NSLOCTEXT din codul sursă, le exportă ca fișiere .po pentru traducere și compilează rezultatele în fișiere binare .locres, pe care UE le încarcă în timpul execuției.

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
Executați 'Gather Text' după fiecare modificare a codului care adaugă sau modifică macrocomenzi LOCTEXT. Dacă omiteți acest pas, șirurile noi nu vor apărea în fișierele .po, iar traducătorii nu le vor vedea. Adăugați un pas de colectare în automatizarea compilării pentru a detecta automat această situație.
3

Folosiți String Tables pentru texte bazate pe date

String Tables vă permit să definiți șiruri localizate într-o resursă centralizată, în loc să răspândiți macrocomenzi LOCTEXT prin fișierele-sursă. Sunt ideale pentru textul interfeței, dialoguri și orice șiruri pe care designerii sau autorii trebuie să le editeze fără a modifica codul. String Tables pot fi definite ca resurse UE sau importate din 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
String Tables sunt colectate automat de Localization Dashboard. Nu aveți nevoie de macrocomenzi LOCTEXT pentru șirurile definite într-un String Table — este suficient să le referiți prin ID-ul tabelului și cheie în C++ sau Blueprints.
4

Modele de localizare în C++

În C++, definiți un LOCTEXT_NAMESPACE la începutul fiecărui fișier .cpp și folosiți LOCTEXT pentru toate șirurile destinate utilizatorilor. Folosiți FText::Format pentru conținut dinamic cu variabile. Anulați întotdeauna definiția spațiului de nume la sfârșitul fișierului pentru a împiedica propagarea acestuia.

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());
Argumentele FText::Format trebuie să fie tot de tip FText, nu valori FString brute. Folosiți FText::FromString() pentru a converti valori FString, FText::AsNumber() pentru formatarea numerelor conform setării regionale și FText::AsCurrency() pentru prețuri. Concatenarea valorilor FString brute produce text care nu respectă regulile locale de formatare.
5

Localizarea în Blueprint

Toate proprietățile Text din Blueprints sunt implicit de tip FText, așadar sunt deja pregătite pentru localizare. Setați Key și Namespace în panoul cu detaliile proprietății pentru ca șirurile să poată fi colectate. Folosiți nodul Format Text pentru conținut dinamic cu variabile.

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")
Extindeți lista proprietății text din panoul Blueprint Details pentru a vedea câmpurile Key, Namespace și Source String. Stabilirea unei valori Key sugestive îi ajută considerabil pe traducători să identifice șirurile în fișierul .po.
6

Gestionați pluralurile și genul

Unreal Engine acceptă formatul de mesaje ICU pentru pluraluri și text dependent de gen. Definiți regulile de plural în șirurile sursă, iar UE selectează automat forma corectă pe baza regulilor CLDR ale culturii active.

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)"
Nu includeți niciodată direct în cod condiția count == 1 pentru detectarea singularului. Franceza tratează 0 ca singular. Rusa are forme distincte pentru 'few' și 'many'. Araba are 6 forme de plural. Lăsați regulile de plural ICU să gestioneze logica — definiți toate formele necesare, iar UE o va selecta pe cea corectă pentru fiecare cultură.
7

Împachetați și testați localizarea

Înainte de lansare, verificați dacă toate culturile vizate au fișiere .locres compilate și dacă textul este afișat corect în timpul execuției. Folosiți previzualizarea culturii din Editor, înlocuirea culturii prin linia de comandă și verificări automate pentru a detecta traducerile lipsă sau deteriorate.

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.
Dacă o cultură nu este enumerată în Project Settings > Packaging > Localizations to Package, fișierele sale .locres sunt excluse din versiunea compilată. Jucătorii care selectează limba respectivă în timpul execuției vor vedea textul de rezervă sau șiruri goale. Verificați întotdeauna dacă setările de împachetare corespund culturilor acceptate.
8

Adăugați lanțuri de rezervă pentru setările regionale

Mecanismul implicit de localizare din Unreal Engine revine numai de-a lungul ierarhiei de subetichete IETF. Un utilizator pt-BR pentru care lipsește o traducere primește textul în engleză, în locul unei traduceri pt-PT perfect valabile. locale-chain-ue adaugă prin FTextLocalizationManager lanțuri laterale de rezervă configurabile, astfel încât utilizatorii regionali să vadă întotdeauna cea mai apropiată traducere disponibilă.

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);
Apelați ULocaleChain::Configure() o singură dată la pornire pentru a încărca 75 de lanțuri de rezervă incluse, care acoperă 11 familii de limbi. Folosiți ConfigureWithOverrides pentru personalizare accesibilă din Blueprint sau ConfigureCustom în C++ pentru control complet asupra comportamentului de rezervă.

Automatizați controlul calității traducerilor

Detectați cheile lipsă și substituenții nevalizi înainte de lansare folosind i18n-validate. Testați-vă interfața cu pseudotraduceri folosind i18n-pseudo înainte de sosirea traducerilor reale.

Probleme frecvente

Folosirea FString pentru textul destinat utilizatorilor

FString ocolește întregul flux de localizare. Textul construit cu FString::Printf sau prin concatenarea șirurilor nu poate fi colectat, tradus sau afișat corect în limbile RTL. Folosiți întotdeauna FText cu macrocomenzi LOCTEXT și FText::Format pentru șirurile vizibile utilizatorilor.

Lipsește #undef LOCTEXT_NAMESPACE

Omiterea #undef LOCTEXT_NAMESPACE la sfârșitul unui fișier .cpp face ca spațiul de nume să se propage în unitățile de traducere următoare. Astfel sunt atribuite fără avertisment spații de nume greșite șirurilor din alte fișiere, iar traducerile apar în contextul greșit.

Logică de plural inclusă direct în cod

Scrierea expresiei 'count == 1 ? singular : plural' ignoră regulile CLDR. Franceza tratează 0 ca singular, rusa are 4 forme de plural, iar araba are 6. Folosiți sintaxa de plural ICU în modelele FText și lăsați UE să gestioneze regulile pentru fiecare cultură.

Compilarea a fost omisă după import

Importarea fișierelor .po actualizează datele textului, dar nu generează fișierele binare .locres. În timpul execuției, jocul încarcă în continuare traducerile vechi compilate. Executați întotdeauna 'Compile' în Localization Dashboard după import sau adăugați acest pas în automatizarea compilării.

Structura recomandată a proiectului

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

Încercați acum i18n Agent

Plasați aici fișierul de traducere

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

sau faceți clic pentru a-l selecta

Limbi țintă

Nu este necesară înregistrareaEstimare instantanee

Întrebări frecvente