Panduan Lengkap Penyetempatan Unreal Engine
Daripada makro FText hingga rantaian sandaran lokal: setempatkan permainan UE5 anda dengan Localization Dashboard, String Tables, C++, Blueprint, dan terjemahan automatik.
FText & Saluran Penyetempatan
FText ialah jenis rentetan Unreal Engine yang memahami penyetempatan. Setiap rentetan yang dilihat pengguna dalam permainan anda — label UI, dialog, petua alat, pemberitahuan — mesti menggunakan FText agar disertakan dalam saluran penyetempatan. FString hanya untuk logik dalaman.
// 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.Sediakan Localization Dashboard
Localization Dashboard ialah alat terbina dalam UE untuk mengurus terjemahan. Alat ini mengumpulkan semua rentetan LOCTEXT dan NSLOCTEXT daripada kod sumber anda, mengeksportnya sebagai fail .po untuk diterjemahkan, serta menyusun hasilnya menjadi fail binari .locres yang dimuatkan oleh UE semasa masa jalan.
# 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 LanguageGunakan String Tables untuk Teks Berasaskan Data
String Tables membolehkan anda mentakrifkan rentetan yang disetempatkan dalam aset berpusat dan bukannya menyebarkan makro LOCTEXT merentas fail sumber. Ciri ini sesuai untuk teks UI, dialog, dan sebarang rentetan yang perlu disunting oleh pereka atau penulis tanpa menyentuh kod. String Tables boleh ditakrifkan sebagai aset UE atau diimport daripada 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 KeyCorak Penyetempatan C++
Dalam C++, takrifkan LOCTEXT_NAMESPACE di bahagian atas setiap fail .cpp dan gunakan LOCTEXT untuk semua rentetan yang dilihat pengguna. Gunakan FText::Format untuk kandungan dinamik dengan pemboleh ubah. Sentiasa nyahTakrif ruang nama di hujung fail untuk mencegah kebocoran.
// 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());Penyetempatan Blueprint
Semua sifat Text dalam Blueprint secara lalai berupa FText, maka ia sudah sedia untuk penyetempatan. Tetapkan Key dan Namespace dalam panel butiran sifat supaya rentetan boleh dikumpulkan. Gunakan nod Format Text untuk kandungan dinamik dengan pemboleh ubah.
// 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")Kendalikan Bentuk Jamak dan Gender
Unreal Engine menyokong format mesej ICU untuk bentuk jamak dan teks yang bergantung pada gender. Takrifkan peraturan bentuk jamak dalam rentetan sumber anda dan UE memilih bentuk yang betul secara automatik berdasarkan peraturan CLDR budaya aktif.
// 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)"Pakejkan dan Uji Penyetempatan
Sebelum mengeluarkan produk, pastikan semua budaya sasaran mempunyai fail .locres tersusun dan teks dipaparkan dengan betul semasa masa jalan. Gunakan pratonton budaya Editor, penggantian budaya melalui baris perintah, dan pemeriksaan automatik untuk mengesan terjemahan yang tiada atau rosak.
# 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.Tambahkan Rantaian Sandaran Lokal
Penyetempatan lalai Unreal Engine hanya bersandar mengikut hierarki subtag IETF. Pengguna pt-BR yang tiada terjemahan mendapat bahasa Inggeris dan bukannya terjemahan pt-PT yang sebenarnya sesuai. locale-chain-ue menambahkan rantaian sandaran sisi boleh dikonfigurasikan melalui FTextLocalizationManager supaya pengguna serantau sentiasa melihat terjemahan tersedia yang paling dekat.
// 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);Automatikkan Kualiti Terjemahan
Kesilapan Umum
Menggunakan FString untuk Teks yang Dilihat Pengguna
#undef LOCTEXT_NAMESPACE Tiada
Logik Bentuk Jamak yang Dikod Keras
Terlupa Menyusun Selepas Import
Struktur Projek yang Disyorkan
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.uprojectCuba i18n Agent Sekarang
Lepaskan fail terjemahan anda di sini
JSON, YAML, PO, XML, CSV, Markdown, Properties
atau klik untuk semak imbas
Bahasa sasaran