スクリプティング

このドキュメントでは、C# スクリプトを使用して Localization システムとインタラクトする最も一般的な方法を説明しています。

Package Manager ウィンドウの Localization パッケージの Samples セクションから、追加的なスクリプトサンプルがダウンロード可能です。

LocalizedString

LocalizedString は、String Table 内から特定のエントリーにアクセスします。

LocalizedString はユーザースクリプト内で使用できます。これは独自のエディターをシリアル化して表示します。このエディターを使用すれば、Tables ウィンドウを開くことなく、テーブルやテーブルエントリーの選択や、ローカライズされた値のインライン編集が行えます。

Unity の LocalizedString エディター

LocalizedString は StringChanged イベントを提供します。選択ロケールが変更されるとスクリプトがこのイベントを呼び出します。これにより、コードがよりシンプルで効率的になります (スクリプトは LocalizedAsset の更新が必要な時にしかこの呼び出しを行わないため)。


public class LocalizedStringWithEvents : MonoBehaviour
{
    public LocalizedString myString;

    string localizedText;

    /// <summary>
    /// Register a ChangeHandler. This is called whenever the string needs to be updated.
    /// </summary>
    void OnEnable()
    {
        myString.StringChanged += UpdateString;
    }

    void OnDisable()
    {
        myString.StringChanged -= UpdateString;
    }

    void UpdateString(string s)
    {
        localizedText = s;
    }

    void OnGUI()
    {
        EditorGUILayout.LabelField(localizedText);
    }
}

動的文字列

例えば Smart String や String.Format を変更後の引数で使用する場合など、ローカライズされた文字列の更新が必要になることもあります。そうした引数を使用して GetLocalizedString を呼び出すと常に文字列が更新されます。StringChanged イベントを使用すると、RefreshString 関数を使用して更新をリクエストし、Arguments プロパティを使用して文字列の書式設定を行う引数を設定できます。


/// <summary>
/// This example expects a Smart String with a named placeholder of `TimeNow`, such as "The time now is {TimeNow}".
/// </summary>
public class LocalizedStringSmart : MonoBehaviour
{
    public LocalizedString myString;

    string localizedText;

    public float TimeNow => Time.time;

    /// <summary>
    /// Register a ChangeHandler. This is called whenever we need to update our string.
    /// </summary>
    void OnEnable()
    {
        myString.Arguments = new[] { this };
        myString.StringChanged += UpdateString;
    }

    void OnDisable()
    {
        myString.StringChanged -= UpdateString;
    }

    void UpdateString(string s)
    {
        localizedText = s;
    }

    void OnGUI()
    {
        // This calls UpdateString immediately (if the table is loaded) or when the table is available.
        myString.RefreshString();
        GUILayout.Label(localizedText);
    }
}

LocalizedAsset

LocalizedAsset は、ローカライズされたバージョンの Unity アセットに Asset Table 内からアクセスするジェネリッククラスです。

Unity の LocalizedAsset エディター

LocalizedString は AssetChanged イベントを提供します。ローカライズされたアセットが新しく使用可能になった時 (ゲーム言語が変更された時など) にスクリプトがこのイベントを呼び出します。これにより、コードがよりシンプルで効率的になります (スクリプトは LocalizedAsset の更新が必要な時にしかこの呼び出しを行わないため)。

LocalizedAsset を使用するには、クラスの具象バージョンを作成し、それを Serializable としてマークする必要があります。

例えば、以下のクラスを定義することで、フォントアセットのローカライズをサポートできます。

using System;
using UnityEngine;
using UnityEngine.Localization;

[Serializable]
public class LocalizedFont : LocalizedAsset<Font> {}

この例では、スクリプトに LocalizedFont が追加可能になり、ローカライズされた Font アセットが使用可能になると LocalizedString が AssetChanged イベントを呼び出すようになっています。

以下の Unity アセットは既にサポートされています。

タイプ	クラス
AudioClip	`LocalizedAudioClip`
GameObject/Prefab	`LocalizedGameObject`
Material	`LocalizedMaterial`
Sprite	`LocalizedSprite`
Texture	`LocalizedTexture`

TableReference

