# Localization

## 개요

Localization(현지화)은 다양한 언어를 사용하는 플레이어에게 동일한 경험을 제공하기 위한 기능입니다.

**월드 이름, 설명**과 같은 아웃게임 텍스트부터 월드 내 UI, 상호작용 메시지, 시스템 문구 등 **인게임 텍스트**까지 번역하여 표시할 수 있습니다.

이 기능을 활용하면 다양한 국가의 플레이어에게 자연스러운 경험을 제공할 수 있으며, 월드 접근성을 높여 **사용자 유입 확대**와 **수익 극대화**에 도움을 줄 수 있습니다.

## 특징

이 시스템은 다음과 같은 특징을 가집니다:

* UI, ProximityPrompt에 표시되는 텍스트를 자동으로 수집하여 크리에이터 허브에 등록
* 번역 데이터는 크리에이터 허브에서 통합 관리
* 등록된 번역 데이터를 기반으로 플레이어의 언어 설정에 따라 자동으로 번역 적용
* 스크립트를 통해 동적 텍스트도 번역 가능

## 지원 언어

현재 OVERDARE는 **영어, 힌디어, 포르투갈어(브라질)**를 지원합니다.

유사한 언어는 지원 언어로 자동 매칭됩니다. 예를 들어 영국 영어는 영어로, 유럽 포르투갈어는 브라질 포르투갈어로 매칭됩니다.

지원되지 않는 언어는 원문으로 표시될 수 있습니다.

| 언어         | 언어 코드   | 유사 언어 계열 예시        |
| ---------- | ------- | ------------------ |
| 영어         | `en`    | `en-us`, `en-gb` 등 |
| 힌디어        | `hi`    | `hi-in` 등          |
| 포르투갈어(브라질) | `pt-br` | `pt`, `pt-pt` 등    |

각 언어에 대한 번역 텍스트가 입력되지 않은 경우, 해당 항목은 기본 언어(원문)로 표시될 수 있습니다. 월드 활성화 및 사용자 경험에 영향을 줄 수 있으므로, **지원하는 모든 언어에 대해 번역 텍스트 입력을 권장합니다.**

## 사용 방법

1. Localization 기능은 월드를 **퍼블리시한 이후에 사용**할 수 있습니다.\
   (월드가 퍼블리시되지 않은 경우, 먼저 퍼블리시를 진행해야 합니다.)

   <figure><img src="/files/h2GquEsJeerpchGepWUM" alt=""><figcaption></figcaption></figure>
2. 스튜디오의 **Game Settings**의 **Localization 탭**에서 **자동 텍스트 수집(ATC)**&#xACFC; **번역 콘텐츠 사용**을 활성화합니다.\
   (Edit in Hub 버튼을 누르면 크리에이터 허브의 Localization 관리 페이지로 이동할 수 있습니다.)

   <figure><img src="/files/iAAAf0RLi8vQdlfj4D7F" alt=""><figcaption></figcaption></figure>
3. **플레이 테스트**를 실행합니다.
4. 테스트 중 UI 및 ProximityPrompt에 텍스트가 표시되면 해당 텍스트가 **수집 대상으로 자동 등록**됩니다.\
   (수집 과정은 내부적으로 처리되며, 한 번의 플레이 테스트에서 수집 가능한 텍스트 수에는 제한이 있습니다. 이 제한을 초과하면 추가 텍스트는 수집되지 않고 경고 로그가 출력됩니다.)
5. **플레이 테스트 종료 시**, 수집된 텍스트가 크리에이터 허브의 번역 테이블에 **자동으로 등록**되며, 지원하는 모든 언어에 대해 번역 항목이 함께 생성됩니다.

   <figure><img src="/files/2PYgB8zEdHlSkXeUti9w" alt=""><figcaption></figcaption></figure>
6. 등록된 텍스트는 크리에이터 허브에서 확인할 수 있으며, **각 언어별로 번역 텍스트를 입력**하고 관리할 수 있습니다.\
   (입력 후 **Save 버튼**을 눌러 저장해야 합니다.)

   <figure><img src="/files/50kM5JeEEq5rvYmiKnFl" alt=""><figcaption></figcaption></figure>
