Revision as of 21:34, 7 November 2012 by HE-Nate (Talk | contribs)
Jump to: navigation, search



Game localization is the process whereby a product is modified to be suitable for other distinct markets through the process of translation and cultural adaptation of its content. Localization includes (but is not limited to):

Going hand-in-hand with localization is the concept of internationalization or globalization which is the process whereby a product is designed to be easy to localize by hiding or removing cultural or language specific content through planning and game design.

HeroEngine's Localization system provides a fully internationalized interface for management of translated text strings. The Localization system has two operating modes:

  1. In DEV mode (while the game is under development), multiple translations of game-specific text phrases are prepared and stored in the repository. Phrases are identified by numeric string IDs
  2. In RT mode (when the game is being played), phrases are retrieved from the repository by string ID. You can switch to a different language simply by changing the current locale

Be aware that the Localization system provides only a small part of what is necessary for the proper internationalization of your game... as you too are responsible for developing your game's systems to support internationalization.

On this page and the pages it references you will find an overview of HeroEngine's Localization system as well as a variety of topics addressing some of the issues. This documentation is not intended to explain all of the issues in the problem space of internationalization and localization.

What Problem(s) Does HeroEngine Localization Solve?

What Problem(s) Does HeroEngine Localization Not Solve?

Suggested Reading

For background in the issues of localization, we recommend books such as: Game Localization Handbook

Globalization Step by Step” provides a good overview of the factors involved in internationalization.

Recommended Usage

DEV Mode

The DEV-mode Localization system is highly customizable, and there are many different ways in which game developers can use it. However, the Localization Table Editor will meet the needs of most game developers.

See the Example below and/or the Localization Table Editor page for further instructions.

RT Mode

When the game is being played, retrieve localized strings using the $LOCALIZE system node

See the Example below and/or the $LOCALIZE system node page for further instructions.

Recommended Usage Example

Let's say that we have a quest game whose GUI interface includes a window that displays the name and description of a quest ...
Localize example1 en.png

... and that we'd like to localize this window so that we can easily change the language at runtime:  
Localize example1 ru.png

We can accomplish this with the following steps: 

  1. Use theLocalization Table Editor to create a localized string database containing the desired translations.
  2. Use HeroBlade to create the quest window. Include GUILabel controls for the quest name and description.
  3. Write the HSL for the quest window, using the $LOCALIZE system node to retrieve the quest name and description in the desired language.

The next two sections provide detailed step-by-step instructions for this example (except for the details of creating the quest window: see the "GUI Window Tutorial" for that).

Create Localized String Database with Localization Table Editor

To open the Localization Table Editor in HeroBlade

  1. Click on the Viewport window to ensure that it is selected. 
  2. Hit the F5 key to bring up the Utilities Interface window. 
  3. Select the Tools tab, then click on Localization Table Editor.

   *************** NATE: PLEASE FILL THIS IN ***************

Write RT-Mode HSL  

Finally, we can use the $LOCALIZE system node to query the string tables at runtime and customize the GUI for a specific language:

//$QUEST system node
method constructQuestWindow(questSpec as NodeRef of class SomeGameQuestSpecClass, locale as String) as noderef of class SomeGameQuestWindowClass
  questWindow as noderef of class SomeGameQuestWindowClass = CreateNodeFromPrototype("SomeGameQuestWindowClass")
  questWindow.build = true
  questWindow.initializeQuestWindow(questSpec, POSITION_DEFAULT, PARENT_NONE)
  questWindow.updateQuestWindowGUI(locale) // "locale" is the locale name of the language in which the quest window will be displayed

method initializeQuestWindow(questSpec as NodeRef of class SomeGameQuestSpecClass, position as enum SomeGameWindowPositionEnum, parent as noderef of class SomeGameWindowClass)
method updateQuestWindowGUI(locale as String)
  questSpec as NodeRef of class SomeGameQuestSpecClass = me.getMyQuestWindowQuestSpec()
  localizeRequestID as ID
  // set the language in which we want the localized string to be retrieved
  if (questSpec.LOC_SetCurrentLocale(locale) != true)
    // This is a fatal error. The most likely causes are that "locale" is not a valid locale name, or that "locale" is not in your localized string database.
    // The LOC_OnRTError() callback will be invoked, with a detailed error message.
  //request quest name localized string
  questNameStringID as string = questSpec.getQuestNameStringID() // this is the string ID assigned to the quest name by the Localization Table Editor. You must initialize it in the quest spec.
  localizeRequestID = $LOCALIZE._GetLocalizedStringValueAsync(me, questNameStringID) // start asynchronous retrieval of localized string
  me.questWindowAddPendingLocalizedStringUpdateRequest(localizeRequestID, me.getQuestWindowNameLabel()) // link the asynchronous request ID to the GUI control which will be updated by the string and save it
  //request quest description localized string
  questDescriptionStringID as string = questSpec.getQuestDescriptionStringID() 
  localizeRequestID = $LOCALIZE._GetLocalizedStringValueAsync(me, questSpec.getQuestDescriptionStringID())
  me.questWindowAddPendingLocalizedStringUpdateRequest(localizeRequestID, me.getQuestWindowDescriptionLabel())
method _GotLocalizedStringValueAsync( request_id as ID, localized_string_number as Integer, localized_string_value as String )
  //If the string we've just received fulfills the request with ID 'request_id', process it and remove it from our pending list
  if me.questWindowIsWaitingForLocalizedString(request_id)
    me.questWindowProcessPendingLocalizedStringUpdateRequest(request_id, localized_string_value)
