Applanga SDK for Unity

---

Version: 2.0.94

Website: https://www.applanga.com

Changelog: https://www.applanga.com/changelog/unity

---

Table of Contents

1. Installation
2. Configuration
3. Usage
4. Optional settings
5. Unity Language mapping

Installation

1. Download and import the Applanga.unitypackage. A new menu item labeled Applanga will appear in the editor.
2. You can always get the latest version by clicking Applanga -> Update SDK.

Configuration

1. Download the Applanga Settings File for your project from the Applanga Project overview in the dashboard by clicking the [Prepare Release] button and then clicking [Get Settings File].
2. Add the Applanga Settings File to your Resources folder. The file extension will be automatically changed to '.applanga.bytes'. This will happen when adding the file as an asset or when executing the next step.
3. Select Applanga -> Initialize -> For Sqlite to use the default Sqlite database implementation or Applanga -> Initialize -> For In-Memory DB to use an in-memory database implementation and the Applanga object will be added to your scene. This should be done at least on the first scene that your game loads. The Applanga object is set to not be destroyed on scene change.
4. Now, if you start your game you should see a log message that confirms that Applanga was initialized or a warning in case of a missing settings file.

---

KNOWN ISSUE: If you initialized for Sqlite and use the scripting Runtime Version 4.0 instead of 3.5 you need to manually remove the file Applanga/Internal/Libs/System.Data.dll (This will be done automatically with the next update).

---

Usage

Basic:

• UI: Select Applanga -> AutoTranslate Scene to attach the Applanga AutoTranslate Component to all Objects with a UI.Text Component and all TextMeshes in the current openend scene and to autogenerate Applanga ID's for them. All GameObjects that have the AutoTranslate Component attached get translated when they get Awake with the current cached translation state and whenever the Applanga SDK retrieves new updated translations. (see section 5. Automated UI Localization for more details)

• Scripts: Use the following code to retrieve a localized string programmatically. *(see section 4. Script Localization for more details)

  Applanga.GetString("APPLANGA_ID", "DEFAULT_VALUE")

• Synchronization: When you start a scene that includes the Applanga Object it initializes on Awake and synchronizes the local string data with the Applanga dashboard. If you press play from within the Editor, built your game as a Development Build or if Draft Mode is activated then all texts that you supply to Applanga.GetString and AutoTranslate(able) Components will also be uploaded to the dashboard after they are activated and if the IDs do not yet exist or if they have empty values.

Extended:

1. To get notified after the localization updates completes (e.g. to show a LoadingScreen at beginning of your App) set a callback event on the First Update Callback Event of the Applanga gameobject. The event function should take a bool as parameter, which indicates if the update was successful.

   // example event function
   public void ApplangaCallbackDelegate (bool success) {
   		...
   }

2. The Settings field allows you to specify various optional settings as name/value pairs (see section Optional settings).

3. The Editor Draft Mode checkbox allows you to directly activate or deactivate the Draft Mode. It will be ignored outside of the editor.

4. To use Applanga in a WebGL project the Use Memory DB checkbox wich allows you to switch to an In-memory DB implementation. Please see In-memory Database under Optional Settings for more Information.

5. If you plan to deploy to the WebGL platform, please see In-memory Database under Optional Settings for more Information.