7. ATC로 수집이 어려운 저빈도 텍스트나 조건부 텍스트는 크리에이터 허브의 **Table Management 탭**에서 CSV를 통해 수동으로 등록할 수 있습니다.

   <figure><img src="/files/Rtx9iS3GZyZP2bewArqJ" alt=""><figcaption></figcaption></figure>
8. 월드 이름, 설명과 같은 월드 정보 데이터는 기본적으로 구성되어 있습니다.

   <figure><img src="/files/7Y2nBoV4gKzOO5IetecN" alt=""><figcaption></figcaption></figure>

## 번역 테스트

**Localization Preview**에서 언어를 선택하여 번역 결과를 확인할 수 있으며, 플레이 중에도 언어를 변경할 수 있습니다.

<figure><img src="/files/5klibLff78N9Bs0HPe1k" alt=""><figcaption></figcaption></figure>

## 상세

### 자동 텍스트 수집 (ATC)

스튜디오 환경에서 플레이 테스트 중 UI 또는 ProximityPrompt에 텍스트가 표시될 때 해당 텍스트는 자동으로 수집되며, 수집된 텍스트는 **플레이 종료 시** 크리에이터 허브의 번역 테이블에 등록됩니다.

#### **수집 대상**

* TextLabel, TextButton의 텍스트 속성 (Text)
* ProximityPrompt의 상호작용 텍스트 속성 (ActionText, ObjectText)

#### **수집 조건**

다음 조건을 만족하는 경우에만 텍스트가 수집됩니다.

* **자동 텍스트 수집(ATC)이 활성화**된 상태
* **스튜디오 환경의 플레이 테스트 상태** (모바일 환경에서는 수집되지 않습니다.)
* UI 또는 ProximityPrompt의 **AutoLocalize 속성이 활성화**된 경우
  * UI의 경우, 조상과 자식 UI 모두에서 AutoLocalize가 활성화된 경우에만 텍스트가 수집됩니다.

#### 동작 방식

* 화면에 표시되는 텍스트는 플레이 중 **실시간으로 수집**됩니다.
  * 허브의 Location 필드에는 텍스트가 수집된 경로가 StarterGui.ScreenGui.TextButton와 같은 형식으로 기록됩니다.
* 스크립트를 통해 **동적으로 할당된 텍스트**도 수집 대상에 포함됩니다.
* 이미 허브에 등록된 텍스트는 중복 등록되지 않습니다.
* 수집된 텍스트는 **플레이 종료**시 허브로 전송됩니다.

#### **수집 제한**

* 한 번의 플레이 테스트에서 수집 가능한 텍스트 수에는 제한이 있습니다.
* 제한을 초과하면 이후 텍스트는 수집되지 않으며, **경고 로그**가 출력됩니다.
* 루프 문에서 텍스트를 반복적으로 할당하는 등 과도한 텍스트 생성이 발생하는 경우, 구조를 점검한 후 플레이 테스트를 다시 실행해야 합니다.
* **수집이 불필요한 텍스트는 AutoLocalize 속성을 반드시 비활성화하세요.**

### 번역 텍스트 적용

플레이 테스트 중 UI 또는 ProximityPrompt에 텍스트가 표시될 때, 해당 텍스트가 크리에이터 허브에 등록되어 있고 번역된 텍스트가 존재하는 경우 자동으로 번역이 적용됩니다.

#### 번역 적용 **대상**

* TextLabel, TextButton의 텍스트
* ProximityPrompt의 상호작용 텍스트

#### 적용 조건

* **번역 콘텐츠 사용이 활성화**된 상태
* **스튜디오 환경의 플레이 테스트 상태 또는 모바일 환경에서 월드에 접속한 상태**
* UI 또는 ProximityPrompt의 **AutoLocalize 옵션이 활성화**된 경우
  * UI의 경우, 부모와 자식 UI 모두에서 AutoLocalize가 활성화된 경우에만 텍스트가 번역됩니다.

#### 수정 사항 반영 시점

* 번역 데이터의 변경 사항은 플레이 테스트 **재실행** 또는 월드 **재접속시 반영**됩니다.
* 모바일 환경에서는 변경 사항이 즉시 반영되지 않으며, **약 5분 정도 후**에 적용될 수 있습니다.

