Skip to main content

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.

1

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.

LOCTEXT memerlukan dua argumen: kekunci dan rentetan sumber. Kekunci mesti unik dalam ruang namanya. Pengumpul teks UE menggunakan kekunci ini untuk menjejaki terjemahan merentas budaya. NSLOCTEXT membolehkan anda menentukan ruang nama secara jelas; LOCTEXT menggunakan ruang nama yang ditakrifkan oleh makro LOCTEXT_NAMESPACE yang membungkusnya.
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.
Jangan sekali-kali mencipta teks yang dilihat pengguna dengan FString::Printf atau penggabungan rentetan. Cara ini melangkaui saluran penyetempatan sepenuhnya — teks yang dihasilkan tidak boleh dikumpulkan, diterjemahkan, atau dipaparkan dengan betul dalam bahasa RTL. Sentiasa gunakan FText::Format dengan corak LOCTEXT.
2

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.

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
Jalankan 'Gather Text' selepas setiap perubahan kod yang menambahkan atau mengubah makro LOCTEXT. Jika langkah ini tertinggal, rentetan baharu tidak akan muncul dalam fail .po dan tidak akan dilihat oleh penterjemah. Tambahkan langkah pengumpulan pada automasi binaan anda agar hal ini dikesan secara automatik.
3

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

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 dikumpulkan secara automatik oleh Localization Dashboard. Anda tidak memerlukan makro LOCTEXT untuk rentetan yang ditakrifkan dalam String Table — hanya rujuk berdasarkan ID jadual dan kekunci dalam C++ atau Blueprint.
4

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

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());
Argumen FText::Format juga mesti berupa FText, bukan FString mentah. Gunakan FText::FromString() untuk menukar nilai FString, FText::AsNumber() untuk pemformatan nombor yang memahami lokal, dan FText::AsCurrency() untuk harga. Penggabungan FString mentah menghasilkan teks yang tidak mematuhi peraturan pemformatan lokal.
5

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 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")
Kembangkan menu lungsur sifat teks dalam panel Blueprint Details untuk melihat medan Key, Namespace, dan Source String. Menetapkan Key yang bermakna memudahkan penterjemah mengenal pasti rentetan dalam fail .po.
6

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.

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)"
Jangan sekali-kali mengekod keras count == 1 untuk mengesan bentuk tunggal. Bahasa Perancis menganggap 0 sebagai bentuk tunggal. Bahasa Rusia mempunyai bentuk berasingan untuk 'sedikit' dan 'banyak'. Bahasa Arab mempunyai 6 bentuk jamak. Biarkan peraturan bentuk jamak ICU mengendalikan logiknya — takrifkan semua bentuk yang diperlukan dan UE memilih bentuk yang betul bagi setiap budaya.
7

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.

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.
Jika sesuatu budaya tidak disenaraikan dalam Project Settings > Packaging > Localizations to Package, fail .locres-nya dikecualikan daripada binaan. Pemain yang memilih bahasa tersebut semasa masa jalan akan melihat teks sandaran atau rentetan kosong. Sentiasa pastikan tetapan pemakejan anda sepadan dengan budaya yang disokong.
8

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 (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);
Panggil ULocaleChain::Configure() sekali semasa permulaan untuk memuatkan 75 rantaian sandaran terbina dalam yang merangkumi 11 keluarga bahasa. Gunakan ConfigureWithOverrides untuk penyesuaian mesra Blueprint, atau ConfigureCustom dalam C++ untuk kawalan penuh terhadap tingkah laku sandaran.

Automatikkan Kualiti Terjemahan

Kesan kekunci hilang dan ruang letak rosak sebelum dikeluarkan dengan i18n-validate. Uji UI dengan terjemahan pseudo menggunakan i18n-pseudo sebelum terjemahan sebenar tersedia.

Kesilapan Umum

Menggunakan FString untuk Teks yang Dilihat Pengguna

FString melangkaui seluruh saluran penyetempatan. Teks yang dicipta dengan FString::Printf atau penggabungan rentetan tidak boleh dikumpulkan, diterjemahkan, atau dipaparkan dengan betul dalam bahasa RTL. Sentiasa gunakan FText dengan makro LOCTEXT dan FText::Format untuk rentetan yang kelihatan kepada pengguna.

#undef LOCTEXT_NAMESPACE Tiada

Terlupa menulis #undef LOCTEXT_NAMESPACE di hujung fail .cpp menyebabkan ruang nama bocor ke unit terjemahan seterusnya. Hal ini menetapkan ruang nama yang salah pada rentetan dalam fail lain secara senyap sehingga terjemahan muncul dalam konteks yang salah.

Logik Bentuk Jamak yang Dikod Keras

Menulis 'count == 1 ? singular : plural' mengabaikan peraturan CLDR. Bahasa Perancis menganggap 0 sebagai bentuk tunggal, Rusia mempunyai 4 bentuk jamak, dan Arab mempunyai 6. Gunakan sintaks bentuk jamak ICU dalam corak FText anda dan biarkan UE mengendalikan peraturan bagi setiap budaya.

Terlupa Menyusun Selepas Import

Mengimport fail .po mengemas kini data teks, tetapi tidak menjana binari .locres. Permainan tetap memuatkan terjemahan lama yang telah disusun semasa masa jalan. Sentiasa jalankan 'Compile' dalam Localization Dashboard selepas mengimport, atau tambahkan langkah ini pada automasi binaan anda.

Struktur Projek yang Disyorkan

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

Cuba i18n Agent Sekarang

Lepaskan fail terjemahan anda di sini

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

atau klik untuk semak imbas

Bahasa sasaran

Tidak perlu mendaftarAnggaran serta-merta

Soalan Lazim