TableReference 構造体を使用して Asset Table や String Table を参照できます。テーブルを参照するには、テーブルの名前か固有の GUID が使用できます。テーブル名は後に変更することになった場合に参照の手動更新が必要になりますが、GUID は常に同じままなので、通常は GUID を使用するほうが安全です。

TableEntryReference

TableEntryReference 構造体を使用して、Asset Table 内あるいは String Table 内のエントリーを参照できます。テーブルの参照にはテーブルの名前か固有の Key ID (符号なしの長い整数) が使用できます。テーブル名は後に変更することになった場合に参照の手動更新が必要になりますが、Key ID は常に同じままなので、通常は Key ID を使用するほうが安全です。

AsyncOperationHandle の使用

Unity は、ローカライズされたアセットを全て使用可能な状態でメモリ内に保持するわけではなく、必要になった時にオンデマンドで読み込み、不要になるとアンロードします。このため、ローカライズされたアセットは直ちに使用可能であるとは限らず、Unity によってディスクから読み込まれるかサーバーからフェッチされなければならない場合があります。これに対応するため、Unity は全てのリクエストのインターフェースとして AsyncOperationHandle を使用しています。アセットが直ちに使用可能でない場合は Localization システムが AsyncOperationHandle を返します。操作が完了すると AsyncOperationHandle が Completed イベントを発して Unity に通知します。この呼び出しは LateUpdate 中に行われます。リクエストが既に完了している場合 (例えば、リクエストされたデータが以前のリクエストから既に読み込まれている場合やプリロード中など) は、Result プロパティ経由でIsDone プロパティを確認することで、すぐにアクセスできます。あるいは、Completed イベントが LateUpdate 内で引き続き発生することで全てのコードが同じパスを辿ることができます。コルーチン内で AsyncOperationHandle を yield することも可能です。

メインスレッドで操作を強制的に完了させるには、WaitForCompletion を呼び出してください。詳細は Synchronous Workflow を参照してください。

基本的なロケール選択メニューの作成

以下は、ゲームで使用する言語 (Localization システムの Locale で定義される) をゲームのプレイヤーが選択できるようにする機能の作成方法の一例です。シーンに UI ドロップダウンメニューを追加するには、GameObject > UI > Dropdown を開き、以下のスクリプトを添付してください。


using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.Localization.Settings;
using UnityEngine.UI;

public class LocaleDropdown : MonoBehaviour
{
    public Dropdown dropdown;

    IEnumerator Start()
    {
        // Wait for the localization system to initialize
        yield return LocalizationSettings.InitializationOperation;

        // Generate list of available Locales
        var options = new List<Dropdown.OptionData>();
        int selected = 0;
        for (int i = 0; i < LocalizationSettings.AvailableLocales.Locales.Count; ++i)
        {
            var locale = LocalizationSettings.AvailableLocales.Locales[i];
            if (LocalizationSettings.SelectedLocale == locale)
                selected = i;
            options.Add(new Dropdown.OptionData(locale.name));
        }
        dropdown.options = options;

        dropdown.value = selected;
        dropdown.onValueChanged.AddListener(LocaleSelected);
    }

    static void LocaleSelected(int index)
    {
        LocalizationSettings.SelectedLocale = LocalizationSettings.AvailableLocales.Locales[index];
    }
}

このスクリプトのより高度なバージョンは Localization パッケージサンプル内に提供されています。

Editor

Editor スクリプティングクラス LocalizationEditorSettings を使用して Localization アセットに変更を加えることができます。

以下の例は、新しいロケールのサポートを追加することによってコレクションを更新する方法を示しています。


// Create the new Locale
var locale = Locale.CreateLocale(SystemLanguage.Spanish);
AssetDatabase.CreateAsset(locale, "Assets/Spanish.asset");
LocalizationEditorSettings.AddLocale(locale);

// Get the collection
var collection = LocalizationEditorSettings.GetStringTableCollection("My String Table");

// Add a new table
var newTable = collection.AddNewTable(locale.Identifier) as StringTable;

// Add a new entry to the table
var entry = newTable.AddEntry("Hello", "Hola");

// Add some metadata
entry.AddMetadata(new Comment { CommentText = "This is a comment"});

// We need to mark the table and shared table data entry as we have made changes
EditorUtility.SetDirty(newTable);
EditorUtility.SetDirty(newTable.SharedData);