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:

Method 1 From your menu bar, select GameObject > Lean > Localization.
Method 2 Right click inside the Hierarchy window, and go to Lean > Localization.
Method 3 Create a new GameObject, and add the component Lean > Localization.

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.

EXAMPLE: If you want to translate UI Text, then you can add the LeanLocalizedText component to your GameObject that has the Text component.
EXAMPLE: If you want to translate a SpriteRenderer's sprite, then you can add the LeanLocalizedSpriteRenderer component to your GameObject that has the SpriteRenderer component.

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?

Step 1 Select a phrase (LeanPhrase component).
Step 2 Add a translation for at least one language (e.g. English).
Step 3 Click the Add button next to the language you want to automatically create a translation for (e.g. Spanish).
Step 4 Click the Modify button, and select Auto Translate > From ___, where ___ is the language you want to automatically translate from (e.g. English).

That's it! Your phrase should now have automatically translated from one language (e.g. English) to another (e.g. Spanish).

NOTE  This feature uses the Google Translate API, and there may be limits on how often you can use it every day.


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:

Method 1 Duplicate one of the existing language prefabs.
Method 2 Right click inside the Project window, and select the Create > Lean > Localization > Lean Language option.

You should now see a language prefab. Now you must:

Step 1 Rename the prefab to the name/title of the language you want.
Step 2 [Optional] Set the TranslationCode of the language, this should be the two letter code like en, de, ja, etc. This is used by the auto translation system.
Step 3 [Optional] Set the language culture names/alises. When detecting a language these culture names are used to choose the correct language. This depends on your LeanLocalization component's DetectLanguage setting.

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.

NOTEtranslation.Data is a System.Object, so you must verify it's type before casting it out.


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.

EXAMPLE: MyGroup/MyTranslation

When using a translation name dropdown, this will automatically place MyTranslation into a group called MyGroup.

NOTE  If you change the name of a translation after you created it, then any components that point to that translation name will point to the old and now non-existent translation. You must manually update these.


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.

NOTE  If your prefab points to an asset folder, then you must view the LeanLocalization inspector to force the folder contents to update. Folder contents like this can only be accessed in the editor, so you must do this to trigger its update.

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:

Method 1  Create a new GameObject and add the LeanToken component.
Method 2  Type the name of a token into the LeanLocalization > Tokens search box, and click the Add button.

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.

NOTE  If you want to be able to change a token value and have it persist across multiple scenes, then you should place the token in a prefab, and add it to the LeanLocalization.Prefabs list.



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.

NOTE  The LeanLocalization component's DetectLanguage setting defines how the initial language name or culture name will be picked.


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.

NOTE  You must use the TextMeshPro specific components, like LeanLocalizedTextMeshProUGUI.






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

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+

Lean Touch+ is an extension to the popular Lean Touch asset, adding many more example scenes.


Lean Localization

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

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

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

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

Lean GUI Shapes allows you to quickly add lines, rounded boxes, polygons, and much more to your GUI!


Lean Texture

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+

Lean Texture+ is an extension to Lean Texture, adding many new types of texture modification tools!


Paint in 3D

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

FLOW allows you to add large scale interactive fluids to your scene - all highly optimized using GPU acceleration.


Destructible 2D

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

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

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

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

NOTE  This is a massive update. To update you must first back up your project, delete the root SpaceGraphicsToolkit folder, then install the new version.

Changed folder structure to be inside Plugins/CW/LeanLocalization.
Updated inspector code to support third party assets that implement nested inspectors.



1.5.3

Fixed transform gizmos not appearing in Unity 2021.2.



1.5.2

Updated common library code.



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

NOTE  This is a huge update. Back up your project files before installing.

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.4.0

Added LeanLocalToken component.
Added Local Token demo scene.



1.3.9

Moved main build to Unity 2018.4.13f1.



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

Fixed LeanLocalization.SetCurrentLanguage bug.



1.3.6

Added LeanLocalizedTextMeshPro to TextMeshPro package.
Added LeanLocalizedTextMeshProFont to TextMeshPro package.



1.3.5

Fixed LeanToken inspector changes not automatically updating text.
Updated common library code.



1.3.4

Fixed inspector expand buttons in UI Elements.



1.3.3

Fixed bug where LeanLocalization.CurrentLanguage wouldn't save unless it was changed in game.



1.3.2

Fixed bug in LeanHelper.cs that prevents making builds.



1.3.1

Updated Common library code.



1.3.0

Updated Common library code.
Updated demo scene design.







Components

ILocalizationHandler

This interface can be implemented by any component that needs to listen for localization changes.



LeanLanguage

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

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

NOTE  This component only handles loading one CSV file from one language. If you have multiple languages, then you must make multiple CSV files for each, and a matching LeanLanguageCSV component to load each.

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.



void
ExportTextAsset

This exports all text phrases in the LeanLocalization component for the Language specified by 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?

NOTE  This save data can be cleared with ClearSave context menu option.


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.




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.




LeanLocalToken

The component works like LeanToken, but must be added to the child GameObject of the one that will be translated.



LeanPhrase

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

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).

NOTE  This is a System.Object, so you must correctly cast it back before use.


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.

NOTE  If this is empty then no LeanSource of this name is localized for 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.

NOTE  If you want local tokens to work, then specify the localTokenRoot GameObject.



LeanTranslationNameAttribute

This attribute allows you to select a translation from all the localizations in the scene.



LeanLocalizedAudioSource

This component will update an AudioSource component with localized text, or use a fallback if none is found.



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

This component will update an Image component with a localized sprite, or use a fallback if none is found



LeanLocalizedRenderer

This component will update a Renderer component's sharedMaterial with a localized material, or use a fallback if none is found.



LeanLocalizedSpriteRenderer

This component will update a SpriteRenderer component with a localized sprite, or use a fallback if none is found



LeanLocalizedText

This component will update a UI.Text component with localized text, or use a fallback if none is found.



LeanLocalizedTextFont

This component will update a Text component's Font with a localized font, or use a fallback if none is found.



LeanLocalizedTextMesh

This component will update a TMPro.TextMeshProUGUI component with localized text, or use a fallback if none is found.



LeanLocalizedTextMeshFont

This component will update a TextMesh component's Font with a localized font, or use a fallback if none is found.



LeanLocalizedTextMeshPro

This component will update a TMPro.TextMeshPro component with localized text, or use a fallback if none is found.



LeanLocalizedTextMeshProFont

This component will update a TextMeshPro component's Font with a localized font, or use a fallback if none is found.



LeanLocalizedTextMeshProUGUI

This component will update a TMPro.TextMeshProUGUI component with localized text, or use a fallback if none is found.



LeanLocalizedTextMeshProUGUIFont

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.




Index

What is Lean Localization?

How do I use it?

How do I automatically translate words?

How do I change language?

How do I get a translation from C# code?

How do I add to the language list?

How do I localize other components?

How do I better organize my translations?

How do I use prefabs?

How do I use tokens?

What are Cultures?

Why can you only translate Text, Object, and Sprite?

Is Text Mesh Pro supported?



Assets

Lean Touch

Lean Touch+

Lean Localization

Lean Pool

Lean Transition

Lean GUI

Lean GUI Shapes

Lean Texture

Lean Texture+

Paint in 3D

FLOW

Destructible 2D

Space Graphics Toolkit

Space Graphics Planets

Volumetric Audio



Versions

2.0.0

1.5.3

1.5.2

1.5.1

1.5.0

1.4.0

1.3.9

1.3.8

1.3.7

1.3.6

1.3.5

1.3.4

1.3.3

1.3.2

1.3.1

1.3.0



Components

ILocalizationHandler

LeanLanguage

LeanLanguageCSV

LeanLanguageNameAttribute

LeanLocalization

LeanLocalizedBehaviour

LeanLocalToken

LeanPhrase

LeanPrefab

LeanSource

LeanToken

LeanTranslation

LeanTranslationNameAttribute

LeanLocalizedAudioSource

LeanLocalizedDropdown

LeanLocalizedImage

LeanLocalizedRenderer

LeanLocalizedSpriteRenderer

LeanLocalizedText

LeanLocalizedTextFont

LeanLocalizedTextMesh

LeanLocalizedTextMeshFont

LeanLocalizedTextMeshPro

LeanLocalizedTextMeshProFont

LeanLocalizedTextMeshProUGUI

LeanLocalizedTextMeshProUGUIFont

LeanLocalizedTMP_Dropdown