# LocalizationService

LocalizationService : `Instance`

## Overview

LocalizationService는 게임 내 자동 번역(Auto Translation)과 클라이언트의 로케일/지역 정보를 제공하는 서비스 객체입니다.

월드당 하나만 존재하며, 직접 생성할 수 없는 서비스 타입으로 `game:GetService("LocalizationService")`를 통해서만 접근할 수 있습니다.

클라우드에 등록된 번역 테이블을 기반으로 특정 로케일에 대응되는 Translator 객체를 비동기적으로 제공하며, 플레이어의 국가/지역 코드 조회 기능도 함께 제공합니다.

지원되지 않는 언어 코드는 영어(`en`)로 fallback되며, 영어 계열(`en-us`, `en-gb`)은 `en`으로, 포르투갈어 계열(`pt-br`, `pt-pt`)은 `pt-br`로, 힌디어 계열(`hi-in`)은 `hi`로 prefix 기준 유사 매칭됩니다. 단, 클라이언트가 직접 노출하는 로케일 값(ClientLocaleId, Player.LocaleId)은 원래 디바이스/스튜디오 설정값을 그대로 반환하며, fallback은 Translator의 LocaleId에만 반영됩니다.

## Properties

### ClientLocaleId

`string`

로컬라이징에 사용되는 클라이언트 로케일 ID로 `en-us` 형식의 문자열을 반환하는 읽기 전용 속성입니다.

* 모바일 환경에서는 OVERDARE Player 앱의 표시 언어가 반환됩니다.
* 스튜디오 환경에서는 Studio Setting의 Language에서 설정한 언어가 반환되며, 별도 설정이 없으면 기본값은 `en-us`이고 에뮬레이터 사용 시 지정된 언어가 반환됩니다.

이 값은 클라이언트에서만 사용할 것을 권장하며, 서버에서는 유효하지 않은 값이 반환될 수 있습니다.

또한 동일 클라이언트에서 `LocalizationService.ClientLocaleId`와 `Translator.LocaleId`는 스튜디오/앱에서 설정한 언어와 동일한 값을 가집니다.

#### Code Samples

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

print(LocalizationService.ClientLocaleId)
```

### SystemLocaleId

`string`

로컬 플레이어의 운영체제(OS)에 설정된 로케일 ID로 `en-us` 형식의 문자열을 반환하는 읽기 전용 속성입니다.

ClientLocaleId가 앱/스튜디오에서 설정한 언어를 반영하는 것과 달리, SystemLocaleId는 기기 OS의 언어 설정을 반영합니다. 따라서 두 값은 서로 다를 수 있습니다.

이 값은 클라이언트에서만 사용할 것을 권장하며, 서버에서는 유효하지 않은 값이 반환될 수 있습니다.

#### Code Samples

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

print(LocalizationService.SystemLocaleId)
```

## Methods

### GetCountryRegionForPlayerAsync

플레이어의 클라이언트 IP 지리적 위치를 기반으로 국가/지역 코드 문자열을 반환합니다.

서버에 캐싱된 값이 존재할 경우 즉시 반환되며, 그렇지 않을 경우 외부 API 응답이 도착할 때까지 호출한 스크립트가 yield됩니다.

반환값은 `KR`, `BR`, `IN`과 같은 대문자 국가 코드 형식이며, 조회에 실패한 경우 빈 문자열이 반환될 수 있습니다.

이 메서드는 비동기로 동작하므로 반드시 스크립트(코루틴) 컨텍스트에서 호출해야 합니다.

#### Parameters

| `Instance` Player | 국가/지역 정보를 조회할 대상 플레이어입니다. |
| ----------------- | ------------------------- |

#### Return

| `string` | 대문자 국가/지역 코드(예: `KR`, `BR`, `IN`)입니다. |
| -------- | ------------------------------------- |

#### Code Samples

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

local function OnPlayerAdded(player)
    local region = LocalizationService:GetCountryRegionForPlayerAsync(player)
    print(player.Name, "is from", region)
end
Players.PlayerAdded:Connect(OnPlayerAdded)
```

### GetTranslatorForLocaleAsync

로케일 코드를 인수로 받아 해당 로케일을 위한 클라우드 번역 테이블이 로드될 때까지 대기하고, 사용 가능하다면 해당 로케일의 번역을 수행할 수 있는 Translator 객체를 반환합니다.

전달된 로케일이 지원되지 않는 경우 영어(`en`)로 fallback된 Translator가 반환되며, 영어 계열(`en-us`)/포르투갈어 계열(`pt-pt`)/힌디어 계열(`hi-in`)은 prefix 기준 유사 매칭이 적용됩니다.

동일 로케일에 대해 반복 호출하더라도 캐싱된 Translator 인스턴스를 그대로 반환합니다.

클라우드 번역 테이블이 아직 로드되지 않은 상태라면, 로드가 완료될 때까지 호출한 스크립트가 yield됩니다.

#### Parameters

| `string` Locale | 로케일 ID 문자열(예: `ko-kr`, `pt-br`, `hi-in`, `en`)입니다. |
| --------------- | -------------------------------------------------- |

#### Return

| `Translator` | 해당 로케일에 대응되는 Translator 객체입니다. |
| ------------ | ------------------------------ |

#### Code Samples

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

local translator = LocalizationService:GetTranslatorForLocaleAsync("ko-kr")
local translated = translator:Translate(game, "Hello, world!")
print(translated)
```

### GetTranslatorForPlayerAsync

플레이어를 인수로 받아 해당 플레이어가 운영체제에 설정한 로케일에 대한 클라우드 번역 테이블이 로드될 때까지 대기하고, 사용 가능하다면 해당 로케일의 번역을 수행할 수 있는 Translator 객체를 반환합니다.

내부적으로는 플레이어의 로케일 ID를 기준으로 GetTranslatorForLocaleAsync()와 동일한 방식으로 동작하며, 지원되지 않는 로케일은 `en`으로 fallback됩니다.

클라우드 번역 테이블이 아직 로드되지 않은 상태라면, 로드가 완료될 때까지 호출한 스크립트가 yield됩니다.

#### Parameters

| `Instance` Player | Translator를 가져올 대상 플레이어입니다. |
| ----------------- | --------------------------- |

#### Return

| `Translator` | 해당 플레이어 로케일에 대응되는 Translator 객체입니다. |
| ------------ | ----------------------------------- |

#### Code Samples

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

local function OnPlayerAdd(player)
    local translator = LocalizationService:GetTranslatorForPlayerAsync(player)
    print(translator:Translate(game, "Welcome!"))
end
Players.PlayerAdded:Connect(OnPlayerAdd)
```

## Events

## See also

{% content-ref url="/pages/s8jDFPa97Wp49c1BRCXN" %}
[Localization](/korean/manual/studio-manual/game-development/localization.md)
{% endcontent-ref %}


---

# 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/development/api-reference/classes/localizationservice.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.