Localisation


Game Framework lets you easily target a global audience by providing out of the box support for localisation and includes translations into several common languages.

Localisation Setup

The file \FlipwebApps\GameFramework\Resources\Default\Localisation.csv contains a set of text key’s and their corresponding translation in various languages (please let us know if you can help translate to others).

Localisation File

You should avoid editing the above file directly as changes will be overwritten when you install an update to the framework. Instead create (or copy) your own separate \Resources\Localisation.csv file and add your entries here. At run-time this will be appended to the default localisation file so you can add text specific to you game or override key’s and values from the default localisation file.

Important Note: The localisation file must be in UTF-8 format with BOM, which is not the default saved by Excel. If you find that non-English characters are not showing up then try using notepad++ and select the Encoding | Convert to UTF-8-BOM option before saving your localisation file back out again. Also not all fonts support all characters so if you are missing characters in your UI verify in the inspector whether the values are showing correctly there.

Through code we can access all localisation languages and keys as shown later, however it might be that for your game you only want to support a sub set of these languages (e.g. if you have a lot of custom text that you haven’t yet translated). You should let the framework know what languages you intend to support bu adding these to the GameManager component.

Accessing Localised Text

You can use the LocaliseText class from code to Get and Format localisation strings.

As the example above shows you can use format strings for your localisation values and use the LocaliseText.Format method to access and automatically format in parameters. These follow the standard .Net format string syntax.

To display localised text in a GUI you can use the LocaliseText component. Just add this to a gameobject containing a Unity UI Text component to set the value automatically based upon the specified key.

LocaliseText

Localised Images

The LocaliseImage component can be attached to a gameobject that contains a UI Image component and allows for setting localisation specific images.

localiseimage

GameItems also allow for associating localised images and prefabs and include several components for working with these.

Setting The Langauge

The default language Game Framework uses is matched against the device settings with a fallback if that language isn’t present in the localisation file. There are several ways that you can change the language.

If you have entered languages in GameManager as mentioned above the the Settings Window will allow you to chose the language to use in game.

LocalisationSettingsWindow

The OnButtonClickSetLanguage component can also be used to change to a particular language. It can be added to a gameobject that contains a UI Button and will automatically hook up the button click event to change to a particular language. One use for this might be if you have buttons with flag images to set the different languages.

You may also set the language directly through code by assigning directly to the LocaliseText.Language property.

Whenever the localisation changes a LocalisationChangedMessage is sent out via the messaging system. This allows any components that you write to easily and automatically react to localisation changes and if necessary update displayed values, text or otherwise.

To conditionally display things based upon the current language, you can use the EnableIfLanguage component to conditionally display gameobjects based upon whether the currently used language matches a specified value.

If you have the extras bundle then there is a sample that demonstrates all of the above in the GameFrameworkTutorials\Localisation folder. You can also see a YouTube video walking through the construction of this sample.

Use in Other Components

Many other components that show or work with text will allow you to provide a localisation key that should be used to look up the text for the current language. Many of these allow you to specify formatting parameters (see above) that will be substituted with specific values. The tooltips for these components will identify what parameters you can use. In the below image, the text for our localisation key “Game.TotalCoins” might contain “{0}”, “Coins: {0}” or some other similar string.

UseInOtherComponents

See also

If you have any thoughts or suggestions on improvements or additions to the Localisation features then please let us know!