Localization(언어)

Abstract

코어의 Localization 은 생각보다 작습니다. "키 → 문자열" 딕셔너리 하나와 "현재 언어"라는 값 하나가 전부입니다. 언어별 파일을 골라 읽는 일도, 언어를 바꿨을 때 화면을 갱신하는 일도 하지 않습니다. 그 사실을 알고 나면 "왜 언어를 바꿨는데 글자가 그대로지?" 같은 의문이 풀립니다. 사전 파일을 만들어 HUD 에 적용하는 과정은 Unity 쪽 로컬라이제이션 시스템 (Localization System) 페이지에 있습니다.

프레임워크가 해 주는 것과 내가 해야 하는 것

프레임워크	게임 코드
사전 파일을 읽어 딕셔너리에 넣기 (ReadData)	어느 언어의 파일을 읽을지 정하기
키로 문자열 찾기, {0} 자리 채우기 (GetString)	UI 텍스트에 실제로 넣기 — 폼이 열릴 때 GetString 을 불러 대입
기기 언어 알려 주기 (SystemLanguage)	지원하지 않는 언어일 때 대체 언어 고르기
현재 언어 값 보관 (Language)	언어를 바꿨을 때 사전을 다시 읽고 열린 화면을 갱신하기
	언어에 맞는 폰트 준비하기

런타임 언어 전환 — 직접 구현하는 순서

public void ChangeLanguage(Language language)
{
    LocalizationComponent localization = GameEntry.GetComponent<LocalizationComponent>();

    localization.RemoveAllRawStrings();          // ① 옛 사전을 비운다 (안 하면 중복 키로 파싱이 중단된다)
    localization.Language = language;            // ② 값을 바꾼다
    localization.ReadData(Utility.Text.Format("Dictionary.{0}", language));   // ③ 새 사전을 읽는다 (비동기)

    // ④ LoadDictionarySuccess 이벤트를 받으면 "언어가 바뀌었다"는 자체 이벤트를 발행하고,
    //    열려 있는 UI 폼들이 그것을 듣고 자기 텍스트를 GetString 으로 다시 채운다
}

복사

④가 핵심입니다. 프레임워크는 어떤 UI 가 어떤 키를 쓰는지 모르기 때문에, 화면 갱신은 이벤트로 알리고 각 폼이 스스로 다시 그리게 합니다. 실무에서는 텍스트 컴포넌트에 붙이는 작은 스크립트(키를 인스펙터에 적어 두고, 켜질 때와 언어 변경 이벤트 때 GetString 을 불러 대입)를 하나 만들어 모든 고정 문구에 붙이는 방식이 일반적입니다.

GetString 의 실패는 조용하다

상황	돌아오는 문자열	화면에 이것이 보이면
키가 사전에 없다	<NoKey>ui.start_button	사전에 키를 추가하지 않았거나, 사전 로드가 끝나기 전에 불렀다
{1} 이 있는데 인자를 하나만 줬다	<Error>ui.score,… 로 시작하는 긴 문자열	번역문의 자리표시자 개수와 코드의 인자 개수가 다르다

예외를 던지지 않으므로 게임은 멈추지 않습니다. 대신 QA 가 화면에서 눈으로 찾아야 합니다. 출시 전에 "모든 키가 모든 언어 사전에 있는가"를 검사하는 에디터 스크립트를 하나 만들어 두는 것이 좋습니다.

이 에디션에서 다른 점 · 본문을 읽을 때 주의할 점

•

본문은 "런타임 중에도 언어를 자유롭게 변경할 수 있습니다"라고 하지만, 위에서 보듯 Language 값만 바꿔서는 아무것도 달라지지 않습니다. 사전 교체와 화면 갱신은 직접 구현합니다.

•

Language 는 문자열이 아니라 열거형입니다. 본문의 Language = "Korean" 은 Language.Korean 으로 고쳐 두었습니다.

•

본문의 SetLocalizationHelper, SetResourceManager 는 LocalizationComponent 가 대신 합니다. 게임 코드는 GameEntry.GetComponent<LocalizationComponent>() 로 ReadData / GetString 만 부릅니다.

•

에디터에서는 BaseComponent 의 Editor Language 로 기기 언어와 무관하게 테스트 언어를 지정할 수 있습니다. 한국어 PC 에서 영어 화면을 확인할 때 씁니다.

•

사전 파일은 Addressables 에 등록한 TextAsset 이고, 기본 형식은 탭 구분 4열(2열 = 키, 4열 = 값)입니다. 빈 줄이나 열 수가 다른 줄을 만나면 그 자리에서 파싱이 중단됩니다.

