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.
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.
// 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.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ó.
# 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 LanguageUtilitzar 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.
// 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 KeyPatrons 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.
// 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());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 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")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.
// 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)"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.
# 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.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: 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);Automatitzar la qualitat de la traducció
Errors habituals
Utilitzar FString per al text visible per a l'usuari
Ometre #undef LOCTEXT_NAMESPACE
Lògica de plural codificada de manera fixa
Oblidar-se de compilar després de la importació
Estructura de projecte recomanada
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.uprojectProvar i18n Agent ara
Arrossegar aquí el fitxer de traducció
JSON, YAML, PO, XML, CSV, Markdown, Properties
o fer clic per explorar
Idiomes de destinació