method questWindowProcessPendingLocalizedStringUpdateRequest(request_id as ID, localized_string_value as String)
  //Get the label we want to update, then update its text value
  labelToUpdate as NodeRef of class _GUILabel = me.questWindowGetLabelForLocalizedStringRequest(request_id)
  labelToUpdate.text = localized_string_value
Now, in order to create a quest window whose text will match the locality of the player, we need only to call $QUEST.constructQuestWindow(...) from an HSL script with the appropriate quest spec and locale.

Advanced Usage

IF Studios recommends the Localization Table Editor for most game developers. However, it does make some default assumptions that might not be suitable for all developers, including:

The low-level Localization system concept of operations is:

  1. DEV-mode Localization external functions are used to either create a new localized string database or to load an existiing localized string database from the repository.
  2. DEV-mode Localization external functions are used to edit the localized string database. This includes the creation of new localized strings and the editing and deletion of existing localized strings.
  3. When the DEV-mode localized string database is ready for in-game use, the DEV-mode Localization runtime database generation external functions are used to generate an RT-mode localized string database and upload it to the repository. This is the only write access to the RT-mode localized string database which is provided by the Localization external functions.
  4. When the game is played, the RT-mode Localization external functions are used to load an RT-mode localized string database, select a language in which localized strings are to be retrieved, and retrieve localized strings.

Import of Localization Files


Translation String Table

$TABLE_NAME (tab) $STRING_ID (tab) $STRING[base] (tab) $STRING[context] (tab) $STRING[translator_locale]
$TABLE_NAME (tab) $STRING_ID (tab) $STRING[base] (tab) $STRING[context] (tab) $STRING[translator_locale]
$TABLE_NAME (tab) $STRING_ID (tab) $STRING[base] (tab) $STRING[context] (tab) $STRING[translator_locale]
$TABLE_NAME (tab) $STRING_ID (tab) $STRING[base] (tab) $STRING[context] (tab) $STRING[translator_locale]
$TABLE_NAME (tab) $STRING_ID (tab) $STRING[base] (tab) $STRING[context] (tab) $STRING[translator_locale]

Which would look something like this with real data for a japanese translation of the table:

TABLE (tab) ID (tab) en_US (tab) CONTEXT (tab) ja_JP
GameTable1 (tab) 456 (tab) Hello, World! (tab) A generic programmer greeting used in code samples. (tab) こんにちは、世界!
GameTable1 (tab) 457 (tab) Goodbye, World! (tab) An orthogonal phrase to the classic "Hello, World!" (tab) さようなら、世界!

Asynchronous RT-Mode Localization


Synchronous RT-Mode Localization



Base locale

When a game is being played, the base locale specifies the fallback language in which localized strings are to be retrieved by the RT-mode Localization interface should a translation not be available in the current locale. 

Current locale

When a game is being played, the current locale specifies the preferred language in which localized strings are to be retrieved by the RT-mode Localization interface. 

DEV mode

"DEV mode" refers to operations during game development. The HeroEngine DEV-mode Localization system provides a suite of tools for the import, creation, and editing of localized string databases for use by RT-mode Localization


Locales identify the target culture/language. HeroEngine identifies locales using the same locale names as the host operating system. Locales in table 1 include English as spoken in the US ("en-US"), French ("fr"), Spanish ("es"), Russian ("ru"), Japanese ("ja-JP"), Korean ("ko-KR"), and traditional Chinese ("zh-CN"). 

Localized string

A translation uniquely identified by the combination of a string ID and a locale. For example, in table 1 the localized string "안녕히 가세요" translates the phrase "Goodbye" (string ID 100002) into Korean (locale "ko-KR"). 


The contiguous range of string IDs managed by a universe or string table. Ranges may not include the invalid string ID of zero. 

RT mode

"RT mode" refers to operations while a game is being played (i.e., during the game's runtime). The HeroEngine RT-mode Localization system provides an external function library for efficient retrieval of localized strings from the repository files created by DEV-mode Localization

String ID

A 64 bit signed integer that uniquely identifies a particular phrase. In Table 1, string ID 100001 identifies the phrase "Hello" and string ID 100001 identifies the phrase "Goodbye". Zero is an invalid string ID and negative string IDs are reserved for HeroEngine's use. 

Relationship of String IDs, Locales, and Localized Strings
Table 1. Relationship of String IDs, Locales, and Localized Strings

Localization Data/File Hierarchy  

In both DEV and RT modes, localization data is organized into configurations, universes, and string tables.

Configurations, universes, and DEV-mode string tables all map one-to-one to localization files in the repository. However, RT-mode string tables correspond to multiple repository files.  

File Keys

In both DEV and RT modes, the Localization external functions enforce a rule that one and only one configuration file can be loaded at any time (however, DEV-mode and RT-mode configurations are not the same, so one DEV-mode configuration and one RT-mode configuration can coexist.). 

Both DEV-mode and RT-mode external functions also enforce "hierarchical access": universes cannot be loaded until a configuration that references them has been loaded, and string tables cannot be loaded until a universe that references them has been loaded. Universes and string tables are referenced by random unsigned 64-bit integer "file keys" assigned by the external functions.  Note that file keys are of HSL type "ID".


 Configurations are the highest-level localization data item, and contain an indefinite number of universes. All of the localized strings for a game should be stored in one and only one configuration.


  Universes are the mid-level localization data item, and contain an indefinite number of string tables. 

String Table

String tables are the lowest-level localization data item, and contain an indefinite number of localized strings.

See Also

    How to use HeroBlade's Localization Table Editor to create translation databases.

    For information on the HSL DEV-mode localization system node.

    For information on the HSL RT-mode localization system node.

    Descriptions of the Localization external functions.

    Descriptions of the Localization repository files.

Personal tools