#### Context 기반 번역 적용 규칙

번역은 **Context 값**과 UI 또는 ProximityPrompt의 **위치**를 기준으로 다음과 같이 적용됩니다.\
(이 규칙은 Translate 메서드를 사용하는 경우에도 동일하게 적용됩니다.)

예를 들어 허브에 다음과 같이 등록되어 있을 때,

<table><thead><tr><th width="107.666748046875">원문(Source)</th><th width="117.3333740234375">번역 텍스트</th><th width="387.9998779296875">Context</th><th>비고</th></tr></thead><tbody><tr><td>강화</td><td>강화</td><td></td><td>기본 번역</td></tr><tr><td>강화</td><td>아이템 강화</td><td>PlayerGui.ScreenGui.ItemPopup.EnhanceButton</td><td>UI용 번역</td></tr><tr><td>강화</td><td>강화 몬스터</td><td>ServerStorage.Monster.NameTag.GradeLabel</td><td>몬스터용 번역</td></tr></tbody></table>

* Context가 **일치**하면 해당 번역이 적용됩니다.
  * UI 또는 ProximityPrompt의 경로가 PlayerGui.ScreenGui.ItemPopup.EnhanceButton이면,\
    -> **아이템 강화**가 적용됩니다.
* Context가 **일치하지 않으면** Source만 있는 번역(기본 번역)이 적용됩니다.
  * UI 또는 ProximityPrompt의 경로가 위 Context들과 모두 다르면,\
    -> 기본 번역인 **강화**가 적용됩니다.
* **기본 번역이 없으면** Context가 있는 번역이 적용될 수 있습니다.
  * 예를 들어 강화에 대한 기본 번역이 없고 Context 번역만 존재한다면,\
    -> **아이템 강화** 또는 **강화 몬스터**와 같이 Context 번역이 적용될 수 있습니다.

## 번역 데이터 관리

### Localization 페이지

스튜디오의 Game Settings의 Localization 탭에서 **Edit in Hub 버튼**을 누르면 크리에이터 허브의 Localization 관리 페이지로 이동할 수 있습니다.

<figure><img src="/files/NdPd4sFDFUzoaz48uiPL" alt=""><figcaption></figcaption></figure>

또는 크리에이터 허브의 Dashboard에서 월드를 선택한 뒤, **Localization 탭**으로도 접근할 수 있습니다.

<figure><img src="/files/M2xMi8vH8qsSOkGd5jf6" alt=""><figcaption></figcaption></figure>

### 번역 텍스트 관리

**Languages 탭**에서 언어를 클릭하면 해당 언어의 **월드 정보**와 **인게임 텍스트**의 번역을 관리할 수 있는 페이지로 이동합니다.

또는 **Translation Workspace 탭**으로도 이동할 수 있습니다.

<figure><img src="/files/eBWa3zLjGxHFxZ6tgHbs" alt=""><figcaption></figcaption></figure>

#### 월드 정보 관리

**Information 탭**에서 지원 언어별로 **월드 이름**(Name)과 **설명**(Description)의 번역 텍스트를 입력할 수 있으며, 수정 내역은 Translation History에 기록됩니다.

<figure><img src="/files/eohiOTk37eTO99zg2pKk" alt=""><figcaption></figcaption></figure>

#### 인게임 텍스트 관리

**Strings 탭**에서 지원 언어별로 인게임에서 사용되는 데이터의 번역 텍스트를 입력할 수 있으며, 수정 내역은 Translation History에 기록됩니다.

각 항목을 선택하면 등록된 데이터의 번역 내용을 수정하거나 삭제할 수 있습니다.

<figure><img src="/files/iZ8Opgp6yr5tU8HWciFU" alt=""><figcaption></figcaption></figure>

기본적으로 플레이 테스트 중 ATC를 통해 수집된 텍스트는 자동으로 등록되며, **Add Entry 버튼**을 통해 수동으로도 추가할 수 있습니다.

<figure><img src="/files/mNBjpCfGCyPBplUMSAQg" alt=""><figcaption></figcaption></figure>

