앙박의 기술서 [ Unity ] #Localization

Unity에는 게임 다국어 지원 패키지인 Localization이 있습니다. 언어마다 대응될 번역본/폰트/이미지/오디오 등은 개발자가 직접 준비해야 하며, 패키지는 단지 언어 설정 기능과 그에 따른 게임 컴포넌트 자동 변경 기능을 제공합니다.

1. 다운로드

Unity Localization은 유니티에서 제공하는 패키지입니다. Package Manager에서 "Install package by name"을 클릭하고 "com.unity.localization"을 기입한 후 Install 버튼을 누르면 다운로드 할 수 있습니다.

2. 지원하고싶은 언어 세팅

UnityEditor 상단 메뉴에서 Edit > ProjectSettings > Localization > Add Locale > 원하는 언어 선택 > Add Locale 해주시면 게임에서 지원하고싶은 언어들을 등록할 수 있습니다.

3. 언어별 번역본 세팅

UnityEditor 상단 메뉴에서 Window > Asset Management > Localization Tables > New Table Collection > 원하는 언어 선택 > String Table Collection > Create 순으로 누르면 언어별 텍스트를 할당할 수 있는 테이블이 등장합니다.

Table은 CSV로 Export 할 수 있습니다. 만약 따로 번역가한테 외주를 맡기는 경우 CSV(With Comments)로 Export해 추가 설명을 넣을 수 있습니다.

CSV는 Excel로 열람할 수 있습니다. 처음에는 인코딩 호환 때문에 깨져보일 수도 있는데 그럴 경우 Excel의 인코딩 설정을 변경해주면 됩니다. id가 달라지면 Export/Import에 문제가 생기니 건드리면 안 됩니다.

번역본이 업데이트 되면 다시 Table UI로 돌아와 새로운 번역본을 Table로 Import 해주면 됩니다.

4. 언어별 에셋(오디오/이미지/폰트 등) 세팅

UnityEditor 상단 메뉴에서 Window > Asset Management > Localization Tables > New Table Collection > 원하는 언어 선택 > Asset Table Collection > Create 순으로 누르면 언어별 에셋을 할당할 수 있는 테이블이 등장합니다. 폰트/이미지/오디오 등 다양한 유니티 에셋을 언어별로 지정할 수 있습니다.

폰트의 경우 Google Fonts에서 언어별 폰트를 다운로드 받을 수 있습니다. 이미지/오디오 같은 경우는 국가에 따라 예민하게 반응할 수 있는 요소를 제거해야 합니다.

인스펙터의 TextMeshPro 컴포넌트에 마우스를 올린 후 우클릭을 누르면 Localize 탭이 등장합니다. 클릭시 하단에 Localize String Event 컴포넌트가 추가되며, String Reference에서 원하는 Text를 선택해주시면 됩니다.

프로퍼티도 Localize가 가능합니다. TextMeshPro 컴포넌트의 프로퍼티 중 하나인 Font 위에 마우스를 올린 후 우클릭하면 Localize Property탭이 등장합니다. 클릭시 Game Obejct Localizer 컴포넌트가 하단에 추가되며 원하는 Font Asset을 선택해주시면 됩니다.

한 가지 주의할 점이, 위처럼 Text와 Font를 따로 Localize할 시 순서가 뒤섞여 결국엔 글자가 깨져서 출력됩니다. 따라서 우선적으로 폰트를 로드한 다음에 텍스트를 변경해주는 스크립트를 직접 작성해줘야 합니다.

using UnityEngine;
using TMPro;
using UnityEngine.Localization;
using UnityEngine.Localization.Settings;
using UnityEngine.ResourceManagement.AsyncOperations;

namespace WF.Common.Localization
{
    public class LocalizedTMPHandler : MonoBehaviour
    {
        [Header("References")]
        [SerializeField] private TMP_Text targetText;
        [SerializeField] private LocalizedAsset<TMP_FontAsset> localizedFont;
        [SerializeField] private LocalizedString localizedString;

        private void OnEnable()
        {
            ApplyLocalizedContent();
            LocalizationSettings.SelectedLocaleChanged += OnLocaleChanged;
        }

        private void OnDisable()
        {
            LocalizationSettings.SelectedLocaleChanged -= OnLocaleChanged;
        }

        private void OnLocaleChanged(UnityEngine.Localization.Locale locale)
        {
            ApplyLocalizedContent();
        }

        private async void ApplyLocalizedContent()
        {
            if (targetText == null) return;

            // 1️. 폰트 로드 완료 대기
            var fontHandle = localizedFont.LoadAssetAsync();
            await fontHandle.Task;
            TMP_FontAsset newFont = fontHandle.Result;

            // 2️. 폰트 적용
            targetText.font = newFont;
            targetText.fontMaterial = newFont.material;
            targetText.fontSharedMaterial = newFont.material;


            // 3️. LocalizedString 로드
            // 최신 버전에서는 GetLocalizedStringAsync(IAsyncOperationHandle parentHandle = default) 필요
            AsyncOperationHandle<string> textHandle = localizedString.GetLocalizedStringAsync();
            string localizedText = await textHandle.Task;
            targetText.text = localizedText;

            // 4️. TMP 강제 리빌드
            targetText.ForceMeshUpdate();
            Canvas.ForceUpdateCanvases();
        }
    }
}

5. 디버깅

Play 버튼을 누르면 Game 탭의 우측 상단에 언어 선택 탭이 생깁니다. 그 탭에서 언어를 선택하면 그에 따라 Localize가 실시간으로 적용됩니다.

앙박록