> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/localizationservice.md).

# 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 %}