Localization 시스템 개요

Game Framework의 Localization(다국어 지원) 시스템은 게임 내 텍스트를 다국어로 관리하기 위한 견고한 구조를 제공합니다.

이 시스템은 문자열을 딕셔너리(Dictionary) 형태로 저장하고, 고유 키(Key) 를 통해 조회하며, 문자열 포맷팅과 파라미터 지원이 가능합니다.

또한 Resource Management 시스템과 통합되어 언어 데이터(사전 파일) 를 로드하고, 런타임 중에도 언어를 자유롭게 변경할 수 있습니다.

시스템 구조

1. Dictionary 기반 구조

•

각 문자열은 고유 키(Key) 와 연결되어 저장됩니다.

•

현재 선택된 언어에 따라 해당 키에 맞는 문자열을 반환합니다.

핵심 구성 요소

LocalizationManager

•

ILocalizationManager 인터페이스를 구현하고 GameFrameworkModule을 상속하는 핵심 클래스

•

로컬라이즈된 문자열 딕셔너리를 유지·관리

•

문자열 접근, 추가, 삭제 등의 기능 제공

언어(Language) 관리

속성/메서드	설명
Language	현재 게임에서 사용할 언어 설정/조회
SystemLanguage	시스템 언어를 ILocalizationHelper로부터 가져옴
SetLocalizationHelper(ILocalizationHelper)	플랫폼별 언어 기능 지원 헬퍼 설정

ILocalizationHelper는 플랫폼별로 시스템 언어 감지, 로컬라이제이션 데이터 로드 로직 등을 구현하는 역할

로컬라이즈 문자열 조회

1. 기본 조회

string text = localizationManager.GetString("ui.start_button");

복사

2. 포맷팅 지원

string text = localizationManager.GetString("ui.score", 100);
// ui.score = "점수: {0}" → "점수: 100"

복사

딕셔너리 관리 기능

메서드	설명
HasRawString(string key)	특정 키 존재 여부 확인
GetRawString(string key)	포맷팅 전 원본 문자열 조회
AddRawString(string key, string value)	새로운 문자열 추가
RemoveRawString(string key)	특정 문자열 삭제
RemoveAllRawStrings()	모든 문자열 초기화

데이터 로딩

LocalizationManager는 Data Provider를 사용해 사전 파일을 로드·파싱합니다.

메서드	설명
ReadData(string dictionaryAssetName)	리소스 시스템에서 언어 사전 파일 로드
ParseData(string/byte[])	문자열 또는 바이트 배열로 된 사전 데이터 파싱

플로우 차트

다른 시스템과 연동

•

Resource Manager

→ 로컬라이제이션 사전 파일을 리소스로 로드

→ SetResourceManager(IResourceManager) 로 연결

•

Data Provider System

→ 사전 데이터 파싱

→ SetDataProviderHelper(IDataProviderHelper<ILocalizationManager>) 로 설정

일반적인 사용 흐름

게임 시작 시 LocalizationManager 초기화

SetLocalizationHelper()로 헬퍼 등록

SetResourceManager()로 리소스 매니저 연결

언어 선택 (예: localizationManager.Language = Language.Korean — 문자열이 아니라 Language 열거형이다)

ReadData()로 해당 언어 사전 로드

GetString()으로 UI나 게임 내 텍스트 출력

다른 데이터 시스템과 비교

시스템	목적	주요 기능
Localization	다국어 문자열 관리	키 기반 조회 + 포맷팅 지원
Config	전역 설정 관리	타입별 Getter(GetBool, GetInt 등)
DataTable	구조화된 게임 데이터 관리	강타입 데이터 행(Row) 관리

에러 처리

•

존재하지 않는 키 → <NoKey>{key} 반환

•

문자열 포맷 실패 → 예외 내용을 포함한 에러 문자열 반환

Best Practices

•

게임 초기 단계에서 Localization 시스템 초기화

•

문자열 사용 전에 반드시 언어 설정

•

키는 의미 있고 계층적 구조로 작성 ("ui.main_menu.start_button")

•

UI 컴포넌트에서 누락된 키 처리 로직 구현

•

확장 메서드로 GetString() 호출을 간단히 만드는 것도 추천

결론

이 Localization 시스템을 사용하면 다국어 지원이 필요한 게임에서 언어별 문자열 관리, 런타임 언어 변경, 리소스 기반 로드까지 쉽게 구현할 수 있습니다.

특히 UI나 대사량이 많은 게임(스토리형, RPG, 글로벌 출시 예정작)에 매우 유용합니다.