Unity Localization 한 방에 끝내기: Localize String Event부터 동적 문자열·언어 전환까지

 

Localization 컴포넌트 접근해서 Table 변경하기

 

 

현지화 작업을 하다가 보면

하나의 오브젝트 안에서 다양한 동작을 하는 경우가 있다.

 

나같은 경우는 레벨 1일 경우에는 Text안에 "레벨1입니다."

2일 경우에는 "레벨 2입니다." 처럼 상황에 따라서 변경해주어야 하는 상황이라서

Localize String Event에서 String Reference를 변경 해주어야 했다.

 

일단은 String Table 안에서 

 

상황에 맞는 string 을 영문 버전과 한글 버전에 맞춰서 입력 해주었다.

 

 그리고

 

LocalizeStringEvnet 를 사용하기 위해서 

 

네임스페이스 : using UnityEngine.Localization.Components 를 추가해준다.

 

Localize String Evnet를 가진 오브젝트(텍스트) 불러오기 위해서

다음과 같이 선언을 해준다.

 

 public LocalizeStringEvent LStringEvent;

 

 

[ 컴포넌트 접근 하는 방법]

public LocalizeStringEvent LStringEvent;
    
LStringEvent.StringReference.TableReference = "BasicStringTable";
LStringEvent.StringReference.TableEntryReference = "Game_Clear1_str";

바꾸고 싶은 테이블의 이름(TableReference)과

테이블의 키(TableEnterReference)를 

 

[ 응용 해서 상황에 따라서 사용한 경우]

 

  LStringEvent.StringReference.TableReference = "BasicStringTable";
        if (GameManager.instance.CoreGame_Stage_i.Equals(1))
        {
            LStringEvent.StringReference.TableEntryReference = "Game_Clear1_str";
        }
        else if (GameManager.instance.CoreGame_Stage_i.Equals(2))
        {
            LStringEvent.StringReference.TableEntryReference = "Game_Clear2_str";
        }
        else if (GameManager.instance.CoreGame_Stage_i.Equals(3))
        {
            LStringEvent.StringReference.TableEntryReference = "Game_Clear3_str";
        }
        else if (GameManager.instance.CoreGame_Stage_i.Equals(4))
        {
            LStringEvent.StringReference.TableEntryReference = "Game_Clear4_str";
        }

 

1. Unity Localization이란?

Unity Localization 패키지는 문자열과 멀티미디어 Asset을 테이블 기반으로 관리해, 빌드 한 번으로 다양한 언어를 지원할 수 있게 해 주는 공식 솔루션입니다.

용어 정의

String Table	언어별로 관리되는 키–값(번역 문자열) 테이블
Table Reference	참조할 테이블 이름 또는 GUID
Table Entry Reference	테이블 안에서 특정 문자열을 가리키는 키
Locale / LocaleIdentifier	en-US, ko-KR처럼 언어·지역을 나타내는 코드
LocalizedString	테이블·키 정보를 담아 실제 번역 문자열을 비동기로 가져오는 구조체
Localize String Event	UI 텍스트(Text / TextMeshPro)에 번역을 자동 적용해 주는 컴포넌트

---

2. 정적 UI 텍스트 현지화: Localize String Event

1. Text UI를 선택 → Inspector에서 Localize 클릭
2. Localize String Event 컴포넌트가 추가됨
3. String Reference에서 테이블과 키 지정
4. 실행하면 Game 창 우측에 언어 전환 드롭다운(샘플 UI)이 자동 표시

팁
같은 방법으로 TextMeshPro UGUI도 적용됩니다.

---

3. 스크립트에서 테이블 직접 참조하기

using UnityEngine.Localization;
using UnityEngine.ResourceManagement.AsyncOperations;

public string GetLocalizedString(string table, string key)
{
    var locString = new LocalizedString
    {
        TableReference = table,
        TableEntryReference = key
    };

    var handle = locString.GetLocalizedStringAsync();
    if (handle.IsDone && handle.Status == AsyncOperationStatus.Succeeded)
        return handle.Result;

    return null; // 아직 로딩 중이거나 실패
}

대안
LocalizationSettings.StringDatabase.GetLocalizedStringAsync(table, key) 도 같은 결과를 반환합니다.

---

4. 런타임 언어 전환 (언어 메뉴 없이 코드로만)

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

public void LoadLocale(string localeCode)   // 예: "en-US"
{
    var target = new LocaleIdentifier(localeCode);

    foreach (var locale in LocalizationSettings.AvailableLocales.Locales)
    {
        if (locale.Identifier == target)
        {
            LocalizationSettings.SelectedLocale = locale;
            break;
        }
    }
}

• 사용 가능한 언어 코드는 Edit ▸ Project Settings ▸ Localization ▸ Available Locales에서 확인

---

5. 하나의 컴포넌트에서 문자열 동적으로 교체하기

레벨 클리어 팝업처럼 같은 UI 요소가 상황(스테이지 레벨 등)에 따라 다른 문자열을 보여줘야 할 때:

using UnityEngine;
using UnityEngine.Localization.Components;

public class StageClearText : MonoBehaviour
{
    public LocalizeStringEvent lse;   // Inspector에 연결

    public void Refresh(int stage)
    {
        lse.StringReference.TableReference  = "BasicStringTable";

        switch (stage)
        {
            case 1: lse.StringReference.TableEntryReference = "Game_Clear1_str"; break;
            case 2: lse.StringReference.TableEntryReference = "Game_Clear2_str"; break;
            case 3: lse.StringReference.TableEntryReference = "Game_Clear3_str"; break;
            case 4: lse.StringReference.TableEntryReference = "Game_Clear4_str"; break;
        }

        // 값이 바뀌면 LocalizeStringEvent가 자동으로 텍스트를 다시 갱신
    }
}

---

6. Addressables 빌드 잊지 말기

Localization 패키지는 내부적으로 Addressables를 사용합니다. 빌드 전에:

1. Window ▸ Asset Management ▸ Addressables ▸ Groups
2. Build ▸ New Build ▸ Default Build Script 실행
   • 번역 테이블과 리소스가 번들에 포함되어, 실제 플레이 / 배포 버전에서 문자열이 정상 로드됩니다.

---

7. 정리

• 정적 UI는 Inspector에서 Localize String Event로 간편하게 번역
• 동적 문자열은 스크립트로 LocalizedString 또는 LocalizeStringEvent를 제어
• 언어 전환은 LocalizationSettings.SelectedLocale 한 줄이면 끝
• 빌드 전엔 Addressables를 반드시 빌드

이제 프로젝트를 다국어로 확장할 준비가 끝났습니다. 즐거운 현지화 개발 되세요!