IsDatabaseForLocalizing

Introduction

Many games require support in multiple languages. The IsDatabaseForLocalizing property simplifies the creation of games which can run in multiple languages. When a spreadsheet is marked as IsDatabaseForLocalizing, there are a number of things which Glue does:

  1. It populates the LocalizationManager with the database when it is loaded
  2. It assumes that all Text objects in Scenes (.scnx files) loaded through Glue use string IDs from the localization database and performs translation in generated code.
  3. It assumes that all non-animation string variables in Glue use string IDs from the localization database and performs translation in generated code.

Because of this behavior, creating a game that supports localization requires very little code.

Creating a Localization Database

The first step is to create a spreadsheet file that will serve as a localization database. To do this:

  1. Right-click on “Global Content Files”. Since most of your game will use text you will want to put the spreadsheet file under “Global Content Files”
  2. Select Add File->New File
  3. Select Spreadsheet (.csv) as the file type
  4. Enter the name “LocalizationDatabase” for your new file
  5. Click OK

The next step is to tell Glue that this file is a database for localization. To do this:

  1. Select the newly-created LocalizationDatabase file
  2. Change IsDatabaseForLocalizing to “True”IsDatabaseForLocalization.png
  3. You will get a popup notifying you that all code needs to be regenerated. Click OK, close, then re-open Glue to force a full code regeneration.OutOfDateCode.png

Modifying the Spreadsheet

The next step is to begin filling out the database. To do this:

  1. Double-click the file to open it in a spreadsheet editing program such as Excel or Open Office
  2. Change the top-left cell to read “ID (required)”. Make sure “required” is not capitalized.
  3. Change the first row in the second column to say “English”
  4. Change the first row in the third column to say “Spanish”. You can continually add columns for any language you may want to support. LanguagesInExcel.png
  5. Enter a string ID under the “ID” column. You may want to use a particular prefix to differentiate between string IDs and actual text – this can help you spot bugs in development. For this tutorial, I’ll use “T_” before IDs. Therefore, I’ll enter “T_Hello” for my first string.
  6. Enter the English and Spanish versions of this stringStringIdAndTranslation.png
  7. Save the spreasheet

Viewing translation in game

Next we’ll add a Text object to the game that will use this translation:

  1. Add a .scnx file to a Screen
  2. Open the .scnx
  3. Add a Text object
  4. Change the Text’s “DisplayText” to “T_Hello” (or whatever string ID you’d like to match)HelloTextInSE.png

Setting the Language

Before any localization can happen, you must tell the game which language to use. By default, the LocalizationManager will use index 0 as its default language. This is reserved as an “untranslated” language, which allows you to view string IDs in game. The first language (which is English in our case) begins at index 1. Therefore, to have your database translated, you must set the language index. To do this:

  1. Open Game1.cs (or whatever your Game class is named)
  2. Find “GlobalContent.Initialize();” and add the following after it:

Be sure that this is set before ScreenManager.Start is called, or else the Screen will be initialized prior to the language being set.

Viewing your localized text

Once you have set the language you can run the game and your Text object should be localized:

HelloTranslated.png

Manually Translating Text

Glue’s automatic translation of text is convenient, but you may also need to perform translation based off of game logic. To do this, you can use the LocalizationManager’s Translate method. For example, if you wanted to translate the string ID “T_Tutorial1” you could do so as follows:

You could then use translatedTutorialString in your game.

Adding Variables to Translated Text

So far we’ve covered static translations. Of course, you may want to have variables embedded in your text. The LocalizationManager supports this through a syntax that is very similar to the string.Format method. To support variables in your text:

  1. Add an entry to your database spreadsheet using the { and } characters surrounding the variable index. For example, to inform the player of how many goals are left, you might enter: “You have completed {0} goals and you have {1} goals left.”TranslatedTextWithVariables.png
  2. In your code you can use the Translate overload which takes arguments to “format” the string. For example, your code may look like this: