Use Guide

Once you done with localization document set up, and general localization tokens is filled, you can start loclize your project with Google Doc Localization plugin API and components. 

If after reading you will have any questions or suggestion, do not hesitate to contact us: https://stansassets.com/#contacts

Scripting

This chapter will demonstrate basic approaches to manage localization in your project.

Initialization

Localization initialization is not required, localization module will be initialized automatically on first call to any localization API method. And yes, initialization may use some time, it depends on how much tokens needs to be processed. So this is a good practise to initialize localization module on your landing scene. See the code snippet bellow. 

Localization.Init();

Changing the language

In most cases your app will change default localization language in 2 cases:

  • On first app launch depending of current system language
  • When user is changed language in the app settings

For those or any other cases you can use SetLanguage method. See the code snippet bellow:

Localization.SetLanguage(LangCode.EN);

Note: LangCode enum will be create automatically by plugin, after analysing your localization document.

Note: Default localization language, is the first defined language in the LangCode enum.

Note: If your app called SetLanguage method plugin will save language choice for the next sessions.

In case some of your components needs to be notified when app localization si changed, you can subscribe to the OnLanguageChanged event. See the code snippet bellow.

Localization.OnLanguageChanged += Localization_OnLanguageChanged;
void Localization_OnLanguageChanged () {
	Debug.Log("Localization Chnaged: " + Localization.CurrentLanguage);
}

Getting Localized Strings

If you would like to get localized string out of localization token you need to use one of the following methods.

public static string GetLocalizedString(string token);
public static string GetLocalizedString(string token, LangSection section);
public static string GetLocalizedString(string token, LangSection section, LangCode lang);

Use example:

string banana = Localization.GetLocalizedString("banana");

Note: If token or section wasn't found in the document, same token string will be returned with the "_key_not_found" postfix, and warning will be thrown.

More Localization API feature may be found under the  Localization API Reference.

Mono Components

To help you localize your project with less coding we designed few useful mono components.

LabelLocalizer

The LabelLocalizer component should be added to the game object within contains UnityEngine.UI.Text. In case gameobject doesn't have the UnityEngine.UI.Text component LabelLocalizer  will look for it in the object childes.

All you need to do is to fill localization token and section fileds. And UnityEngine.UI.Text component text value will have localized token value when app is runing and will also react on laguage chnage action, so your lable text value will be automatically updated when app notification chnaged.

API Reference

Localization

namespace SA.GoogleDoc 

public class Localization {
		
	/// <summary>
	/// Action is fired, when localization language chnaged
	/// </summary>
	public static event Action OnLanguageChanged = delegate {};


	/// <summary>
	/// Init the localizaition API
	/// 
	/// Method call is optinal. You may use it on your app start
	/// otherwise localization will be initialized with fisrt localization API call 
	/// </summary>
	public static void Init();


	/// <summary>
	/// <para>Set's current localization language. </para>
	/// <para> </para>
	/// LanguageChanged action will be fired once new language dictionary parsed
	/// </summary>
	public static void SetLanguage(LangCode lang);


	/// <summary>
	/// Returns localized string by token
	/// 
	/// <param name="token"> localization token</param>
	/// </summary>
	public static string GetLocalizedString(string token);


	/// <summary>
	/// Returns localized string by token
	/// 
	/// <param name="token"> localization token</param>
	/// <param name="section"> localization section</param>
	/// </summary>
	public static string GetLocalizedString(string token, LangSection section);


	/// <summary>
	/// Returns localized string by token
	/// 
	/// <param name="token"> localization token</param>
	/// <param name="section"> localization section</param>
	/// <param name="lang"> localization language code</param>
	/// </summary>
	public static string GetLocalizedString(string token, LangSection section, LangCode lang);

	/// <summary>
	/// Returns  full localization dictionarry for the default section
	/// </summary>
	public static Dictionary<string, string> GetFullSectionLocalization();

	/// <summary>
	/// Returns  full localization dictionarry for the specified section
	/// 
	/// <param name="section"> localization section</param>
	/// </summary>
	public static Dictionary<string, string> GetFullSectionLocalization(LangSection section);

	/// <summary>
	/// Current Localization Language
	/// </summary>
	public static LangCode CurrentLanguage;

	/// <summary>
	/// DefaultLanguage Localization Language
	/// </summary>
	public static LangCode DefaultLanguage;

	/// <summary>
	/// DefaultLanguage Localization Section
	/// </summary>
	public static LangSection DefaultSection;

}

LabelLocalizer

public class LabelLocalizer : MonoBehaviour {
	/// <summary>
	/// Localization token
	/// </summary>
	public string Token = "token";

	/// <summary>
	/// Localization section
	/// </summary>
	public LangSection Sheet;
}