[TIL]유니티 커스텀 로컬라이제이션 시스템 구축 및 디버깅

오늘은 직접 만든 CSV 기반 로컬라이제이션 시스템을 프로젝트에 적용하고, 실제 작동시키면서 발생한 여러 문제를 해결하는 과정을 거쳤다. 이 과정을 통해 시스템의 원리를 더 깊게 이해할 수 있었다.

1. 로컬라이제이션 시스템의 전체 구조

오늘 완성한 시스템은 세 가지 핵심 스크립트로 구성된다.

• LocalizationConverter.cs: Resources/CSV 폴더에서 UILocalization.csv 파일을 찾아, 그 내용을 파싱하여 메모리에 '번역 사전' 형태로 저장하는 데이터 처리기.
• LocalizationController.cs: 게임 전체에 단 하나만 존재(싱글톤)하며, 파싱된 번역 사전을 들고 있는 중앙 관리소. DontDestroyOnLoad로 씬이 바뀌어도 유지된다.
• UITextLocalizer.cs: 번역이 필요한 각 TextMeshPro 오브젝트에 붙는 요청자 컴포넌트. Key 값을 가지고 있다가 LocalizationController에 번역을 요청하고, 언어가 변경되면 자동으로 텍스트를 갱신한다.

2. 마주했던 문제와 해결 과정 (디버깅)

시스템이 처음에는 예상대로 작동하지 않았지만, 몇 가지 디버깅 과정을 통해 원인을 찾아 해결했다.

• 문제 1: UITextLocalizer가 LocalizationController를 찾지 못하는 오류 (Instance가 없습니다!)
  • 원인: Hierarchy 씬에 LocalizationController 컴포넌트를 가진 게임 오브젝트가 없었기 때문.
  • 해결: 빈 게임 오브젝트를 생성하고 LocalizationController를 붙여주어 문제를 해결했다.
• 문제 2: 컨트롤러는 찾았지만, KEY에 해당하는 번역문을 찾지 못하고 KEY 값 자체가 출력되는 현상.
  • 원인: LocalizationConverter가 UILocalization.csv 파일의 내용을 제대로 읽지 못해, 번역 사전이 텅 비어있는 상태였다.
  • 디버깅: Debug.Log를 코드 곳곳에 추가하여 데이터 흐름을 추적했다.
  • 최종 원인: CSV 파일에 **헤더(제목 줄)**가 포함되어 있었고, 코드의 파싱 로직이 이 헤더를 보고 번역 파일이 아니라고 판단하여 건너뛰고 있었다. (이전에는 헤더를 삭제하라고 했으나, 최종적으로는 헤더를 인식하고 건너뛰는 코드로 수정하여 해결)
• 문제 3: (과거) Unity 공식 로컬라이제이션 패키지 사용 시도 중 발생한 오류
  • 오류: No Locale could be selected, InvalidKeyException: Key=Locale 등.
  • 원인: 로컬라이제이션 데이터(Locale, String Table)가 어드레서블(Addressables) 시스템에 제대로 등록되지 않았기 때문.
  • 해결: Addressables Groups 창에서 New Build를 실행하여 데이터 주소록을 생성/갱신해주어야 한다는 것을 배웠다.

오늘의 결론

단순히 코드를 짜는 것을 넘어, 데이터(CSV)와 시스템(C#), 그리고 엔진의 기능(Resources 폴더)이 어떻게 상호작용하는지 직접 경험하며 배울 수 있었다. 특히 Debug.Log를 통해 눈에 보이지 않는 코드의 작동 흐름을 추적하고, 문제의 원인을 단계적으로 좁혀나가는 디버깅의 중요성을 체감했다. 이제 이 시스템을 기반으로 게임의 모든 텍스트를 효율적으로 관리할 수 있게 되었다.