DartCore.Localization - AtaTrkgl/Unity-DartCore Wiki

1. Adding and Removing Language Files

To manage the languages, click "DartCore/Localization/Language File Manager" from the toolbar

image of the toolbar

After pressing it, the "Language File Manager" will pop up. From there, you can manage the languages. The section bellow the current languages allows you to add new languages to your project easly. There are 4 fields to fill to create a new language.

  1. "Language to add" : Language to add.
  2. "File Name" : Name of the file where the data will be stored like "en" or "tr". (don't specify the extention like .txt or .csv)
  3. "Language Name" : The name of the language in that language. (Deutch for German, Türkçe for Turkish)
  4. "Language Error Message" : The error message in that language in case something goes wrong.

image of the Language File Manager

2. Adding, Removing and Editing Keys

To add, remove or edit keys we need to access the Key Editor window. for that click "DartCore/Localization/Key Editor" from the toolbar

image of the toolbar

After opening the Key Editor you can either search for a key to edit or create a new key by typing its name and then clicking the "Add New Key" button. If you are editing a key, the changes that are not saved in a language will be written in red, don't forget to click the "Update Values" button to save them.

image of the Key Editor

To check which keys have been localized you can open the "Key Browser" via "DartCore/Localization/Key Browser". There you can search for keys and see which ones localized to which languages. Green means localized, while red means the opposite. Clicking on a key will open it in the Key Editor.

image of the Key Browser

3. Language Updater

By adding the LanguageUpdater component to a TextMeshPro Text, you can localize it's text. You can also add prefixes & suffixes to the text. For example if you want to have a label before the health displayer and you want to use a semicolon, you can use a key called "health" which will localize to "Health" and then add ":" as a suffix, this will result in "Health:".

image of the LanguageUpdater

4. Scripting

4.1 Localizator.GetCurrentLanguage()

This function returns the current language.

Example Usage:

SystemLanguage currentLanguage = Localization.GetCurrentLanguage();

4.2 Localizator.GetString()

This function is used for getting the localized value of a given key. It has 2 overloads:

if the parameter returnErrorString is set to true the function will return the value of the "lng_error" key if the given key is invalid or not localized in the current language. If it is set to false, it will return and empty string("") instead of an error message.

Example Usage for getting the value of the "test_key" key in the current language:

string value = Localization.GetString(test_key);

getting the same value in French:

string value = Localization.GetString(test_key, SystemLanguage.French);

4.3 Localizator.UpdateLanguage()

This function is used for changing the current language. It takes one argument which is the desired language. If that language is available it will return true and change the language, however, if the language is not available, it will return false.

Example Usage for changing the language to Turkish:

Localizator.UpdateLanguage(SystemLanguage.Turkish);

4.4 Localizator.SetLanguageAccordingToSystem()

This function will set the current language to the systems language if it is available.

Example Usage:

Localizator.SetLanguageAccordingToSystem();

4.5 Localizator.GetAvailableLanguages()

This function returns and array of SystemLanguages which contains the languages available for use.

Example Usage:

SystemLanguage[] languages = Localizator.GetAvailableLanguages();

4.6 Localizator.GetLanguageCount()

This function returns the number of languages available for use.

Example Usage:

int languageCount = Localizator.GetLanguageCount();
SystemLanguage[] languages = Localizator.GetAvailableLanguages();

if (languageCount == languages.Length)
    Debug.Log("Yes");
else
    Debug.Log("No");
    
//Output is Yes

4.7 Localizator.GetCurrentLanguageFiles()

This function returns a string array that contains the names of the current languages' file names.

Example Usage:

string[] currentLanguageFiles = Localizator.GetCurrentLanguageFiles();

4.8 Localizator.DoesContainKey()

This function returns a boolean which will be true if the key file contains the given key, it will return false otherwise.

Example Usage:

bool doesContainTestKey = Localizator.DoesContainKey("test_key");

4.9 Localizator.GetKeys()

This function returns string array which contains every key available.

Example Usage:

string[] keys = Localizator.GetKeys();

4.10 Localizator.CreateLanguage()

This function is used for creating a new language file. It should be used in editor, not in game. It is strongly recommended to use the method showed in the 1.1 section to add a new language. However, if you need to add a new language programmatically you can use this function. The function itself takes 4 arguments with the following order:

  1. "language" : Language to add
  2. "fileName" : Name of the file where the data will be stored (don't specify the extention like .txt or .csv
  3. "lngName" : The name of the language in that language (Deutch for German, Türkçe for Turkish)
  4. "lngErrorMessage" : The error message in that language in case something goes wrong

Example Usage:

Localizator.CreateLanguage(SystemLanguage.English, "en", "English","Localization Error");

4.11 Localizator.RemoveLanguage()

This function is used for creating a new language file. It should be used in editor, not in game. It is strongly recommended to use the method showed in the 1.1 section to add a new language. However, if you need to add a new language programmatically you can use this function. The function itself takes 1 argument:

  1. "language" : Language to remove

Example Usage:

Localizator.RemoveLanguage(SystemLanguage.English);

4.12 Localizator.RefreshAll()

This function refreshes all references to key and language files. After editing the files, this function is required for everything to work correctly.

Example Usage:

Localizator.RefreshAll();

4.13 Localizator.OnLanguageChange

This event is raised when the language is changed. This can be used to call a certain function on language change.

Example Usage:

private string value = "";
private string key = "test_key";

private void Start()
{
   UpdateValue();
   // UpdateValue function will be called everytime the language is changed.
   Localizator.OnLanguageChange += UpdateValue;
}

private void UpdateValue()
{
   value = Localizator.GetString(key);
}

4.14 Localizator.GetStringWithFallBackLanguage()

This function works same as the GetString() method, however, if a localization is not available it will try to get the localization from the provided fallback language. If that's not available too, it will return a error message or an empty string depending on the parameter GetString()

Example Usage for getting the value of the "test_key" key in the current language:

string value = Localization.GetStringWithFallBackLanguage(test_key, SystemLanguage.English, returnErrorString: true);
// If the current language is Turkish and there exist a localized value for the test_key in Turkish
// value will be set to the Turkish value of the test_key
// If it doesn't exist it will be set to the English value of the test_key
// If that doesn't exists either it will be set to the localization error key in the Turkish Language.

4.15 Localizator.LocalizedKey Attribute

By adding the [LocalizedKey] attribute to a string, the string will be displayed in the inspector as a key. It will show if the key entered exists, it will also have a button to edit the entered key.

Example Usage:

[LocalizedKey] public string nameKey;
[LocalizedKey] public string descriptionKey;

How it looks:

image of the localizedKey attribute