Skip to main content

Guia completa de localització d'Unreal Engine

Des de les macros de FText fins a les cadenes de reserva de configuracions regionals: localitzi el seu joc d'UE5 amb el tauler de localització, les taules de cadenes, C++, Blueprints i la traducció automatitzada.

1

FText i el procés de localització

FText és el tipus de cadena d'Unreal Engine preparat per a la localització. Totes les cadenes del joc que veu l'usuari —etiquetes de la interfície, diàlegs, indicadors de funció i notificacions— han d'utilitzar FText per formar part del procés de localització. FString només és per a la lògica interna.

LOCTEXT requereix dos arguments: una clau i una cadena d'origen. La clau ha de ser única dins del seu espai de noms. El recopilador de text d'UE utilitza aquestes claus per fer el seguiment de les traduccions entre cultures. NSLOCTEXT permet especificar explícitament l'espai de noms; LOCTEXT utilitza l'espai de noms definit per la macro LOCTEXT_NAMESPACE que l'engloba.
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.
No construeixi mai text visible per a l'usuari amb FString::Printf ni concatenant cadenes. Aquests mètodes ometen completament el procés de localització: el text resultant no es pot recopilar ni traduir i tampoc es pot mostrar correctament en llengües RTL. Utilitzi sempre FText::Format amb patrons LOCTEXT.
2

Configurar el tauler de localització

El tauler de localització és l'eina integrada d'UE per gestionar traduccions. Recopila totes les cadenes LOCTEXT i NSLOCTEXT del codi font, les exporta com a fitxers .po perquè es tradueixin i compila els resultats en fitxers binaris .locres que UE carrega en temps d'execució.

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
Executi «Recopila el text» després de cada canvi de codi que afegeixi o modifiqui macros LOCTEXT. Si omet aquest pas, les cadenes noves no apareixeran als fitxers .po i els traductors no les veuran. Afegeixi un pas de recopilació a l'automatització de la compilació perquè es faci automàticament.
3

Utilitzar taules de cadenes per al text basat en dades

Les taules de cadenes permeten definir cadenes localitzades en un recurs centralitzat en comptes de dispersar macros LOCTEXT pels fitxers font. Són ideals per al text de la interfície, els diàlegs i qualsevol cadena que els dissenyadors o redactors hagin d'editar sense modificar el codi. Les taules de cadenes es poden definir com a recursos d'UE o importar des de 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
El tauler de localització recopila automàticament les taules de cadenes. No calen macros LOCTEXT per a les cadenes definides en una taula de cadenes: només cal fer-hi referència mitjançant l'ID de la taula i la clau en C++ o Blueprints.
4

Patrons de localització en C++

En C++, defineixi un LOCTEXT_NAMESPACE al començament de cada fitxer .cpp i utilitzi LOCTEXT per a totes les cadenes visibles per a l'usuari. Utilitzi FText::Format per al contingut dinàmic amb variables. Anul·li sempre la definició de l'espai de noms al final del fitxer per evitar que es propagui.

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());
Els arguments de FText::Format també han de ser FText, no pas valors FString sense processar. Utilitzi FText::FromString() per convertir valors FString, FText::AsNumber() per formatar nombres segons la configuració regional i FText::AsCurrency() per als preus. La concatenació directa de valors FString produeix text que no respecta les regles de format de la configuració regional.
5

Localització amb Blueprints

Totes les propietats Text de Blueprints són FText per defecte, de manera que ja estan preparades per localitzar-se. Defineixi la clau i l'espai de noms al tauler de detalls de la propietat perquè les cadenes es puguin recopilar. Utilitzi el node Format Text per al contingut dinàmic amb variables.

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")
Desplegui la propietat de text al tauler de detalls de Blueprint per veure els camps de clau, espai de noms i cadena d'origen. Una clau descriptiva facilita molt que els traductors identifiquin les cadenes al fitxer .po.
6

Gestionar els plurals i el gènere

Unreal Engine admet el format de missatges d'ICU per als plurals i el text que varia segons el gènere. Defineixi les regles de plural a les cadenes d'origen i UE seleccionarà automàticament la forma correcta segons les regles CLDR de la cultura activa.

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)"
No codifiqui mai count == 1 de manera fixa per detectar el singular. En francès, 0 es considera singular. El rus té formes diferents per a 'few' i 'many'. L'àrab té 6 formes plurals. Deixi que les regles de plural d'ICU s'encarreguin de la lògica: defineixi totes les formes necessàries i UE seleccionarà l'adequada per a cada cultura.
7

Empaquetar i provar la localització

Abans de publicar el producte, comprovi que totes les cultures de destinació tinguin fitxers .locres compilats i que el text es representi correctament en temps d'execució. Utilitzi la previsualització de cultures de l'editor, les substitucions de cultura mitjançant la línia d'ordres i les comprovacions automatitzades per detectar traduccions absents o defectuoses.

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.
Si una cultura no figura a Project Settings > Packaging > Localizations to Package, els seus fitxers .locres s'exclouen de la compilació. Els jugadors que seleccionin aquesta llengua en temps d'execució veuran el text de reserva o cadenes buides. Comprovi sempre que la configuració d'empaquetament coincideixi amb les cultures admeses.
8

Afegir cadenes de reserva de configuracions regionals

Per defecte, la localització d'Unreal Engine només recorre a configuracions alternatives seguint la jerarquia de subetiquetes IETF. Si falta una traducció per a un usuari de pt-BR, aquest veu el text en anglès en comptes d'una traducció pt-PT perfectament vàlida. locale-chain-ue afegeix cadenes de reserva laterals configurables mitjançant FTextLocalizationManager perquè els usuaris regionals vegin sempre la traducció disponible més propera.

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);
Cridi ULocaleChain::Configure() una vegada durant l'arrencada per carregar 75 cadenes de reserva integrades que abasten 11 famílies lingüístiques. Utilitzi ConfigureWithOverrides per personalitzar-les fàcilment amb Blueprints o ConfigureCustom en C++ per controlar completament el comportament de reserva.

Automatitzar la qualitat de la traducció

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

Errors habituals

Utilitzar FString per al text visible per a l'usuari

FString omet tot el procés de localització. El text creat amb FString::Printf o concatenant cadenes no es pot recopilar ni traduir i tampoc es pot mostrar correctament en llengües RTL. Utilitzi sempre FText amb macros LOCTEXT i FText::Format per a les cadenes visibles per a l'usuari.

Ometre #undef LOCTEXT_NAMESPACE

Si s'oblida d'afegir #undef LOCTEXT_NAMESPACE al final d'un fitxer .cpp, l'espai de noms es propaga a les unitats de traducció següents. Això assigna silenciosament espais de noms incorrectes a les cadenes d'altres fitxers i fa que les traduccions apareguin en un context equivocat.

Lògica de plural codificada de manera fixa

Escriure 'count == 1 ? singular : plural' no té en compte les regles CLDR. En francès, 0 es considera singular; el rus té 4 formes plurals i l'àrab en té 6. Utilitzi la sintaxi de plural d'ICU als patrons FText i deixi que UE apliqui les regles de cada cultura.

Oblidar-se de compilar després de la importació

Importar fitxers .po actualitza les dades de text, però no genera els binaris .locres. El joc continua carregant les traduccions compilades antigues en temps d'execució. Executi sempre «Compila» al tauler de localització després d'importar o afegeixi aquest pas a l'automatització de la compilació.

Estructura de projecte recomanada

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

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

Preguntes més freqüents