6. Script Localization

   To load a string for a specific ID in the current language, use the functions described in this section. Note that if the ID you requested does not exist, the default value will be returned and the string may be created in the dashboard.

   6.1 Setup

   using ApplangaSDK;
   using ApplangaSDK.Unity;

   Should be added to any script that needs to call Applanga methods.

   6.2 Strings

   // get a translated string for the current device locale
   Applanga.GetString("APPLANGA_ID", "DEFAULT_VALUE");

   6.3 Arguments

   // get a translated string with formatted arguments
   // using the default c# string format parameters {0}, {1}, {2} etc.
   // @see https://msdn.microsoft.com/en-us/library/system.string.format(v=vs.110).aspx
   Applanga.GetString("APPLANGA_ID", "DEFAULT_VALUE", "arg1", "arg2", "arg3");        

   6.4 Named Arguments

   // if you pass a Dictionary<string, string> you can get a translated string
   // with named arguments being inserted. %{someArg} %{anotherArg} etc.
   Dictionary<string, string> arg = new Dictionary<string, string>()
   args.Add("someArg","awesome");
   args.Add("anotherArg","crazy");
   Applanga.GetString("APPLANGA_ID", "DEFAULT_VALUE", args);

   Example:

   APPLANGA_ID = "This value of the argument called someArg is %{someArg} and the value of anotherArg is %{anotherArg}. You can reuse arguments multiple times in your text, which is %{someArg}, %{anotherArg} and %{someArg}."

   gets converted to:

   "The value of the argument called someArg is awesome and the value of anotherArg is crazy. You can reuse arguments multiple times in your text, which is awesome, crazy and awesome."

   6.5 Pluralization

   // get a string in the given quantity
   Applanga.GetQuantityString("APPLANGA_ID", "DEFAULT_VALUE", quantity);

   Available pluralization rules:

   Zero,
   One,
   Two,
   Few,
   Many,
   Other

   You specify the quantity (int) as the last parameter and Applanga will pick the best pluralization rule based on: http://unicode.org/.../language_plural_rules.html

   In the dashboard you create a pluralized ID by appending the Pluralization rule to your ID in the following format: [zero], [one],[two],[few],[many], [other].

   So the zero pluralized ID for "APPLANGA_ID" is "APPLANGA_ID[zero]".

   If uploading strings is enabled and you call Applanga.GetQuantityString() with a quantity, Applanga will create the corresponding pluralized ID for the supplied default value.

7. Automated UI Localization

   You can add the AutoTranslate script to any UI.Text component or TextMesh component to have the text automatically translated on Awake.

   If you want to localize all supported objects in the scene you can click Applanga -> AutoTranslate Scene and AutoTranslate components will be attached to all supported text objects. All AutoTranslate components will update their text values after a successful update call or a successful language change.

   If you do not want to use the automatically generated IDs you can override them in the AutoTranslate component.

   Note: On Input Fields, AutoTranslate components will only be attached to the placeholder Text component and the Input Field itself will not be translated.

   To only translate a single object or a prefab click Applanga->AutoTranslate selected. This will add the AutoTranslate component to that object and generate an Applanga_ID based on the scene name and the objects hierarchy.

   If you would like a text field to be ignored by the Autotranslate feature, then you can attach the DoNotTranslate component.

   If you would still like that text element to be included in screenshots uploaded to the applanga dashboard you can add any applanga keys you like in the DoNotTranslate AdditionalScreenshotIds string array in the inspector.

8. Update Content

   To trigger an update call:

   Applanga.Update (  new ApplangaCallbackDelegate((bool success) => {
   		//enter code to be called when update is complete   
   }));

   This will request the base language along with the long (e.g. "en_US") and short (e.g. "en") versions of the device's current language. If you are using groups, be aware that this will only update the main group.

   To trigger an update for a specific set of groups (see groups) and languages call:

   List<string> groups = new List<string>();
   groups.Add("GroupA");
   groups.Add("GroupB");
   List<string> languages = new List<string>();
   languages.Add("en");
   languages.Add("de");
   languages.Add("fr_CA");
   
   Applanga.Update(groups, languages, new ApplangaCallbackDelegate((bool success) => {
   		//enter code to be called when update is complete    
   }));

9. Change Language

   You can change your app's language at runtime using the following call:

   bool success = Applanga.SetLanguage(language);

   language must be the iso string of a language that has been added in the dashboard. It does not have to correspond to any Unity system language. The return value will be true if the language could be set or if it already was the current language, otherwise it will be false. The newly set language will be saved. To reset it back to the device language call:

   Applanga.SetLanguage(null);

   The language parameter is expected in the format [language]-[region] or [language]_[region] with the region being optional. Examples: "fr_CA", "en-us", "de".

   If you have problems switching to a specific language you can update your settings file or specifically request that language within an update content call (see section 7. Update Content). You can also specify the language as a default language to have it requested on each update call (see section Optional settings).

