Text Localization

Text in Unreal Engine (UE) is the primary component for localization. It is a specialized string, represented by the FText type in C++. This should be used when you have user-facing text that needs to be localized.

Internally, FText is implemented as a TSharedRef to an ITextData. This makes it very cheap to copy, and the FTextSnapshot utility provides an efficient way to detect if a cached FText value has actually changed.

The data held within FText instances varies, depending on how the FText was created. This variance is handled by the internal "text history" (FTextHistory). Text histories support the culture-correct rebuilding of text, and also form the key component for the following:

• Live culture switching.

• Sending FText over the network.

• Creating culture invariant sources.

Text Literals

Localizable text is made up of three components: a Namespace; a Key (which form its identity); and a Source String (which is the basis of what gets translated, and acts as validation against "stale" translations). The most common way to create localizable text in UE is by using a text literal.

Creating Text Literals in C++

Text literals can be created in C++ by using the LOCTEXT family of macros.

Text Literal Macros

Example:

	// Define the namespace to use with LOCTEXT
	// This is only valid within a single file, and must be undefined before the end of the file
	#define LOCTEXT_NAMESPACE "MyNamespace"
	// Create text literals
	constFTextHelloWorld= NSLOCTEXT("MyOtherNamespace","HelloWorld","Hello World!")
	constFTextGoodbyeWorld= LOCTEXT("GoodbyeWorld","Goodbye World!")
	// Undefine the namespace before the end of the file
	#undef LOCTEXT_NAMESPACE
Copy full snippet

Creating Text Literals in INI Files

Text literals can be created in INI files using the NSLOCTEXT macro syntax.

Creating Text Literals in Assets

Text literals can be created using FText properties. A Key is generated for you automatically, but you can define a custom Namespace or Key for your text by using the advanced combo next to the text field. It is also fine to use the default Namespace or Key.

Text Formatting

Text formatting provides a way to combine text in a way that is easier to localize, by using a localizable format pattern that injects real text to replace format placeholders.

Format placeholders are contained within a pair of curly braces, and can be numbers (for index-based formatting) or strings (for name-based formatting). For example:

"You have {0} health left." "You have {CurrentHealth} health left."

Format placeholders can also specify a function (called an "argument modifier") to run on their argument data. These are specified as a pipe followed by the function name and arguments. For example:

"{NumCats} {NumCats}|plural(one=cat,other=cats)"

	Result `{ {Res} }
Copy full snippet

	Result { 10 }
Copy full snippet

	Result \`\`{Res}\`\`  
Copy full snippet

	Result \`10\`
Copy full snippet

Text Formatting in C++

Text formatting in C++ is handled by the FText::Format family of functions. Each function takes an FTextFormat pattern, which will implicitly construct from an FText instance, followed by additional arguments as defined in the table below.

Text Formatting in Blueprints

Text formatting in Blueprints is handled by the Format Text node. This node can either take a literal format pattern, or the node can have the pattern linked to another Text pin.

• When a literal format pattern is specified, the format argument pins will be generated automatically.

• When the format pattern is linked to another Text pin, you must manually specify the arguments for the format using the Details panel of the node.

Argument Modifiers

Argument modifiers provide a way to pre-process an argument before it gets added to the formatted string. Argument modifiers are extensible. You create an argument modifier by implementing the ITextFormatArgumentModifier interface, and registering a factory function for a given keyword (see FTextFormatter::RegisterTextArgumentModifier).

UE provides some argument modifiers by default: there are modifiers for plurality, gender, and Hangul post-positions.

Plural Forms

Plural forms allow you to use different text based upon a numeric variable given to your text format. Plural forms may be cardinal (such as "There is 1 cat" or "There are 4 cats"), or ordinal (such as "You finished 1st!" or "You finished 2nd!"). Plural forms are specified as key-value pairs, and support any of the following keywords (as defined for your culture by the CLDR data): zero, one, two, few, many, other. Values are an optionally quoted string, that can also contain format markers.

Cardinal Format Example:

	"There {NumCats}|plural(one=is,other=are) {NumCats} {NumCats}|plural(one=cat,other=cats)"

Copy full snippet

Ordinal Format Example:

	"You came {Place}{Place}|ordinal(one=st,two=nd,few=rd,other=th)!"

Copy full snippet

Gender Forms

Gender forms allow you to use different text based on an ETextGender value given to your text format, such as "Le guerrier est fort" or "La guerrière est forte". Gender forms are specified as a list of values in the order of [masculine, feminine, neuter], where neuter is optional. Values are an optionally quoted string that may also contain format markers.

Format Example:

	"{Gender}|gender(Le,La) {Gender}|gender(guerrier,guerrière) est {Gender}|gender(fort,forte)"

Copy full snippet

Hangul Post-Positions

Hangul post-positions help you follow the grammar rules present in Korean, and will insert the correct glyph(s) based on whether the value being inserted ends in a consonant or a vowel, such as "사람은" or "사자는". Hangul post-positions are specified as a list of values in the order of [consonant, vowel]. Values are an optionally quoted string.

Format Example:

	"{Arg}|hpp(은,는)"

Copy full snippet

Text Formatting Best Practices

• When injecting a number that affects the sentence, handle these variances using the plural forms argument modifiers, rather than branching in code. When you use plural forms, the sentence is correctly translated for languages that do not share the plural rules of your source language.

• When injecting a personal noun, make sure you include an argument for the gender of the person. This is important for languages with grammar rules for gender, as it allows your translators to switch their translation based on the gender (see Gender Forms).

• Avoid injecting nouns for objects (such as "table," "door," or "chair"), or be prepared to make them localizable. These nouns might have one gender in one language, and a different gender in another language. This makes the format pattern string impossible to accurately localize without per-culture metadata. Ideally, you should include full sentences rather than just the noun. This will ensure accurate translations.

  Future versions of UE might include a function for translators to use metadata to tag text that represents nouns, that they can later branch on in format patterns to produce accurate translations.

• Avoid concatenating partial sentences. This can cause problems, as it is possible for each clause or part to be translated correctly and yet the translation of the whole could be incorrect. It is better to rewrite the text into full sentences, so you can ensure correct translation.

Text Generation

Text generation uses internationalization data to produce culture-correct text that doesn't rely on direct localization. There are three types of text generation: numerical, chronological, and transformative.

Numerical Text Generation

Numerical generation is used to convert numeric types into a text representation that is friendly for humans to read. The exact rules for this are culture-specific, and can also be tweaked on a per-generation basis if more specific control is required.

As an example, under the default generation rules, the floating-point number "1234.5" would generate as "1,234.5" under English, "1 234,5" under French, and "١٬٢٣٤٫٥" under Arabic.

Numerical Generation in C++

Numerical generation in C++ is handled by the following functions.

Most of the functions in the table take an optional [FNumberFormattingOptions](https://api.unrealengine.com/INT/API/Runtime/Core/Internationalization/FNumberFormattingOptions/index.html) to control the output (the default is taken from the active locale), and also an optional culture (default is the active locale).

Numerical Generation in Blueprints

Numerical generation in Blueprints is handled by the following nodes.

Most of the nodes in the table take advanced arguments to control the output.

Chronological

Chronological generation is used to convert date and time types into a text representation that is friendly for humans to read. The exact rules for this are culture-specific, and the date/time style can be adjusted on a per-generation basis if more specific control is required.

Under the default generation rules, a date representing the 22nd day of the 5th month of the year 1998 would generate "May 22, 1998" under English (United States), "22 May 1998" under English (United Kingdom), "22 mai 1998" under French, and "٢٢‏/٠٥‏/١٩٩٨" under Arabic.

Chronological Generation in C++

Chronological generation in C++ is handled by the following functions.

Most of the above take EDateTimeStyle to control the output (default is taken from the active locale, but may be set as "short", "medium", "long", or "full").

Chronological Generation in Blueprints

Chronological generation in Blueprints is handled by the following nodes.

Transformative

Transformative generation is used to convert text into a different representation of itself. For example, you can convert lower case text to upper case text, or convert upper case text to lower case text.

Transformative Generation in C++

Transformative generation in C++ is handled by the following functions.

Transformative Generation in Blueprints

Transformative generation in Blueprints is handled by the following nodes.

String Tables

String Tables provide a way to centralize your localized text into one (or several) known locations, and then reference the entries within a string table from other assets or code in a robust way that allows for easy re-use of localized text.

String Tables can be defined in C++, loaded using a CSV file, or created as an Asset. See the String Tables page for more information.

Text Value Marshalling

Text values can be losslessly marshalled as strings (using FTextStringHelper, or the ImportText and ExportText functions of UTextProperty).

The following formats are supported:

Data Tables

One common cause of unstable localization keys is iteratively importing raw strings from a CSV file into a Data Table, as this causes a new key to be generated after each import. A solution for this is to assign the imported text a deterministic key post-import by overriding the OnPostDataImport function on your row struct, and calling FText::ChangeKey to assign the new key.

Typically we use the data table name as the Namespace, and a combination of the row name and property name as the Key. For example:

	voidFMyTableRow::OnPostDataImport(constUDataTable*InDataTable,constFNameInRowName,TArray&OutCollectedImportProblems)
	{
	#if WITH_EDITOR
		MyTextProperty = FText::ChangeKey(
		InDataTable->GetName(),
		FString::Printf(TEXT("%s_%s"),*InRowName.ToString(), GET_MEMBER_NAME_STRING_CHECKED(FMyTableRow,MyTextProperty)),
		MyTextProperty
		);
	#endif// WITH_EDITOR
	}

Copy full snippet

Polyglot Data

Polyglot data allows new localization data to be added at runtime, either to interface with an external system, or to allow hot-fixing localization without building new LocRes files.

Polyglot data is comprised of: a Namespace and Key (its identity); a Native String; the category of the text (such as game, engine, editor), to control when the polyglot data is used; an optional native culture (which will fallback to the native culture of the category if unset); and a series of per-culture translations.

Polyglot Data in C++

Polyglot data in C++ is represented by the FPolyglotTextData type, and it can either be used directly (using FPolyglotTextData::GetText to resolve the polyglot data into a text instance), or it can be passed to FTextLocalizationManager::RegisterPolyglotTextData (to patch existing text entries).

Polyglot Data in Blueprints

Polyglot data in Blueprints is represented by the Polyglot Text Data type, and can be used with the Polyglot Data to Text function to resolve the polyglot data into a text instance.

Localized Text Sources

Localized text sources are the primary way that the UE text localization manager discovers and processes localized text data. UE provides two of these by default: FLocalizationResourceTextSource (which hosts LocRes support), and FPolyglotTextSource (which hosts polyglot data support).

Localized text sources can provide a way to interface with an external system, and can be added on a per-project basis by creating and registering a type derived from ILocalizedTextSource.