수동 추가시 입력 필드는 다음과 같이 구성되며, 내용을 입력한 후 **Add 버튼**을 클릭하면 번역 항목이 등록됩니다.

동일한 원문을 가진 텍스트는 Context가 다를 때에만 중복 등록이 가능합니다.

<table><thead><tr><th width="167">이름</th><th width="364.6666259765625">설명</th><th>예시</th></tr></thead><tbody><tr><td>Text to translate</td><td>번역의 기준이 되는 원문 텍스트</td><td>Level</td></tr><tr><td>Key</td><td>번역 항목을 식별하기 위한 고유 값 (선택 입력)</td><td>UI_Text_Level</td></tr><tr><td>Context</td><td>텍스트가 사용되는 UI 위치 (선택 입력)</td><td>PlayerGui.PlayerHUD.TopFrame.Lv</td></tr><tr><td>Example</td><td>번역 참고를 위한 설명 (선택 입력)</td><td>플레이어 레벨 표시용 텍스트</td></tr></tbody></table>

### 설정 관리

**Settings 탭**에서 자동 텍스트 수집 및 번역 텍스트 적용 옵션의 활성화 여부를 설정할 수 있습니다.

설정한 옵션은 스튜디오와 연동되며, 스튜디오에서 변경한 설정도 허브에 동일하게 반영됩니다.

<figure><img src="/files/olgRaa9oP45afL4QcK8n" alt=""><figcaption></figcaption></figure>

### Table Management

**Table Management 탭**에서는 번역 데이터를 CSV로 다운로드하거나, CSV 업로드를 통해 수정할 수 있습니다.

저빈도 UI나 조건부 UI의 경우 ATC만으로는 수집이 어려울 수 있습니다. 이러한 경우 ATC에 의존하기보다는 필요한 데이터를 CSV에 미리 정의한 뒤 업로드하여 관리하는 것을 권장합니다.

<figure><img src="/files/muoFx9YqK3zu3w76TU5V" alt=""><figcaption></figcaption></figure>

* **Upload CSV**: CSV 파일을 업로드하여 인게임 텍스트와 번역 데이터를 추가, 수정할 수 있습니다. 기존 데이터를 기반으로 변경 사항만 반영됩니다.
* **Download CSV**: 현재 번역 테이블을 CSV 파일로 다운로드할 수 있습니다. 다운로드한 파일을 통해 번역 상태를 확인하거나, 수정 후 다시 업로드하여 사용할 수 있습니다.
* **Delete Table**: 번역 테이블에 등록된 모든 인게임 데이터를 삭제합니다. 이 작업은 되돌릴 수 없으므로 신중하게 사용하시기 바랍니다.

## 스크립트 기능

### 로케일 정보 확인

LocalizationService를 통해 플레이어 및 시스템의 언어 정보를 확인할 수 있습니다.

이를 활용하면 플레이어의 언어 설정이나 지역에 따라 다른 처리를 할 수 있습니다.

```lua
local LocalizationService = game:GetService("LocalizationService")

local PlayerLocaleId = Player.LocaleId -- 플레이어 계정에 설정된 언어
local ClientLocaleId = LocalizationService.ClientLocaleId -- 현재 클라이언트에서 사용 중인 언어
local SystemLocaleId = LocalizationService.SystemLocaleId -- 플레이어가 사용하는 기기의 OS 언어
local CountryRegion = LocalizationService:GetCountryRegionForPlayerAsync(Player) -- 플레이어의 접속 지역(국가 코드)
```

ClientLocaleId와 SystemLocaleId는 실행 환경의 로케일 값을 반환합니다. 클라이언트에서는 플레이어 기준으로 동작하지만 서버에서 사용할 경우 서버 기준 값이 반환됩니다.

따라서 플레이어별 로케일 처리가 필요한 경우 서버에서 사용하는 것은 권장하지 않습니다.

### Translator 가져오기

Translator는 특정 언어를 기준으로 번역을 수행하는 객체로, 번역 텍스트를 가져올 때 사용됩니다.