10. Draft Mode To activate draft mode (see the dashboard docu on Draft Mode) on any touch devices you have to hold four fingers down on the screen for four seconds and enter the draft mode key in the Dialog. In the Editor you can tick or untick the Editor Draft Mode check box on the Applanga object to activate or deactivate the draft mode directly, this will only have an effect inside the editor.

    10.1 Display draft mode activation dialog programmatically

    You have the option to open the draft mode activation dialog programmatically:

    Applanga.SetDraftModeActivationDialogVisible (true);

11. Screenshots for Translation Context The Applanga SDK offers the functionality to upload screenshots of your app, while collecting meta data such as the current language, resolution and the Applanga translated strings that are visible, including their positions. Each screenshot will be assigned to a tag. A tag may have multiple screenshots with differing core meta data: language, app version, device, plattform, OS and resolution.

    You can read more here: Manage Tags and here: Uploading screenshots.

    11.1 Make screenshots manually

    To manually make a screenshot you first have to set your app into draft mode.

    With your app in draft mode, all you have to do is to make a two finger swipe downwards. This will show the screenshot menu and load a list of tags. You can also toggle this menu by clicking on the 'Show/Hide Screenshot menu' button in the Inspector window. You will need to select the Applanga gameobject in order to see this Inspector window.

    You can now choose a tag and press capture screenshot to capture and upload a screenshot including all meta data for the currently visible screen and assign it to the selected tag. Tags have to be created in the dashboard before they are available in the screenshot menu.

    11.2 Display screenshot menu programmatically

    You have the option to open the screenshot menu programmatically, this also requires the app to be in draft mode:

    Applanga.SetScreenshotMenuVisible (true);

    11.3 Make screenshots programmatically

    To create a screenshot programmatically you call the following function:

    List<string> applangaIDs = new List<string>{"Start","Settings","Quit"};
    Applanga.CaptureScreenshot("MainMenu", applangaIDs);

    The Applanga SDK tries to find all IDs on the screen but you can pass additional IDs in the applangaIDs parameter.

Optional settings

Default groups and languages

You can specify a set of default groups and languages on the Applanga object, which will be updated on every Applanga.update() or Applanga.updateGroups() call. These groups and languages will be added in addition to values that you specifiy by code.

1. Specify default groups Click on Settings on the Applanga object and enter 1 or 2 in the Size field, depending on if you intend to add groups and languages or only groups. Enter ApplangaUpdateGroups into the Name field and a comma seperated list of groups into the Value field (e.G., "GroupA, GroupB").

2. Specify default languages Click on Settings on the Applanga object and enter 1 or 2 in the Size field, depending on if you intend to add groups and languages or only languages. Enter ApplangaUpdateLanguages into the Name field and a comma seperated list of languages corresponding to the applanga dashboard language isos, into the Value field (e.G., "fr, de_AT").

Screenshot Menu Hotkeys

You also have the possibility to set a number of keys as a Hotkey combination to activate the screenshot menu (requires the draft mode to be active). Select the Applanga gameobject then find Screenshot Menu Activation Keys. Here you can choose the number of Keys you want to use and pick the actual Keys you want to use. The screenshot menu will then be toggled at Runtime if all keys are pressed simultaneously and the draft mode is active.

In-memory Database

You have the option to use an In-memory Database by checking the checkbox Use Memory DB on the Applanga gameobject. Or by using Applanga -> Initialize -> For In-Memory DB. This Database variant will load all Data for used languages into memory and only persist them after successful updates. It will automatically be used if you build for the WebGL platform, due to platform retsrictions.

Note: For the memory DB to load the initial data from the settingsfile, it's necessary to convert the data: click Applanga -> Initialize -> For In-Memory DB. This is required when deploying for WebGL or activating the Use Memory DB option. It will also remove Sqlite library dependencies.

