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

local LocalizationService = game:GetService("LocalizationService")

print(LocalizationService.ClientLocaleId)

SystemLocaleId

string

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

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

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

Code Samples

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

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

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

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

Localization