Lean Localization
DOCUMENTATION
What is Lean Localization?
Lean Localization is a lightweight localization asset, allowing you to easily add language-specific text, images, and much more.
How do I use it?
Step 1 - Add Lean Localization
First you need to add the LeanLocalization component to your scene:
Your Hierarchy window should now have a new LeanLocalization GameObject added, and this should be automatically selected for you.
Step 2 - Add Languages
Inside the Lean / Localization / Languages folder, you can see some prefabs for different languages. To add support for one in your project, simply drag and drop this prefab so it becomes a child of your LeanLocalization GameObject. If done correctly, this language will appear in the LeanLocalization component's Languages list.
Step 3 - Add Phrases
To add a phrase, simply type the title of your phrase into the Translations search box, and click the Translations > Add button.
Your new phrase will automatically be added as a child to your LeanLocalization GameObject.
Step 4 - Add Translations
To add a translation, select your LeanPhrase component, and click the Add button next to the language you want to add a translation for.
Inside the phrase translation you can see three settings:
Text - Allows you to set the translated text for that phrase.
Object - Allows you to set the translated object for that phrase (e.g. Texture, Prefab, Sound).
Sprite - Allows you to set the translated sprite for that phrase.
Step 5 - Add Localization Components
Finally, you need to add a localization component to your scene.
Once added, you will see the Phrase Path setting, which you can set the phrase you want to use.
You can also click the List button to quickly see what's available.
Step 6 - Done!
That's it, your game will now automatically update based on your translations!
How do I automatically translate words?
That's it! Your phrase should now have automatically translated from one language (e.g. English) to another (e.g. Spanish).
How do I change language?
There are multiple ways to do this.
In The Editor
Select the GameObject that has the LeanLocalization component, then click the Current Language > List button.
In Game Using UI
Drag and drop the GameObject that has the LeanLocalization component into your event Object field, and select the LeanLocalization.SetCurrentLanguage function.
In Game Using C#
Simply call the Lean.Localization.LeanLocalization.SetCurrentLanguageAll() static method. For example:
Lean.Localization.LeanLocalization.SetCurrentLanguageAll("English");
How do I get a translation from C# code?
If you just want to get translated text, then you can call:
Lean.Localization.LeanLocalization.GetTranslationText("YourPhraseNameHere");
If you want a Unity Object (e.g. Sprite), then you can call:
Lean.Localization.LeanLocalization.GetTranslationObject("YourPhraseNameHere");
How do I add to the language list?
You can find the default languages in the Lean/Localization/Languages folder. To create your own, you can:
You should now see a language prefab. Now you must:
That's it! You can now drag and drop your new language prefab onto the LeanLocalization GameObject in your scene as a child, or drop the prefab into the
LeanLocalization component's Prefabs setting.
How do I localize other components?
To localize more components, simply implement the LeanLocalizedBehavior base class in your own components.
This class has the UpdateTranslation(LeanTranslation translation); method, where the specified translation will be null if it doesn't exist. If it does exist then you can read the translation.Data value, you can then cast this to the required type before use.
Take a look at the code for LeanLocalizedSpriteRenderer to see just how easy this is.
How do I better organize my translations?
The more translations you add to your project, the more difficult Lean Localization can be to use, because the translation name dropdown list will become increasingly long.
To fix this, you can organize your translations into groups.
To do this, simply add forward slashes to your translation names when creating them.
When using a translation name dropdown, this will automatically place MyTranslation into a group called MyGroup.
How do I use prefabs?
If you have many translations or use many scenes then you may want to use prefabs instead of placing everything in the scene.
Step 1
Drag and drop your phrases, CSV loaders, and tokens into your Project window, turning it into a prefab.
Step 2
Delete your prefab instances from the scene.
Step 3
Drag and drop your prefabs (or a root folder they belong to) into the LeanLocalization.Prefabs setting.
Step 4
Done!
Your localizations should now be automatically loaded from prefabs, giving you better performance, and improved organization.
If you have many LeanLocalization components in different scenes, then this may be tedious to do. To fix this you can make your LeanLocalization component itself a prefab too, so you only have to view the prefab itself to trigger the update.
How do I use tokens?
Tokens allow you to find and replace text. For example, if you want to include the player's name inside a localized text field, then the tokens feature allows you to do this.
Step 1 - Create tokens
To create a token you can either:
You've now created a token, where the GameObject name controls the name of the token.
Step 2 - Insert tokens into text
A token can be added using curly braces, like this:
Hi, my name is {NAME}!
Where the token GameObject is called NAME.
Step 3 - Done!
Your translated text should now automatically have any tokens replaced.
You can also change the value of a token in game using the LeanToken.SetValue method.
What are Cultures?
Cultures allow you to associate language codes with language names. For example, English might be associated with en-GB, en-US, etc.
When you start your application the current device language code will be loaded, and the associated language will be chosen.
Why can you only translate Text, Object, and Sprite?
Internally, the LeanPhrase component only stores Text (string) and Object (UnityEngine.Object) types.
Sprites in the Unity project window are stored as children of their source image. This means when you drag and drop a sprite, you're usually dragging and dropping the parent image, which may give you undesired behaviour when you drag it into an Object field.
To avoid any unexpected behaviour, I added the additional Sprite setting, so you can drag and drop the sprite's parent image, and Unity will automatically drop the sprite in.
This issue doesn't occur for most other scenarios, so you can use the Object type for everything else like Mesh, Material, etc.
Is Text Mesh Pro supported?
Yes, if your project contains the TextMeshPro package then it will automatically be supported.
Assets
Here's a list of all my other assets, please check them out!
You can also view this list on my Asset Store page.
Lean Touch
Rapidly develop your game with consistent input across desktop & mobile using Lean Touch. This lightweight asset comes with many modular components, allowing you to customize them to your exact project needs!
Lean Touch+
Lean Touch+ is an extension to the popular Lean Touch asset, adding many more example scenes.
Lean Localization
Lean Localization is a localization library that's designed to be as simple to use as possible for both designers, and programmers.
Lean Pool
Quickly optimize the performance of your games using Lean Pool. Within minutes you can use this lightweight asset to preload, recycle, and limit the spawning of your prefabs.
Lean Transition
Quickly polish your games using Lean Transition. This asset allows you to easily tween or animate almost anything in your game, making it transition smoothly.
Lean GUI
Lean GUI is a colllection of components that extend Unity's GUI system, allowing you to rapidly enhance the user experience (UX) of your game's UI.
Lean GUI Shapes
Lean GUI Shapes allows you to quickly add lines, rounded boxes, polygons, and much more to your GUI!
Lean Texture
Lean Texture allows you quickly modify textures in your project with a range of filters, pack them together into channels, and much more!
Lean Texture+
Lean Texture+ is an extension to Lean Texture, adding many new types of texture modification tools!
CW Orbit
Take your space game to the next level with this collection of 8K background planets. Just drag and drop them in, and enjoy orbiting around them.
Paint in 3D
Paint all your objects using Paint in 3D - both in game, and in editor. All features are optimized with GPU accelerated texture painting, so you can enjoy consistent performance, even if you paint your objects one million times!
FLOW
FLOW allows you to add large scale interactive fluids to your scene - all highly optimized using GPU acceleration.
Destructible 2D
Unlock the full potential of your 2D games using Destructible 2D, this asset allows you to quickly convert all your boring solid sprites into fully destructible ones!
Space Graphics Toolkit
Quickly make the space scene of your dreams using Space Graphics Toolkit. This huge collection of space effects can be customized and combined in any way you like, allowing you to quickly make realistic or fantasy worlds. Each feature has been heavily optimized to run on almost any device and platform.
Space Graphics Planets
Enhance your space scenes using this large pack of high detail volumetric planets. These planets are finished using the powerful planet features from Space Graphics Toolkit (not required).
Volumetric Audio
Unity sounds only emanate from a single point source. This is great for explosions and footsteps, but quite often you need something more advanced. Volumetric Audio is an easy to use package that allows you to define boxes, spheres, capsules, paths, or meshes that sounds can emanate from.
Versions
2.0.0
Changed folder structure to be inside Plugins/CW/LeanLocalization.
Updated inspector code to support third party assets that implement nested inspectors.
1.5.1
Added LeanLocalization.GetFirstCurrentLanguage method.
Renamed LeanLocalization.SaveLanguage setting to SaveLoad.
Added LeanLocalization.SaveLoad = WhenChangedAlt setting.
Fixed LeanLanguageName attribute not showing tooltip text.
Fixed LeanLanguage.CurrentLanguage not loading after save.
Added LeanLanguageCSV.Format = Comma setting.
Added LeanLanguageCSV.Format = Semicolon setting.
Fixed LeanLanguageCSV error.
Fixed LeanLanguageCSV not dirting when clicking Load Now or Clear.
Added Debug demo scene.
Fixed language aliases not registering properly.
Fixed missing class error in .NET 4.x.
1.5.0
Moved main build to Unity 2019.4.12f1.
Added auto translation option to LeanPhrase component.
Moved languages to separate LeanLanguage component and prefabs.
Allowed multiple LeanLocalization instances at once.
Changed LeanLocalization.SaveLanguage to only save when manually modified.
1.3.8
Moved main build to Unity 2018.4.0f1.
Updated documentation.
Added asmdef.
Phrases can now be added from the translation name List dropdown.
Translation sources can now be selected from the translation name List dropdown.
Updated TextMeshPro package structure.
Added TMP_Dropdown support to TextMeshPro package.
1.3.6
Added LeanLocalizedTextMeshPro to TextMeshPro package.
Added LeanLocalizedTextMeshProFont to TextMeshPro package.
Components
ILocalizationHandler
This interface can be implemented by any component that needs to listen for localization changes.
LeanLanguage LeanSource
This contains information about a language, and any of its optional cultures.
string
TranslationCode
The language code used for auto translation.
List<string>
Cultures
This culture names for this language (e.g. en-GB, en-US).
LeanLanguageCSV LeanSource
This component will load localizations from a CSV file. By default they should be in the format:
Phrase Name Here = Translation Here // Optional Comment Here
TextAsset
Source
The text asset that contains all the translations.
FormatType
Format
The format of the CSV data.
See the inspector for examples of what the different formats look like.
string
Language
The language of the translations in the source file.
CacheType
Cache
This allows you to control when the CSV file is loaded or unloaded. The lower down you set this, the lower your app's memory usage will be. However, setting it too low means you can miss translations if you haven't translated absolutely every phrase in every language, so I recommend you use LoadImmediately unless you have LOTS of translations.
LoadImmediately = Regardless of the language, the CSV will load when this component activates, and then it will be kept in memory until this component is destroyed.
LazyLoad = The CSV file will only load when the CurrentLanguage or DefaultLanguage matches the CSV language, and then it will be kept in memory until this component is destroyed.
LazyLoadAndUnload = Like LazyLoad, but translations will be unloaded if the CurrentLanguage or DefaultLanguage differs from the CSV language.
LazyLoadAndUnloadPrimaryOnly = Like LazyLoadAndUnload, but only the CurrentLanguage will be used, the DefaultLanguage will be ignored.
List<Entry>
Entries
This stores all currently loaded translations from this CSV file.
void
Clear
This will unload all translations from this component.
void
LoadFromSource
This will load all translations from the CSV file into this component.
LeanLanguageNameAttribute
This attribute allows you to modify a normal string field into one that has a dropdown list that allows you to pick a language.
LeanLocalization
This component manages a global list of translations for easy access.
Translations are gathered from the prefabs list, as well as from any active and enabled LeanSource components in the scene.
static List<LeanLocalization>
Instances
All active and enabled LeanLocalization components.
static Dictionary<string, LeanTranslation>
CurrentTranslations
Dictionary of all the phrase names mapped to their current translations.
DetectType
DetectLanguage
How should the cultures be used to detect the user's device language?
string
DefaultLanguage
If the application is started and no language has been loaded or auto detected, this language will be used.
SaveLoadType
SaveLoad
This allows you to control if/how this component's CurrentLanguage setting should save/load.
None = Only the DetectLanguage and DefaultLanguage settings will be used.
WhenChanged = If the CurrentLanguage gets manually changed, automatically save/load it to PlayerPrefs?
List<LeanPrefab>
Prefabs
This stores all prefabs and folders managed by this LeanLocalization instance.
static event System.Action
OnLocalizationChanged
Called when the language or translations change.
string
CurrentLanguage
Change the current language of this instance?
static void
RegisterToken
string name, LeanToken token
When rebuilding translations this method is called from any LeanSource components that define a token.
static LeanTranslation
RegisterTranslation
string name
When rebuilding translations this method is called from any LeanSource components that define a transition.
void
SetCurrentLanguage
string newLanguage
This sets the current language using the specified language name.
static void
SetCurrentLanguageAll
string newLanguage
This sets the current language of all instances using the specified language name.
static string
GetFirstCurrentLanguage
This returns the CurrentLanguage value from the first LeanLocalization instance in the scene if it exists, or null.
void
AddPrefab
Object root
This adds the specified UnityEngine.Object to this LeanLocalization instance, allowing it to be registered as a prefab.
static LeanLanguage
AddLanguageToFirst
string name
This calls AddLanguage on the first active and enabled LeanLocalization instance, or creates one first.
LeanLanguage
AddLanguage
string name
This creates a new token with the specified name, and adds it to the current GameObject.
static LeanToken
AddTokenToFirst
string name
This calls AddToken on the first active and enabled LeanLocalization instance, or creates one first.
LeanToken
AddToken
string name
This creates a new token with the specified name, and adds it to the current GameObject.
static void
SetToken
string name, string value, bool allowCreation = true
This allows you to set the value of the token with the specified name.
If no token exists and allowCreation is enabled, then one will be created for you.
static string
GetToken
string name, string defaultValue = null
This allows you to get the value of the token with the specified name.
If no token exists, then the defaultValue will be returned.
static LeanPhrase
AddPhraseToFirst
string name
This calls AddPhrase on the first active and enabled LeanLocalization instance, or creates one first.
LeanPhrase
AddPhrase
string name
This creates a new phrase with the specified name, and adds it to the current GameObject.
static LeanTranslation
GetTranslation
string name
This will return the translation with the specified name, or null if none was found.
static string
GetTranslationText
string name, string fallback = null, bool replaceTokens = true
This will return the translated string with the specified name, or the fallback if none is found.
static T
GetTranslationObject<T>
string name, T fallback = null
This will return the translated UnityEngine.Object with the specified name, or the fallback if none is found.
static void
UpdateTranslations
bool forceUpdate = true
This rebuilds the dictionary used to quickly map phrase names to translations for the current language.
static void
DelayUpdateTranslations
If you call this method, then UpdateTranslations will be called next Update.
LeanLocalizedAudioSource LeanLocalizedBehaviour
This component will update an AudioSource component with localized text, or use a fallback if none is found.
LeanLocalizedBehaviour
This component simplifies the updating process, extend it if you want to cause a specific object to get localized
string
TranslationName
This is the name of the translation this script uses.
void
UpdateLocalization
If you call this then this component will update using the translation for the specified phrase.
LeanLocalizedDropdown
This component will update a UI.Dropdown component with localized text, or use a fallback if none is found.
void
UpdateLocalization
If you call this then this component will update using the translation for the specified phrase.
LeanLocalizedImage LeanLocalizedBehaviour
This component will update an Image component with a localized sprite, or use a fallback if none is found
LeanLocalizedRenderer LeanLocalizedBehaviour
This component will update a Renderer component's sharedMaterial with a localized material, or use a fallback if none is found.
LeanLocalizedSpriteRenderer LeanLocalizedBehaviour
This component will update a SpriteRenderer component with a localized sprite, or use a fallback if none is found
LeanLocalizedText LeanLocalizedBehaviour
This component will update a UI.Text component with localized text, or use a fallback if none is found.
LeanLocalizedTextFont LeanLocalizedBehaviour
This component will update a Text component's Font with a localized font, or use a fallback if none is found.
LeanLocalizedTextMesh LeanLocalizedBehaviour
This component will update a TMPro.TextMeshProUGUI component with localized text, or use a fallback if none is found.
LeanLocalizedTextMeshFont LeanLocalizedBehaviour
This component will update a TextMesh component's Font with a localized font, or use a fallback if none is found.
LeanLocalizedTextMeshPro LeanLocalizedBehaviour
This component will update a TMPro.TextMeshPro component with localized text, or use a fallback if none is found.
LeanLocalizedTextMeshProFont LeanLocalizedBehaviour
This component will update a TextMeshPro component's Font with a localized font, or use a fallback if none is found.
LeanLocalizedTextMeshProUGUI LeanLocalizedBehaviour
This component will update a TMPro.TextMeshProUGUI component with localized text, or use a fallback if none is found.
LeanLocalizedTextMeshProUGUIFont LeanLocalizedBehaviour
This component will update a TextMeshProUGUI component's Font with a localized font, or use a fallback if none is found.
LeanLocalizedTMP_Dropdown
This component will update a TMP_Dropdown component with localized text, or use a fallback if none is found.
void
UpdateLocalization
If you call this then this component will update using the translation for the specified phrase.
LeanLocalToken LeanToken
The component works like LeanToken, but must be added to the child GameObject of the one that will be translated.
LeanPhrase LeanSource
This contains data about each phrase, which is then translated into different languages.
string
Language
The language of this translation.
string
Text
The translated text.
Object
Object
The translated object (e.g. language specific texture).
bool
TryFindTranslation
string languageName, ref Entry entry
This will return the translation of this phrase for the specified language.
Entry
AddEntry
string languageName, string text = null, Object obj = null
Add a new translation to this phrase for the specified language, or return the current one.
LeanPrefab
This class stores a reference to an object (e.g. folder) in your project that contains LeanSource components so they can be registered.
LeanSource
This is the base class used for all translation sources. When a translation source is built, it will populate the LeanLocalization class with its translation data.
void
Register
This allows you to register a token or language.
void
Register
string primaryLanguage, string secondaryLanguage
This allows you to register a phrase based on the specified languages.
LeanToken LeanSource
The class stores a token name (e.g. "AGE"), allowing it to be replaced with the token value (e.g. "20").
To use the token in your text, simply include the token name surrounded by braces (e.g. "I am {AGE} years old!")
string
Value
This is the current value/text for this token. When this changes, it will automatically update all localizations that use this token.
void
SetValue
float value
This method allows you to set Value from an inspector event using a float value.
void
SetValue
string value
This method allows you to set Value from an inspector event using a string value.
void
SetValue
int value
This method allows you to set Value from an inspector event using an int value.
LeanTranslation
This contains the translated value for the current language, and other associated data.
string
Name
The name of this translation.
object
Data
The data of this translation (e.g. string or Object).
bool
Primary
If Data has been filled with data for the primary language, then this will be set to true.
List<Entry>
Entries
This stores a list of all LeanSource instances that are currently managing the current value of this translation in the current language.
static string
FormatText
string rawText, string currentText = null, ILocalizationHandler handler = null, GameObject localTokenRoot = null
This returns Text with all tokens substituted using the LeanLocalization.Tokens list.