If you want to deploy for another platform and use Sqlite you have to execute Applanga -> Initialize -> For Sqlite.

Disable Update On Start

If you wish to stop the sdk from automatically updating your strings on app launch you can set the following to the settings on the applanga object.

ApplangaInitialUpdate
false

You will still be able to call Applanga.Update() at any time to update your strings manually

Disable Draft Mode

If you wish to create a build that cannot enable draft mode at any time, you can include the following setting to your Applanga object.

ApplangaDraftModeEnabled
false

Automatic Applanga Settings File Update

In case your app's user has no internet connection, new translation updates can't be fetched, so the Applanga SDK falls back to the last locally cached version. If the app was started for the first time, there are no strings locally cached yet so Applanga SDK falls back to the Applanga Settings File which contains all strings from the moment it was generated, downloaded and integrated into your app before release.

To minimize the manual effort of updating the Applanga Settings File, we created a task which triggers the Applanga Settings File generation if changes were made and replace the old one with the new one in your app.

Be aware that the task will not fail if there is no internet connection, to be able to develop offline. In this case, a warning is printed. To activate the Automatic Settings File Update, toggle the "Applanga/Auto Update Settings File on Build" menu item at the top of your unity window.

To make sure that the script is running and to see when it does or doesnt update, check the unity logs after a build. There you will find logs for each update step.

If the file is update successfully you shoudl see the log "Settingsfile updated!". If it is already up to date you will see the log "Settingsfile up-to-date".

You can also trigger a settingd file update manually with the "Applanga/Update Settingd File Now" Menu item.

Branching

If your project is a branching project use at least SDK version 2.0.94 and update your settings file. The settings file defines the default branch for your current app. This branch is used on app start and for update calls. To be sure branching is working look for the log line: Branching is enabled.

To learn more about branching please have a look here.

Unity Language mapping

Applanga detects the system language using Application.systemLanguage and maps it to Applanga Iso strings following this table:

• SystemLanguage.Afrikaans -> af
• SystemLanguage.Arabic -> ar
• SystemLanguage.Basque -> eu
• SystemLanguage.Belarusian -> be
• SystemLanguage.Bulgarian -> bg
• SystemLanguage.Catalan -> ca
• SystemLanguage.Chinese -> zh
• SystemLanguage.ChineseSimplified -> zh-Hans
• SystemLanguage.ChineseTraditional -> zh-Hant
• SystemLanguage.Czech -> cs
• SystemLanguage.Danish -> da
• SystemLanguage.Dutch -> nl
• SystemLanguage.English -> en
• SystemLanguage.Estonian -> et
• SystemLanguage.Faroese -> fo
• SystemLanguage.Finnish -> fi
• SystemLanguage.French -> fr
• SystemLanguage.German -> de
• SystemLanguage.Greek -> el
• SystemLanguage.Hebrew -> he
• SystemLanguage.Hungarian -> hu
• SystemLanguage.Icelandic -> is
• SystemLanguage.Indonesian -> id
• SystemLanguage.Italian -> it
• SystemLanguage.Japanese -> ja
• SystemLanguage.Korean -> ko
• SystemLanguage.Latvian -> lv
• SystemLanguage.Lithuanian -> lt
• SystemLanguage.Norwegian -> no
• SystemLanguage.Polish -> pl
• SystemLanguage.Portuguese -> pt
• SystemLanguage.Romanian -> ro
• SystemLanguage.Russian -> ru
• SystemLanguage.SerboCroatian -> sr
• SystemLanguage.Slovak -> sk
• SystemLanguage.Slovenian -> sl
• SystemLanguage.Spanish -> es
• SystemLanguage.Swedish -> sv
• SystemLanguage.Thai -> th
• SystemLanguage.Turkish -> tr
• SystemLanguage.Ukrainian -> uk
• SystemLanguage.Vietnamese -> vi