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");
C#
복사
2. 포맷팅 지원
string text = localizationManager.GetString("ui.score", 100);
// ui.score = "점수: {0}" → "점수: 100"
C#
복사
딕셔너리 관리 기능
메서드 | 설명 |
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>) 로 설정
일반적인 사용 흐름
1.
게임 시작 시 LocalizationManager 초기화
2.
SetLocalizationHelper()로 헬퍼 등록
3.
SetResourceManager()로 리소스 매니저 연결
4.
언어 선택 (예: localizationManager.Language = "Korean")
5.
ReadData()로 해당 언어 사전 로드
6.
GetString()으로 UI나 게임 내 텍스트 출력
다른 데이터 시스템과 비교
시스템 | 목적 | 주요 기능 |
Localization | 다국어 문자열 관리 | 키 기반 조회 + 포맷팅 지원 |
Config | 전역 설정 관리 | 타입별 Getter(GetBool, GetInt 등) |
DataTable | 구조화된 게임 데이터 관리 | 강타입 데이터 행(Row) 관리 |
에러 처리
•
존재하지 않는 키 → <NoKey>{key} 반환
•
문자열 포맷 실패 → 예외 내용을 포함한 에러 문자열 반환
Best Practices
•
게임 초기 단계에서 Localization 시스템 초기화
•
문자열 사용 전에 반드시 언어 설정
•
키는 의미 있고 계층적 구조로 작성 ("ui.main_menu.start_button")
•
UI 컴포넌트에서 누락된 키 처리 로직 구현
•
확장 메서드로 GetString() 호출을 간단히 만드는 것도 추천
결론이 Localization 시스템을 사용하면 다국어 지원이 필요한 게임에서 언어별 문자열 관리, 런타임 언어 변경, 리소스 기반 로드까지 쉽게 구현할 수 있습니다.
특히 UI나 대사량이 많은 게임(스토리형, RPG, 글로벌 출시 예정작)에 매우 유용합니다.