```lua
-- 플레이어의 언어 설정을 기준으로 Translator를 가져옵니다.
local Translator1 = LocalizationService:GetTranslatorForPlayerAsync(Player)
print(Translator1.LocaleId)

-- 특정 언어 코드를 기준으로 Translator를 가져옵니다.
local Translator2 = LocalizationService:GetTranslatorForLocaleAsync("en")
print(Translator2.LocaleId)
```

### 스크립트로 번역 처리

아이템 이름이나 레벨 등 변수 값에 따라 문장이 달라지거나, 동일한 텍스트라도 상황에 따라 다른 번역이 필요한 경우 스크립트를 통해 번역을 처리할 수 있습니다.

#### Key 기반 번역(FormatByKey)

FormatByKey는 Key를 기준으로 번역 텍스트를 가져오며, 문장 내에 치환이 필요한 값(아이템 이름, 레벨 등)은 Args를 통해 전달합니다.

아이템 이름, 레벨, 수량처럼 상황에 따라 문장이 달라지는 텍스트를 처리할 때 사용하기 적합합니다.

```lua
local Translator = LocalizationService:GetTranslatorForPlayerAsync(Player)

local Key = "ITEM_LEVEL_UP" -- 번역 데이터를 조회하기 위한 Key
local Args = { ItemName = "Sword", PrevLv = 1, NextLv = 2 } -- 문장에서 치환될 값
local TranslatedText = Translator:FormatByKey(Key, Args)

SomeUI.Text = TranslatedText
```

Args로 전달하는 각 값의 이름은 허브에 등록된 번역 데이터 내에서 사용하는 이름과 반드시 동일해야 하며, 필요한 항목의 개수 또한 일치해야 합니다.

<figure><img src="/files/uzhJttOINfQHPCz9xgJ4" alt=""><figcaption></figcaption></figure>

Args에 전달할 수 있는 데이터 타입은 다음과 같습니다.

* number
* string
* bool
* instance (name)
* CFrame
* Vector3
* Vector2
* Color3
* BrickColor
* MenuItem

#### Context 기반 번역(Translate)

```lua
local Translator = LocalizationService:GetTranslatorForPlayerAsync(Player)

local Context = PlayerGui.ScreenGui.ItemPopup.EnhanceButton -- 텍스트가 사용되는 경로 (Context)
local Source = "강화" -- 번역의 기준이 되는 원문 텍스트
local TranslatedText = Translator:Translate(Context, Source)

SomeUI.Text = TranslatedText
```

기본적으로 번역의 기준이 되는 텍스트는 중복될 수 없지만, Context가 다른 경우에는 각각 별도의 번역 데이터로 등록할 수 있습니다.

이를 통해 “강화”는 아이템 강화(Enhance), 스킬 강화(Upgrade), 강화된 적(Enchanted)처럼 상황에 따라 다르게 번역될 수 있으며, Context를 통해 이를 구분할 수 있습니다.

<figure><img src="/files/AN9AWC6kS4NNLfC1ToTr" alt=""><figcaption></figcaption></figure>

### LocalizedText로 원문 가져오기

LocalizedText는 현재 언어 기준으로 번역된 텍스트를 반환하는 속성입니다.

UI에 실제로 표시되는 번역 결과를 확인할 때 사용할 수 있습니다.\
(ProximityPrompt에서는 제공되지 않습니다.)

```lua
print(SomeUI.LocalizedText .. "(원문 : " .. SomeUI.Text .. ")")
```

## 활용 예시

* 월드 이름과 설명을 다양한 언어로 제공하면, 글로벌 사용자에게 월드를 효과적으로 노출하고 유입을 확대할 수 있습니다.
* UI, 버튼, 안내 메시지 등을 플레이어의 언어에 맞게 제공하면, 게임 이해도를 높이고 이탈률을 줄일 수 있습니다..
* 다국어 환경에서 문장 구조가 다른 경우에도, FormatByKey를 사용하면 각 언어에 맞는 자연스러운 문장을 구성할 수 있습니다.
* 동일한 텍스트라도 상황에 맞는 번역(Context)을 적용하면 보다 자연스러운 표현을 제공할 수 있어 사용자 경험을 개선할 수 있습니다.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overdare.com/korean/manual/studio-manual/game-development/localization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.