Unity Localization 패키지 — 다국어 지원 완벽 가이드

개요

Unity Localization 패키지는 게임의 텍스트, 이미지, 오디오 등을 언어별로 관리하는 공식 솔루션입니다. String Table, Asset Table, Smart Strings를 통해 체계적인 다국어 지원을 구현할 수 있습니다.

---

1. 설치 및 초기 설정

Package Manager → Unity Registry → Localization 검색 → Install

Edit → Project Settings → Localization → Create

Locale을 추가합니다 (Korean, English, Japanese 등).

---

2. String Table 생성 및 사용

Window → Asset Management → Localization Tables → Create New Table Collection

using UnityEngine;
using UnityEngine.Localization;
using UnityEngine.Localization.Settings;

public class UIText : MonoBehaviour
{
    // Inspector에서 Table과 Key 지정
    public LocalizedString welcomeText;

    void Start()
    {
        // 비동기 로드
        welcomeText.GetLocalizedStringAsync().Completed += op =>
        {
            GetComponent<TMPro.TMP_Text>().text = op.Result;
        };
    }
}

---

3. LocalizeStringEvent 컴포넌트

코드 없이 Inspector에서 바로 바인딩:

GameObject에 LocalizeStringEvent 컴포넌트 추가
→ String Reference에 Table/Key 지정
→ Update String 이벤트에 TMP_Text.text 연결

---

4. Smart Strings — 동적 문자열

// Table 값: "플레이어 {player.Name}이 {score}점을 획득했습니다!"
using UnityEngine.Localization.SmartFormat;

public class ScoreDisplay : MonoBehaviour
{
    public LocalizedString scoreMessage;

    [System.Serializable]
    public class PlayerData
    {
        public string Name;
    }

    void UpdateScore(PlayerData player, int score)
    {
        scoreMessage.Arguments = new object[] {
            new { player, score }
        };

        scoreMessage.GetLocalizedStringAsync().Completed += op =>
        {
            scoreText.text = op.Result;
            // 결과: "플레이어 홍길동이 1500점을 획득했습니다!"
        };
    }
}

---

5. Asset Table — 언어별 에셋 교체

using UnityEngine.Localization;
using UnityEngine.UI;

public class LocalizedImage : MonoBehaviour
{
    public LocalizedAsset<Sprite> localizedSprite;

    void Start()
    {
        localizedSprite.AssetChanged += sprite =>
        {
            GetComponent<Image>().sprite = sprite;
        };
    }
}

언어별로 다른 폰트, 오디오 클립, 텍스처를 Asset Table에 등록하면 자동으로 교체됩니다.

---

6. 런타임 언어 전환

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

public class LanguageSelector : MonoBehaviour
{
    public async void SwitchLanguage(string localeCode)
    {
        // Locale 코드로 찾기 (예: "ko", "en", "ja")
        var locale = LocalizationSettings.AvailableLocales.Locales
            .Find(l => l.Identifier.Code == localeCode);

        if (locale != null)
        {
            LocalizationSettings.SelectedLocale = locale;
            // 자동으로 모든 LocalizeStringEvent가 갱신됨
        }
    }

    void OnGUI()
    {
        if (GUILayout.Button("한국어")) SwitchLanguage("ko");
        if (GUILayout.Button("English")) SwitchLanguage("en");
    }
}

---

7. 복수형(Plural) 처리

// Table 값 (Smart String)
{count:plural:{}개 아이템|{}개 아이템들}

scoreMessage.Arguments = new object[] { new { count = itemCount } };

---

8. CSV 내보내기/가져오기

번역가에게 전달하기 위한 CSV 익스포트:

Localization Tables 창 → Export → CSV (Comma Separated Values)

번역 완료 후:

Localization Tables 창 → Import → CSV

---

정리

Unity Localization 패키지는 하드코딩된 문자열을 String Table로 분리하고, Smart Strings로 동적 값을 삽입하며, Asset Table로 언어별 에셋을 자동 교체합니다. CSV 내보내기로 번역 파이프라인을 구축하면 대규모 다국어 프로젝트도 체계적으로 관리할 수 있습니다.