Localizing Text in the Unreal Engine

Overview

The Unreal Engine primarily relies on localized text files to display text in a given language.

Configuration is determined by key-value pairs, arranged in sections. One or more values can be associated with a given key.

The language can be changed by setting the Language variable in your game project's Engine configuration file to the specified language, which correlates to a localization directory.

For example, this is how you would set the language to Japanese:

[Engine.Engine]
...
Language=jpn
...

UnrealLoc

The UnrealLoc tool has been written to manage localized text in the engine; it handles the more mundane tasks.

Working with Localized Text Files

Localization in UE3 is handled with a series of localized text files in the \Localization directory and its sub-directories. Each language has its own three letter code (JPN=Japanese, KOR=Korean, CHT=Chinese, DEU=German, etc.) corresponding to a subdirectory that contains the files for that language. Some of the codes may seem unclear, specifically ESM and ESN, which refer to Latin American and European Spanish. Even the default English build should be using localization files, using the character code INT (for International). (ENG can also be used for English.)

File Format

The localized text files themselves are just simple INI-style configuration files, although they should be saved as Unicode (UTF-16 little-endian), and do not inherit from their engine counterparts. The filename itself is the same as the package that the localized data belongs in; and the extension is the same as the directory that the file resides in in the Localization directory.

Sections and Key-Value Pairs

Typical configuration files consist of sections of key-value pairs, arranged as follows:

[Section]
Key=Value

For instance, if you have a script package called MyGame.u, there should be a MyGame.int containing all of the default localized strings for the script classes in MyGame.u. So, if you have a script class called MyHUD.uc, with localized string properties CheckpointReachedString and LoadingString, one of the sections in MyGame.int would be:

[MyHUD]
CheckpointReachedString=Checkpoint Reached
LoadingString=Loading

One of the things to keep in mind about this section is that it needs to be created by hand. UnrealScript will not allow you to specify a default string for a localizable property in the defaultproperties section of the UnrealScript class. If you try, the script compilation will fail. This is actually a good thing because it forces you to be aware of the strings that must be translated and get them into the localized text file as soon as possible.

String Data

Localized strings that are part of data and map packages work in a similar fashion, but have some important differences. Although you can manually create localized text files for these packages, it is usually better to run the Full Loc Export... command from the context menu on the package tree view within the Generic Browser on the packages. This will auto-generate localized text files on a per-package basis with the necessary text.

Be careful: anything you enter in a property window will be overwritten by the INT contents the next time you load the package/map. You'll need to re-xport loc files before terminating the editor session.

Per-Object String Data

The MyHUD example above assumes that there is only one string used for the CheckpointReachedString and LoadingString properties even if multiple instances of the class exist. What happens if you create a class that needs to have different designer-specified localizable text for each instance? For example, if you are using archetypes as a system to build weapons, each of them might need a localized name and description. In this case, the class with the localizable string properties needs to be marked as perobjectconfig in its definition. By doing this, running the Full Loc Export... on packages containing objects of that class will output individual strings for each instance of the class. So, for instance, if you have a package called VO.upk with three WAV files in it (WAV1, WAV2, WAV3), each with a filled-in SpokenText field, running Full Loc Export... on it will generate a localized text file called VO.int with these sections in it:

[WAV1 SoundNodeWave]
SpokenText="<WAV1 Text, whatever that may be>"

[WAV2 SoundNodeWave]
SpokenText="<WAV2 Text, whatever that may be>"

[WAV3 SoundNodeWave]
SpokenText="<WAV3 Text, whatever that may be>"

Notice that the section names include both the resource name and its class. This, coupled with the filename VO.int, should specifically address all of the localized strings in VO.upk.

Wrapping and New Line in UIStrings

When manually editing a localized text file, you may encounter problems with wrapping and new lines in UI Strings.

So, for example, the following:

[GenericStrings]
Output="Line 1/nLine2/nLine 3"

Would return this:

Line 1ine2ine3

Previewing the string within the UI Editor DataStore Browser^? will also yield the same.

However, modifying a single localized string and applying changes within the UI Editor DataStore Browser^? appears to automatically remove any quotes surrounding the strings in the entire INT file affected. This will cause the escape characters to work as expected.

Solution: If you're manually entering localized strings into an INT file with a text editor, do not use quotes!

This is the proper declaration:

[GenericStrings]

Output=Line 1/nLine2/nLine 3

Which will yield the following:

Line 1
Line 2
Line 3

Binary Data

For binary data, localization just involves having different packages with an additional extension using the three letter code of the target language. So, for instance, if you have a package called Art.upk with a texture in it that needs to be localized, if the language you're currently running is Japanese (as specified in Engine.ini), the engine will automatically first look for a package called Art_jpn.upk to find the texture before it looks for it in Art.upk. This has implications for the console cooking process, since you may need to do one cook for each language to fill the seek-free packages with the right localized data.

A benefit of having localization data in separate text files is that the data can be quickly iterated on and previewed in-game without having to resave content. This benefit is especially pronounced for consoles, where content changes require some kind of cooking step.

Declaring the Localized Text File Data

The class declaration describes the new section name of the localized text file. Any string that contains the localized keyword will be available for export and will therefore will be in the associated localized text file.

For example, the following example class declares that its strings will be exported to the MyGame.int localized text file:

class MyHUD extends HUD
   var localized string CheckpointReachedString;
   var localized string LoadingString;

See the UnrealScript Reference for more information on localized strings.

Available Localized Text Files

Localized text files are located in the Localization directory of a given project, in language-specific subdirectories

Here is a list of localized text files available with a given project using the Unreal Engine:

• .int (project name)
• Editor.int (if editor changes are made in your project)
• UI.int (for UI)
• Content.int (for binary content)
• Credits.int (for credits)
• Subtitles.int (for subtitles)