로컬라이제이션 시스템 (Localization System)
관련 소스 파일
Scripts/Runtime/Config/ConfigComponent.cs
Scripts/Runtime/Config/ConfigHelperBase.cs
Scripts/Runtime/Config/DefaultConfigHelper.cs
Scripts/Runtime/DataTable/DataRowBase.cs
Scripts/Runtime/DataTable/DataTableComponent.cs
Scripts/Runtime/DataTable/DataTableHelperBase.cs
Scripts/Runtime/DataTable/DefaultDataTableHelper.cs
Scripts/Runtime/Localization/DefaultLocalizationHelper.cs
Scripts/Runtime/Localization/LocalizationComponent.cs
Scripts/Runtime/Localization/LocalizationHelperBase.cs
로컬라이제이션 시스템은 Unity 게임에서 다국어 텍스트와 리소스를 관리하기 위한 포괄적인 솔루션을 제공합니다. 개발자는 사전(dictionary) 파일에 지역화된 문자열을 정의하고, 현재 언어 설정에 따라 런타임에서 이를 가져올 수 있습니다.
출처:
Scripts/Runtime/Localization/LocalizationComponent.cs
15-19
아키텍처 개요 (Architecture Overview)
로컬라이제이션 시스템은 게임 프레임워크 전반에서 사용되는 컴포넌트-헬퍼 패턴을 따르며, Unity에 특화된 구현과 핵심 프레임워크 로직을 분리합니다.
로컬라이제이션 시스템은 다음의 주요 컴포넌트들로 구성됩니다:
•
LocalizationComponent: 로컬라이제이션 시스템의 주요 인터페이스 역할을 하는 Unity MonoBehaviour 컴포넌트
•
ILocalizationManager: 로컬라이제이션 데이터와 로직을 관리하는 핵심 프레임워크 모듈
•
LocalizationHelperBase: Unity와 핵심 프레임워크 사이를 연결하는 추상 헬퍼 베이스 클래스
•
DefaultLocalizationHelper: 사전 파일을 읽고 시스템 언어를 감지하는 기본 헬퍼 구현
출처:
Scripts/Runtime/Localization/LocalizationComponent.cs 15-40
Scripts/Runtime/Localization/LocalizationHelperBase.cs 14-17
Scripts/Runtime/Localization/DefaultLocalizationHelper.cs 17-20
언어 지원 (Language Support)
시스템은 Language enum을 통해 다양한 언어를 지원하며, 이는 Unity의 SystemLanguage enum에 매핑됩니다.
DefaultLocalizationHelper는 이 매핑을 제공하며, 장치의 시스템 언어를 자동으로 감지합니다.
시스템은 40개 이상의 언어를 지원하며, 여기에는 다음이 포함됩니다:
•
영어
•
중국어 (간체 및 번체)
•
일본어
•
한국어
•
다양한 유럽 언어 (독일어, 프랑스어, 스페인어 등)
•
아랍어, 히브리어 및 기타 RTL(오른쪽에서 왼쪽으로 쓰는) 언어
출처:
Scripts/Runtime/Localization/DefaultLocalizationHelper.cs 30-82
Scripts/Runtime/Localization/LocalizationComponent.cs 43-55
사전 포맷과 로딩 (Dictionary Format and Loading)
로컬라이제이션 시스템은 지역화된 문자열이 포함된 사전 파일을 로드합니다.
이 파일들은 텍스트 형식(.txt) 또는 바이너리 형식(.bytes) 일 수 있습니다.
텍스트 사전(.txt)
탭으로 구분된 4개 열 형식을 따릅니다:
1.
인덱스/식별자 (직접 사용되지 않음)
2.
사전 키 (문자열 식별자)
3.
빈 열 (향후 사용 예약)
4.
지역화된 문자열 값
예:
# Key Type Value
1 GAME_TITLE String My Awesome Game
2 MENU_START String Start
3 MENU_OPTIONS String Options
Plain Text
복사
바이너리 사전(.bytes)
더 빠른 로딩을 위해 키-값 쌍이 이진 형식으로 저장됩니다.
출처:
Scripts/Runtime/Localization/DefaultLocalizationHelper.cs 93-216
Scripts/Runtime/Localization/DefaultLocalizationHelper.cs 22-24
사용법 (Usage)
초기화 및 언어 설정
LocalizationComponent는 Unity 시작 프로세스에서 자동으로 초기화됩니다.
기본적으로 시스템 언어를 사용하지만, 변경할 수도 있습니다:
// 현재 언어 가져오기
Language currentLanguage = GameEntry.Localization.Language;
// 언어를 영어로 변경
GameEntry.Localization.Language = Language.English;
C#
복사
출처:
Scripts/Runtime/Localization/LocalizationComponent.cs 43-55
사전 파일 로딩
사전 파일은 Resource 컴포넌트를 통해 로드할 수 있습니다:
// 기본 사전 파일 로드
GameEntry.Localization.ReadData("Dictionaries/Default");
// 우선순위를 지정해 로드
GameEntry.Localization.ReadData("Dictionaries/UI", 100);
// 사용자 데이터를 포함해 로드
GameEntry.Localization.ReadData("Dictionaries/Items", userData);
C#
복사
출처:
Scripts/Runtime/Localization/LocalizationComponent.cs 184-219
지역화된 문자열 가져오기
사전 키를 사용하여 문자열을 가져올 수 있습니다:
// 단순 문자열 가져오기
string title = GameEntry.Localization.GetString("GAME_TITLE");
// 키 존재 여부 확인
bool hasKey = GameEntry.Localization.HasRawString("MENU_START");
C#
복사
또한 매개변수를 이용한 문자열 포매팅도 지원합니다:
// 매개변수 1개
string welcome = GameEntry.Localization.GetString("WELCOME_MESSAGE", playerName);
// 매개변수 여러 개
string itemInfo = GameEntry.Localization.GetString("ITEM_INFO", itemName, itemLevel, itemRarity);
C#
복사
출처:
Scripts/Runtime/Localization/LocalizationComponent.cs 293-728
Scripts/Runtime/Localization/LocalizationComponent.cs 733-738
다른 시스템과의 통합 (Integration with Other Systems)
로컬라이제이션 시스템은 다른 게임 프레임워크 시스템들과 매끄럽게 작동하도록 설계되었습니다:
•
리소스 시스템: 사전은 ResourceComponent를 통해 로드됨
•
이벤트 시스템: 사전 로딩 상태에 대한 이벤트 발생
•
UI 시스템: UI 컴포넌트에서 지역화 문자열 사용 가능
•
데이터테이블 시스템: 데이터 테이블이 지역화 문자열 키를 참조 가능
출처:
Scripts/Runtime/Localization/DefaultLocalizationHelper.cs 224-236
Scripts/Runtime/Localization/LocalizationComponent.cs 104-141
사전 관리 (Dictionary Management)
로컬라이제이션 시스템은 다음을 지원합니다:
•
게임의 서로 다른 부분에 대해 여러 사전 로드
•
문자열 또는 바이트 배열에서 사전 데이터 파싱
•
사전 키 존재 여부 확인
•
로드된 사전 개수 확인
더 이상 필요 없는 사전은 ResourceComponent를 통해 정리됩니다.
메모리 관리
•
EnsureCachedBytesSize로 사전 데이터 메모리 사전 할당
•
FreeCachedBytes로 불필요할 때 메모리 해제
•
컴포넌트가 파괴될 때 사전 리소스 자동 언로드
출처:
Scripts/Runtime/Localization/LocalizationComponent.cs 162-179
Scripts/Runtime/Localization/DefaultLocalizationHelper.cs 224-226
문자열 매개변수와 포매팅 (String Parameters and Formatting)
최대 16개의 매개변수를 지원하여 동적 텍스트 처리가 가능합니다.
메서드 | 설명 |
GetString(key) | 매개변수 없는 문자열 |
GetString(key, arg) | 매개변수 1개 |
GetString<T1, T2>(key, arg1, arg2) | 매개변수 2개 |
… | … |
GetString<T1...T16>(key, arg1...arg16) | 매개변수 최대 16개 |
예:
사전 항목 "WELCOME_PLAYER" = "Welcome, {0}! You have {1} gold."
string message = GameEntry.Localization.GetString("WELCOME_PLAYER", playerName, goldAmount);
C#
복사
출처:
Scripts/Runtime/Localization/LocalizationComponent.cs 293-728
모범 사례 (Best Practices)
•
사전을 논리적으로 구성: UI, 아이템, 대화 등 영역별로 분리
•
명확한 키 네이밍: UI_, ITEM_, DIALOG_ 같은 접두어 활용
•
필요한 시점에만 로드: 게임 구역 진입 시 로드, 이탈 시 언로드
•
자주 쓰는 문자열은 캐싱: GetString 반복 호출 최소화
•
누락된 번역 처리: HasRawString으로 키 존재 확인 후 사용
•
폴백 언어 설정: 번역이 없는 경우 더 완전한 언어로 대체
출처:
Scripts/Runtime/Localization/LocalizationComponent.cs 733-738
Scripts/Runtime/Localization/LocalizationComponent.cs 184-219
요약 (Summary)
로컬라이제이션 시스템은 Unity 게임에서 다국어 텍스트를 관리하기 위한 강력한 솔루션을 제공합니다.
컴포넌트-헬퍼 패턴을 따름으로써 Unity 전용 코드와 핵심 로직을 깔끔하게 분리하여 유연하고 확장 가능합니다.
이 시스템은 여러 사전을 로드할 수 있고, 다양한 언어를 지원하며, 강력한 문자열 포매팅 기능을 제공합니다.
또한 Resource 시스템과의 통합으로 로컬라이제이션 데이터의 효율적인 로드 및 언로드가 보장됩니다.