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 creatives, each for a different language.

    • Advantage: Immediately see how the translated creative looks without needing to test it via uploading to Unity Playworks and loading the preview on a device set to different languages.
    • Disadvantage: Changes to your playable creative(s) in Unity Playworks will have to manually reapplied onto to each separate language creatives.

  2. Change the language at runtime by making use of our GetPreferredLanguage API.

  • Advantage: Only need one playable creative as the text will dynamically localise itself.
  • Disadvantage: You will need to setup Newtonsoft.Json in order to read 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 creative​

Changing fonts in Unity Playworks​

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

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

  1. After you have uploaded your build to Unity Playworks, 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.

note

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 Unity Playworks. 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 (Playworks Plugin Window > Assets > Fonts) and select the font, inputting the alphabet of your choice.

images-medium

note

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 Unity Playworks.

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.

note

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.

info

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