Overview
com.111percent.percent-table-localization-extension
이게 뭔가요?
Important
Localization 패키지를 설치 후 Percent Table의 CSV, Code Generate를 실행하면 Localization.cs 파일을 생성하지 않고, 내부 로직에 따르도록 자동 설정합니다.
111Percent 표준 언어코드 를 기반으로 하며 Percent Table 에서 다루고 있는 Localization 데이터를 따로 분리하여 편리하게 사용할 수 있도록 제공하는 패키지입니다.
단축키
CTRL + L
: Localization Window를 엽니다. (Table Setting Window가 열려있다면 도킹됩니다.)
ALT + L
: Hierarchy에서 선택한 오브젝트들 중 TMP 컴포넌트가 존재하는 오브젝트들에 LocalizationText를 추가합니다.
CTRL + ALT + L
: BaseTMPFont Helper Window를 엽니다.
F5
: 모든 LocalizationText들을 대상으로 주입된 StringId로 Refresh합니다.
어떤 기능이 있나요?
모든 클래스들의 예제는 아래 코드에서 설명드리겠습니다.
PLocalization
- 코드에서 Localization 처리를 해야할 때 이 클래스의 메소드를 통해 사용합니다.
- LocalizationData의 기능들을 손쉽게 사용하도록 하는 형태의 static 클래스입니다.
- 모든 언어의
FontAsset
과FontAsset의 Preset Material들
을 제공 현재 적용된 언어
의 다양한 정보 제공- isoCode
ex) ko,ja,en
- FontAsset
- stringId를 인자로 받아 반환하는 Localization 데이터
- isoCode
- ChangeLanguage 메소드 제공
- 언어 변경 후 text 값까지 변경
- 모든 씬의 LocalizationText의 text값을 Refresh해주는 메소드 제공
- 특정 GameObject 안에 포함 된 LocalizationText의 text값을 Refresh해주는 메소드 제공
- 모든 언어의
BaseTMPFont
- LocalizationText가 상속받는 클래스입니다.
- TMP의 Font Asset, Material을 다룹니다.
- 이 컴포넌트를 사용하면 Localize 기능을 사용하지 않는 TMP들도
PLocalization.ChangeLanguage
를 호출했을 때 Font Asset과 Material을 변경할 수 있습니다.
LocalizationText
- TMP가 있는 오브젝트에서 사용할 수 있으며 아래 사진처럼 StringId를 입력 → Apply 과정을 거치면 손쉽게 데이터가 TMP.text에 주입됩니다.
- 새로 만든 TMP에
Alt + L
버튼을 누르면 손쉽게 이 클래스가 추가됩니다.
Caution
아래 Material이 없던 버전을 사용하시다가 업데이트 하셨다면, Localization Window에서
Refresh Material
을 진행해주시거나 FontAsset을 재갱신 부탁드립니다!
LocalizationData (ScriptableObject)
- ScriptableObject로 Generate 시에 적재된 데이터를 이 클래스가 관리합니다.
LocalizationDto
- Localization 테이블에 존재하는
모든 나라의 언어 데이터들
을 가진 Dto입니다.
FontMaterialDto
- 언어별 FontAsset의
Material
과Material 이름
을 가진 Dto입니다.
어떻게 사용하나요?
테이블 세팅 방법
- Localization 데이터와 파일 경로는 Percent Table의 테이블 규칙을 따릅니다.
- 위 표준 언어코드에 맞는 언어코드를 칼럼명으로 설정해주신 후에 데이터를 작성해주세요.
- 칼럼명 : 표준 언어코드의 표에서 코드 시트명 : Localization
에디터 세팅 방법
- 먼저 Table Setting Window에서 설정을 마친 후 Generate를 실행해주세요. (실행하신 적이 있다면 스킵하셔도 됩니다.)
CTRL + L
을 누르면 위와 같은 에러가 뜹니다.
PercentTableSetting.asset 파일과 동일한 위치에서
우클릭/Create/Table/Create Localization
을 클릭하여 LocalizationData를 생성합니다. 생성하면 위와 같이 메시지가 뜰 것입니다.2번 과정까지 완료되었다면 아래 사진에 보이는 Generate를 클릭하여 데이터를 적재합니다.
문제 없이 완료되었다면, 위와 같이 언어를 선택할 수 있는 창으로 변경되며, 각 언어에 해당하는 FontAsset을 설정합니다. (None일 경우 TMP Settings의 Default Font Asset으로 설정됩니다.)
언어 변경은 드롭다운으로 언어를 설정한 후 Apply를 누르면 적용됩니다. (Editor 한정입니다!)
여기까지의 과정을 따라오셨다면 Localization 세팅은 마무리되었습니다.
Text에 적용 방법
- Text로 사용할 TMP를 만듭니다.
Hierarchy
에서 Localization을 적용할 TMP들을 선택합니다.Alt + L
을 눌러LocalizationText
를 추가합니다.- 적용 할 StringId를 입력 후 Apply를 클릭합니다.
코드 사용 방법
using System.Collections.Generic;
using Percent.Table.Localization;
using Percent.LanguageCodes;
using Percent.Table.Localization.Dto;
using TMPro;
using UnityEngine;
public class LocalizationSample : MonoBehaviour
{
[SerializeField] LocalizationText _locText;
private void Start()
{
// StringId에 데이터가 있는 경우 설정된 언어의 String 반환
string data1 = PLocalization.GetCurrentLanguageString("Common_Menu");
// StringId가 없는 경우 파라미터의 String을 그대로 반환
string data2 = PLocalization.GetCurrentLanguageString("tjejejeq");
// 다른 언어의 String을 반환
string data3 = PLocalization.GetLanguageString("124", Languages.French);
if (_locText != null)
{
// PLocalization.GetCurrentLanguageString 값으로 TMP.text를 세팅 함
_locText.SetText("Common_Menu");
// PLocalization.GetLanguageString 값으로 TMP.text를 세팅 함
// 이 메소드를 사용하면 FontAsset, Material도 언어에 맞는 값들로 변경됩니다.
_locText.SetText("Common_Menu", Langueages.Korean);
var text = _locText.Text; // TextMeshProUGUI를 가져옴
}
// ------------------- 확장 기능 -------------------- //
// 모든 언어를 가지고 있는 Class Data를 반환
LocalizationDto data4 = PLocalization.GetLanguageData("Common_Pause");
// data를 받아와서 직접 뽑아올 수 있음
var data = data4.GetData(PLocalization.Language);
// data4의 Class Data를 Dictionary로 변환 후 반환
Dictionary<string, string> data5 = PLocalization.GetLanguageDataToDictionary("111");
// 현재 씬에 존재하는 모든 TMP들을 Refresh (특정 상황을 대비하여 제작)
PLocalization.RefreshComponent();
// 언어 변경하는 메소드, 이 메소드만 호출해주면 TMP.text들도 모두 변경됩니다.
PLocalization.ChangeLanguage(Languages.Albanian);
// ------------------- 확장 기능 -------------------- //
}
}
추가 기능
Material 기능 지원
Tip
2024년 상반기 작업의 경우 UI 작업이 거의 끝나가는 단계임을 확인했고 그에 따라 Material Preset과 LocalizationText의 Material 정보를 동기화하기 위해 아래 Helper를 제작하였습니다.
TMP의 Material Preset이 여러개일 경우 커스텀하게 사용하도록 하는 기능이 추가되었습니다.
그로 인해 LocalizationText에도 Custom Material을 사용할 수 있도록 GUI를 추가하였습니다.
Material Helper 기능 설명
Note
이 기능은 언어마다의 FontAsset이 다른 경우, 비슷한 Material 효과를 사용하려면 공통된 네이밍이 필요합니다.
예) Light로 맞춘다고 하면
Korean : MyKoFont Light
English : MyEnFont Light
Japanese : MyJaFont Light
Note
이 Helper를 사용하기 전, Localization Window의 새로 추가된 Refresh Material 클릭
, Font Asset을 재갱신
해주신 후에 PATCH해주시기를 권장드립니다.
- 동기화 시킬 Prefab이 모여있는 폴더의 Path를 지정합니다.
- 위 예시처럼 설정된 Material의 접미어를 설정합니다.
- Patch를 돌린 후에 수정 지점을 확인합니다.
BaseTMPFont
LocalizationText
의 부모 클래스인 BaseTMPFont
가 추가되었습니다.
BaseTMPFont
는 string 데이터를 제외한 Font Asset, Material만 언어에 따라 설정되도록 합니다.
BaseTMPFont
: Font Asset, Material을 설정 및 다룸
LocalizationText
: Localization으로 가공된 string 데이터를 세팅 함
Note
Font Asset, Material을 Localization에 설정된 언어와 동일하게 영향을 받고 싶은 TMP 오브젝트에 BaseTMPFont를 손쉽게 추가할 수 있는 Helper 기능을 제공합니다. Helper는 Inspector에서 멀티 컴포넌트 수정(여러 오브젝트 선택)를 지원하지 않아 추가한 기능입니다.
Helper 사용 방법
- Hierarchy에서 적용하고자 하는 TMP들을 선택한다.
- 여러 오브젝트를 선택하면 선택한 오브젝트 중 TMP가 달린 오브젝트만 선별됨
- TMP를 여럿 가진 부모 오브젝트 하나만 선택하여 자식 오브젝트들을 설정할 수는 없음, 각 개의 오브젝트로 설정
Ctrl + Alt + L
을 입력한다.- 동일하게 적용하고자 하는 세팅 값을 우측에서 설정
- Apply 버튼 클릭
해당 EditorWindow를 띄워놓은 상태로 스크립트 리로드 시 닫았다가 다시 열어주어야 합니다.
Exception
Exception명 | 내용 |
---|---|
InvalidCountryCodeException | 표준 언어코드에 맞는 데이터가 없는 경우 출력 |
LocalizationNotFoundException | Google sheet에 Localization 시트가 존재하지 않을 경우 출력 (EditorWindow 팝업과 같이 출력) |
새로운 기능
[1.1.1] ChangeLanguage 시 언어 변경을 강제하지 않는 방법
LocalizationText.SetText(stringId, isoCode)
를 호출해주시면, 그 텍스트는 ChangeLanguage가 호출되어도 메소드로 인해 세팅 된 언어로 유지합니다.[단, 언어 변경이 이루어지기 전 위 메소드가 한번은 호출이 되어야 합니다.]