https://github.com/applanga/sdk-unity
With the Applanga Unity Localization SDK you can automate the Unity game translation process. You do not need to convert text files to excel or xliff. Once the sdk is integrated you can translate your Unity game over the air and manage all the strings in the dashboard. Unity game localization has never been easier!
https://github.com/applanga/sdk-unity
applanga game gamedev language localisation localization localization-tool screenshot screenshot-testing screenshots sdk translation unity unity-game unity-language-mapping unity3d webgl
Last synced: 12 months ago
JSON representation
With the Applanga Unity Localization SDK you can automate the Unity game translation process. You do not need to convert text files to excel or xliff. Once the sdk is integrated you can translate your Unity game over the air and manage all the strings in the dashboard. Unity game localization has never been easier!
- Host: GitHub
- URL: https://github.com/applanga/sdk-unity
- Owner: applanga
- Created: 2017-01-30T13:14:54.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2025-05-22T13:51:54.000Z (about 1 year ago)
- Last Synced: 2025-05-22T15:06:44.330Z (about 1 year ago)
- Topics: applanga, game, gamedev, language, localisation, localization, localization-tool, screenshot, screenshot-testing, screenshots, sdk, translation, unity, unity-game, unity-language-mapping, unity3d, webgl
- Homepage: https://www.applanga.com
- Size: 144 MB
- Stars: 6
- Watchers: 8
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Applanga SDK for Unity
***
*Version:* 2.0.96
*Website:*
*Changelog:*
***
## Table of Contents
1. [Installation](#installation)
2. [Configuration](#configuration)
3. [Usage](#usage)
4. [Optional settings](#optional-settings)
5. [Unity Language mapping](#unity-language-mapping)
## Installation
1. Download and import the ***[Applanga.unitypackage](https://github.com/applanga/sdk-unity/raw/master/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](https://docs.unity3d.com/ScriptReference/MonoBehaviour.Awake.html) 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)
```csharp
Applanga.GetString("APPLANGA_ID", "DEFAULT_VALUE")
```
- **Synchronization:** When you start a scene that includes the Applanga Object it initializes on [Awake](https://docs.unity3d.com/ScriptReference/MonoBehaviour.Awake.html) 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.
```csharp
// 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](https://www.applanga.com/docs/translation-management-dashboard/draft_on-device-testing). 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**
```csharp
using ApplangaSDK;
using ApplangaSDK.Unity;
```
Should be added to any script that needs to call Applanga methods.
6.2 **Strings**
```csharp
// get a translated string for the current device locale
Applanga.GetString("APPLANGA_ID", "DEFAULT_VALUE");
```
6.3 **Arguments**
```csharp
// 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**
```csharp
// if you pass a Dictionary you can get a translated string
// with named arguments being inserted. %{someArg} %{anotherArg} etc.
Dictionary arg = new Dictionary()
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**
```csharp
// get a string in the given quantity
Applanga.GetQuantityString("APPLANGA_ID", "DEFAULT_VALUE", quantity);
```
Available pluralization rules:
```csharp
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 ](http://www.unicode.org/cldr/charts/latest/supplemental/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](https://docs.unity3d.com/ScriptReference/MonoBehaviour.Awake.html).
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:
```csharp
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](https://applanga.com/docs#groups)) and languages call:
```csharp
List groups = new List();
groups.Add("GroupA");
groups.Add("GroupB");
List languages = new List();
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:
```csharp
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:
```csharp
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](https://www.applanga.com/docs/translation-management-dashboard/draft_on-device-testing)) 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. If you are using branching, you can also change the branch at this point if you wish. 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:
```csharp
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](https://applanga.com/docs#manage_tags) and here: [Uploading screenshots](https://applanga.com/docs#uploading_screenshots).
11.1 **Make screenshots manually**
To manually make a screenshot you first have to set your app into [draft mode](https://www.applanga.com/docs/translation-management-dashboard/draft_on-device-testing).
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](https://applanga.com/docs#manage_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:
```csharp
Applanga.SetScreenshotMenuVisible (true);
```
11.3 **Make screenshots programmatically**
To create a screenshot programmatically you call the following function:
```csharp
List applangaIDs = new List{"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.96 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](https://www.applanga.com/docs/advanced-features/branching).
## 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**