Localization Setup

This guide shows you how to make text localizable in Unreal Engine so the AI Localization Automator can discover and translate it.

Already Familiar with UE Localization?

If you're already familiar with Unreal Engine's localization pipeline and have experience setting up FText, localization targets, and gathering text, you can safely skip this page and go directly to Getting Started.

This page covers the fundamental UE localization setup that's required before using any translation tools, including the AI Localization Automator.

New to UE Localization?

If you're completely new to Unreal Engine's localization system, we highly recommend watching this short video tutorial first: Unreal Engine 5 Localization Tutorial.

After watching the video, most topics covered in this page will already be clear and understandable, and you'll most likely be able to skip this page and go directly to Getting Started.

The guide below covers general Unreal Engine localization setup and workflow - these steps are applicable to any translation project in UE, not just AI-powered translation. It's a reference for the fundamental localization concepts and setup process.

Understanding Localizable Text

For the AI Localization Automator to work, you need FText properties marked as localizable in your project. The plugin discovers text through UE's localization system, so text must be properly configured first.

FText vs FString vs FName

Only FText (Text in Blueprints) can be localized in Unreal Engine:

• ✅ FText: Localizable, supports rich formatting, used for user-facing text
• ❌ FString: Not localizable, used for internal data and file paths
• ❌ FName: Not localizable, used for identifiers and keys

Making Text Localizable in Blueprints

1. Create FText Variables

In your Blueprint classes:

1. Add FText Variable
   • Open your Blueprint class
   • Add a new variable of type Text (FText)

2. Set Default Value
   • In the variable details, set your default text value
   • This will become your source text for translation

3. Enable Localization
   • Click the flag icon located to the right of your text content
   • In the localization window that opens, check the "Localize" checkbox - this is critical!
   • Optionally set a custom Key and Namespace for organization

2. Where FText is Used

Once you have localizable FText variables, they can be used throughout the Unreal Engine ecosystem including: UMG widgets, HUD classes, GameMode/GameState for UI messages, Actor components for interaction prompts, dialogue systems, input action names, achievement/trophy descriptions, save game display text, console commands help text, editor tools, and any custom Blueprint or C++ system that displays user-facing content.

Making Text Localizable in C++

1. Use LOCTEXT Macros

For static text in C++:

// At the top of your file
#define LOCTEXT_NAMESPACE "MyGameUI"

// Create localizable text
FText WelcomeText = LOCTEXT("WelcomeMessage", "Welcome to the game!");
FText ButtonText = LOCTEXT("StartButton", "Start Game");

// At the end of your file  
#undef LOCTEXT_NAMESPACE

2. Use NSLOCTEXT for Specific Namespaces

// For text with custom namespace/key
FText ScoreText = NSLOCTEXT("GameUI", "ScoreLabel", "Score: {0}");
FText HealthText = NSLOCTEXT("GameUI", "HealthDisplay", "Health");

3. FText Properties in Classes

UCLASS()
class MYGAME_API UMyUserWidget : public UUserWidget
{
    GENERATED_BODY()

public:
    // Localizable text property  
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Localization")
    FText DisplayText;

    // Function returning localizable text
    UFUNCTION(BlueprintCallable)
    FText GetWelcomeMessage() const
    {
        return LOCTEXT("Welcome", "Welcome, player!");
    }
};

Setting Up Localization Target

1. Create Localization Target

1. Open Localization Dashboard (Tools → Localization Dashboard)
2. By default, there should already be a Game target available to translate text from
3. If there's no Game target, click "Add New Target" and enter "Game" as the name, and select Game as the Loading Policy

2. Configure Gather Settings

1. Select your target in the dashboard
2. Go to the "Gather Text" section in the Game panel

For Blueprint Content:

3. Turn on "Gather from Packages" and expand it
4. In "Include Path Wildcards", select the directory where your assets with localizable text are located

For C++ Content:

5. Turn on "Gather from Text Files" and expand it
6. In "Search Directories", provide the directory of your C++ code where the source localizable text is located

There are many additional parameters available such as Exclude Path Wildcards, File Extensions, and other options that allow you to fine-tune how the system searches for localizable text.

3. Add Target Languages

1. In the Localization Dashboard, with your target selected
2. Click the "Add New Language" button
3. Select a single language from the dropdown (e.g., Spanish, French, German)
4. Repeat this process for each target language you want to translate to
5. Ensure your native culture is marked as the source language using the radio button on the left side of the language list (English is selected by default)

4. Gather Text

1. Click the "Gather Text" button in your target
2. Wait for the gathering process to complete
3. Click the "OK" button when the process finishes
4. Verify that text entries appear in the Word Count column

5. Edit Localizations

Once text has been gathered, you can now manually edit and add localizations:

1. Click the Edit button (first button) in the Actions column for each target language
2. This opens the localization editor where you can manually translate words and phrases per language
3. For testing purposes, you can add your own testing localizations manually to verify the system works

Automatic AI Translation

The AI Localization Automator plugin will handle this translation process automatically using AI providers. For detailed information about automatic AI translation, see Getting Started.

6. Compile Text

After adding localizations (either manually or through the AI Localization Automator as explained in Your First Translation):

1. Click the "Compile Text" button in your localization target
2. Wait for the compilation process to complete - similar to the Gather Text operation
3. Once compilation finishes, the translated text should be available and visible in your project
4. You can now test your localizations using the methods described below

Test Localization

There are different ways to test your localization setup. Here are the most commonly used methods:

Method 1: Editor Preferences

1. Go to Editor Preferences → Region & Language
2. In the "Preview Game Language" property, select your language to preview
3. Note: If the language list is missing, this might be a common UE bug which is fixed by restarting the editor

Method 2: UMG Preview

1. In the UMG editor, when you want to preview translations in your UI widgets
2. In the upper right section of the preview widget, there's an option to select the language for previewing localizations

Ready for AI Translation

Once you have:

• ✅ Localizable FText content in your project
• ✅ Properly configured localization target with "Game" name
• ✅ Successfully gathered source text using the correct gather settings
• ✅ Added target languages for translation
• ✅ Verified your setup through testing

You're ready to use the AI Localization Automator! Go to Getting Started to configure your AI provider and start translating.