Skip to main content

Playable Localisation

It is recommended that you localise your playable ad experiences to match your audience. This can increase engagement and therefore performance.

In order to ensure you are using the correct language in your playable, there are two possible approaches.

  1. Create multiple versions of your playable, each for a different language.
    • Advantage: Immediately see how the translated version of your playable looks without needing to test it via uploading to Playground and loading the preview on a device set to different languages.
    • Disadvantage: Changes to your playable version(s) in playground will have to manually reapplied onto to each separate language versions.
  2. Change the language at runtime by making use of our GetPreferredLanguage API.
  • Advantage: Only need one playable version as the text will dynamically localise itself.
  • Disadvantage: You will need to setup your text in Scriptable Objects to make use of it, as we don't currently support reading from json files.

In order to do this, you must ensure that your Unity scene and therefore playable ad contain the correct fonts and alphabets according to the language you wish to use.

There are two options for doing this.

Supporting one language per version#

Changing fonts in Luna Playground#

You may use the LunaPlaygroundAsset Attribute to change your playable font (.ttf) via the Luna Playground interface.

This allows you to reduce the overall size of the playable, as only one font will be included in any given version.

  1. After you have uploaded your build to Luna Playground, navigate to the playable editor.
  2. Find the font object in the left hand side menu.
  3. Click the empty asset space (grey bar) to open the Font upload dialogue.
images-small
  1. The Font upload dialogue will now be presented. From here you can upload a .ttf file, and also set a custom alphabet for the given language.
images-small

The default alphabet is English, including additional characters. The default font size is 64 (this is related to the glyph size of the font atlas, not the text size).

Including multiple fonts in your Unity Project#

If you would like to manage your fonts and localisation in Unity, then you can include multiple fonts in the project and implement logic to switch between them as needed.

Please note that including multiple fonts can increase the final size of the playable.
  1. In your game, you should implement logic which allows you to change between fonts/languages in Luna Playground. For example:
  • An enum which is used to control the font/alphabet in use.
  • An integer which controls a number of languages.
  • A boolean which turns on/off a specific font override.

You will need to make sure that your font propagates through all Text components in your game.

  1. Once you have implemented your logic and included the necessary font files, you will need to set the alphabet for each font.
    Navigate to the Font tab (Luna Playable Window > Assets > Fonts) and select the font, inputting the alphabet of your choice.
images-medium

As textures will be created from these characters, it is recommended that you only include the letters/symbols which will be used in the playable.
  1. Test your implementation, and upload to Luna Playground.

Changing Playable text based on device language#

GetPreferredLanguage API#

In order to make use of this API you will need to make use of the GetPreferredLanguage() API, which returns a string language code (e.g. "en-GB" for UK English) based on the device settings. Once you have read this value, you can use a Scriptable Object (SO) to manage the strings which are used for each text item in your playable.

Note: This API works in Luna, not in Unity. To avoid errors in Unity be sure to preprocess the line where you are using it.

#if UNITY_LUNA
lang = Luna.Unity.Playable.GetPreferredLanguage();
#endif

This will return a code in a string format e.g.: "en-gb" for UK English, "fr-fr" for French, "it-it" for Italian.

Language code casing can differ depending upon the device being used. To avoid problems with this convert the string code to lower case.

You can use a simple switch statement to determine the language..

images-large

Once you know the language of the device where your playable is running, you can use this to load the correct content into your text objects.

We also have an example project on our Luna Community Github showcasing the previously described method of implementing localisation using this API.