Localization

Usually the localization works transparently and automatically in the background.

When you access a localizable property of an object, the plugin will automatically fetch the proper localized text for the current language.

Entity entity = ArticyDatabase.GetObject<Entity>("Chr_Manfred");
Debug.Log(entity.DisplayName); // prints the localized DisplayName for the current language

Localizable properties are not strings, but ArticyMultiLanguageStrings, which will cast implicitly to string. The type contains more information like the associated voice over asset or localization key and supports things like overriding the text for different languages at runtime.

Debug.Log(entity.DisplayName.LocaKey); // prints the localization key

You can get an articy object reference to the voice over asset via VOAssetRef. But usually you want to load the voice over asset directly:

AudioClip audioClip = objWithText.Text.LoadVOAssetAsAudioClip();
if (audioClip != null)
{
    audioSource.clip = audioClip;
    audioSource.Play();
}

To access the available languages and change the current one, you have to access the ArticyLocalizationManager found on the ArticyDatabase. The localization manager is used to configure how the localization works, to localize manually and to change the language.

The information about a language is provided via the type ArticyLanguage:

// get all languages
foreach (ArticyLanguage language in ArticyDatabase.Localization.Languages)
{
    Debug.Log($"{language.ArticyLanguageId}, {language.CultureName}, {language.LanguageName}");
}

// get the current used language
Debug.Log(ArticyDatabase.Localization.Language); // string representation will be the culture name

There are multiple ways to change the language:

ArticyDatabase.Localization.SetLanguage(ArticyDatabase.Localization.Languages[0]); // via ArticyLanguage
ArticyDatabase.Localization.SetLanguage(127); // via language id
ArticyDatabase.Localization.SetLanguage("en"); // via culture name

Sometimes it is necessary to be notified when the language is changed. The localization manager has an event that is called everytime the language is changed.

void Start()
{
    ArticyDatabase.Localization.languageChanged += OnLanguageChanged;
}

void OnDestroy()
{
    ArticyDatabase.Localization.languageChanged -= OnLanguageChanged;
}

void OnLanguageChanged(ArticyLanguage aOldLanguage, ArticyLanguage aNewLanguage)
{
    // react to the changed language
}

Working with UI and localization is such a frequent task, that the plugin contains a specialized component to help update a specific UI element with localized text and even update it when the language is changed. To use it add the ArticyLocaCaretaker component to a game object with a Unity UI Text.

It is important to set the Target Component to do that, just drag and drop the Text component onto the Target Component field.

The caretaker will now make sure to always set the text property of the Text component to the localized value using the locaID. So you should make sure to set a correct loca key via the Inspector or via code

private ArticyLocaCaretaker uiLabelCaretaker;

public void OnFlowPlayerPaused(IFlowObject aObject)
{
    var dlgFragment = aObject as DialogueFragment;
    if(dlgFragment != null)
    {
        uiLabelCaretaker.LocaKey = dlgFragment.DisplayName.LocaKey;
    }
}

ArticyLocaCaretaker custom component support

Out of the box, the caretaker works with the Unity Text component, if you have a custom component or even a completely different use case, you can still use with the caretaker and just assign the localized text manually:

public ArticyLocaCaretaker dialogText;

void Start()
{
    dialogText.localizedTextAssignmentMethod.AddListener(AssignDialogueText);
}

private void AssignDialogueText(Component aTargetComponent, string aLocalizedText)
{
    // do something with component and the localized text
}

This works with only a single caretaker instance, allowing different instances to still use the default behaviour or another custom behaviour. But if necessary you can overwrite the default behaviour aswell, making every caretaker use your new behaviour automatically.

void Start()
{
    ArticyLocaCaretaker.AssignLocalizedTextMethod = AssignDialogueText;
}

private static void AssignDialogueText(Component aTargetComponent, string aLocalizedText)
{
    // do something with component and the localized text
}

Reference

Other Resources