특수 번역 작업을 위해 지역화 API를 사용하여 지역화 테이블에 번역 추가로 자동 처리되지 않는 작업을 처리할 수 있습니다. Roblox는 모든 지역화 스크립팅 요구 사항을 처리하기 위해 LocalizationService를 제공합니다. 다음 작업을 위해 LocalizationService를 사용하십시오:
게임을 번역할 때 어떤 지역화 API를 사용하는 경우, 사용자의 LocaleID에 대한 변경 사항을 듣고 사용자가 언어를 전환하는 것에 반응해야 합니다.
번역 코드를 재사용할 때는 오류 처리 및 누락된 번역을 처리하기 위해 TranslationHelper ModuleScript 를 사용해야 합니다.
이미지 및 사운드 지역화
사용자의 로케일에 따라 고유한 이미지와 사운드를 제공함으로써 게임에서 텍스트를 넘어서는 지역화를 추가하십시오. 자산을 지역화하려면 먼저 게임의 지역화 테이블에 출처 및 대상 자산 ID를 추가한 후, 지역화 API를 사용하여 다양한 자산을 가져옵니다.



이미지와 사운드를 지역화하는 시작하려면, 출처 및 대상 자산 ID를 지역화 테이블에 추가하십시오. 지역화 테이블에 대한 자산 ID 항목에는 API에서 호출할 수 있는 식별자로서 Key가 포함되어야 합니다.
다음은 자산 ID를 사용하는 지역화 테이블의 예시 항목입니다:
| Key | Source | es | pt |
|---|---|---|---|
| Key_JewelsImage | 2957093606 | 2957093671 | 2957093727 |
다음 코드는 ImageLabel의 자산 ID를 지역화 테이블에 제공된 스페인 자산 ID로 바꿉니다:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- 로컬 변수
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- "es"의 번역기 로드. 실패를 방지하기 위해 pcall()로 함수를 래핑합니다.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Key를 참조하여 지역화 테이블에서 자산 ID 가져오기
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- 이미지 설정
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('GetTranslatorForPlayerAsync 실패: ' .. translator)
end개별 문자열 번역
일부 상황에서는 개별 문자열을 번역하기 위해 대상할 수 있습니다. Translator:Translate()는 원본 문자열을 기반으로 지역화 테이블에서 개별 항목을 가져올 수 있습니다.
다음 예제에서는 다음 지역화 항목이 사용됩니다:
| Source | es | es | pt |
|---|---|---|---|
| Screen | Pantalla | 295093671 | 2957093727 |
다음 스크립트는 "Screen"의 스페인어 번역을 Output 창에 인쇄합니다:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- "es"의 번역기 로드. 실패를 방지하기 위해 pcall()로 함수를 래핑합니다.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Translate 함수를 사용하고 객체 컨텍스트 및 문자열 제공
local sourceTranslation = translator:Translate(game, "Screen")
print(sourceTranslation) -- 예상 출력: "Pantalla"
else
print('GetTranslatorForPlayerAsync 실패: ' .. translator)
end컨텍스트 오버라이드 사용
동일한 문자열이 여러 의미를 가질 수 있는 경우가 있습니다. 예를 들어, "Screen"이라는 단어는 컴퓨터 화면과 창 화면을 모두 나타낼 수 있지만, 스페인어 번역은 완전히 다릅니다.
지역화 테이블의 Context 열은 컨텍스트 오버라이드를 통해 번역을 지정하는 데 사용됩니다. 다음 예제와 같이 지역화 테이블에서 게임 내 객체를 지정합니다:
| Context | Source | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Screen | Mosquitero |
| Screen | Pantalla |
다음 스크립트는 특정 번역의 우선 순위를 지정하기 위해 컨텍스트 오버라이드를 사용합니다:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- "es"의 번역기 로드. 실패를 방지하기 위해 pcall()로 함수를 래핑합니다.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Translate 함수를 사용하고 객체 컨텍스트 및 문자열 제공
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
print(sourceTranslation) -- 예상 출력: Mosquitero
else
print('GetTranslatorForPlayerAsync 실패: ' .. translator)
end여러 컨텍스트
여러 컨텍스트의 경우, 지역화 서비스는 오른쪽에서 왼쪽으로 Context 필드의 객체 관계를 비교하여 가장 가까운 일치를 사용합니다.
예를 들어, 게임의 지역화 테이블에는 다음과 같은 공유 Source 문자열 항목이 있을 수 있습니다:
| Context | Source | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Screen | Mosquitero |
| playerGui.ScreenGui.TextButton | Screen | Pantalla |
"Screen" 문자열이 게임의 playerGui.ScreenGui.TextLabel 객체에 추가되면, 지역화 서비스는 가장 가까운 컨텍스트 일치로 인해 스페인어 번역으로 "Mosquitero"를 표시합니다.
매개변수 대체
동적 콘텐츠를 번역할 때 매개변수를 사용할 때는 값을 테이블로 설정하고 API를 통해 테이블을 인수로 전달하십시오.
이 예제에서는 게임에 다음 항목이 있는 지역화 테이블이 있습니다:
| Key | Source | es |
|---|---|---|
| Key_Prize_1 | {1:int} jewels | {1:int} joyas |
| Key_Prize_2 | ${AmountCash:fixed} cash and {NumJewels:int} jewels | ${AmountCash:fixed} dinero y {NumJewels:int} joyas |
다음 코드를 사용하여 매개변수 값을 가진 이러한 문자열을 번역하십시오:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- "es"의 번역기 로드. 실패를 방지하기 위해 pcall()로 함수를 래핑합니다.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- "Key_Prize_1"의 매개변수 값을 100으로 설정
local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
print(keyTranslation1) -- 예상 출력: 100 joyas
-- 매개변수를 이름으로 500 및 100으로 설정
local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
print(keyTranslation2) -- 예상 출력: $500.00 dinero y 100 joyas
else
print('GetTranslatorForPlayerAsync 실패: ' .. translator)
end언어 전환
일부 경우에는 게임에서 다른 언어의 번역을 표시하고 싶을 수 있습니다. LocalizationService:GetTranslatorForLocaleAsync()를 사용하여 다른 국가 코드와 함께 새 번역기를 설정할 수 있습니다.
다음 코드 샘플은 수동 국가 코드를 사용하여 하나의 번역기를 설정하고, 사용자의 전역 로케일 설정에 기반한 추가 번역기를 설정합니다:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- 로컬 변수
local player = Players.LocalPlayer
-- "pt"의 번역기 로드. 실패를 방지하기 위해 pcall()로 함수를 래핑합니다.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- 플레이어의 로케일을 기반으로 두 번째 번역기 로드, 이 예제에서는 "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- 첫 번째 번역기를 사용하여 Translate 함수 사용
if res1 then
local translate1 = translator:Translate(game, "jewels")
print(translate1) -- 예상 출력 pt: joyas
else
print('GetTranslatorForPlayerAsync 실패: ' .. translator)
end
-- 두 번째 번역기를 사용하여 Translate 함수 사용
if res2 then
local translate2 = fallbackTranslator:Translate(game, "jewels")
print(translate2) -- 예상 출력, 사용자가 'es'로 설정된 경우: jóias
else
print('GetTranslatorForPlayerAsync 실패: ' .. fallbackTranslator)
end사용자가 언어를 전환하는 것에 반응
사용자는 게임 내 설정 메뉴를 사용하여 언제든지 언어 설정을 변경할 수 있습니다. 이 사용자 설정 변경은 자동 번역에 의해 처리되는 문자열과 같은 비스크립팅 지역화 자산을 자동으로 업데이트하지만, 이미 렌더링된 스크립트 지역화 변경(예: GUI 이미지 또는 사운드)은 업데이트되지 않을 수 있습니다.


스크립팅된 지역화 자산이 올바르게 업데이트되도록 하려면, LocalizationService.GetTranslatorForPlayerAsync로 반환된 Translator 인스턴스의 LocaleID 속성에 대한 변경 사항에 대해 GetPropertyChangedSignal 이벤트를 듣습니다. LocalizationService.GetTranslatorForPlayerAsync를 사용할 때는 오류 발생 시 pcall()로 함수를 래핑하십시오.
다음 코드 샘플은 사용자가 언어를 전환할 때 사용자와 번역기 인스턴스의 Locale ID를 인쇄합니다:
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- GetTranslatorForPlayerAsync가 성공하면 플레이어의 현재 로케일에 대한 Translator를 반환합니다.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- 플레이어의 로케일 ID의 변경이 감지되면 호출되는 함수
local function OnLocaleIdChanged()
print("번역기가 다음으로 변경되었습니다: " .. translator.LocaleId)
-- 플레이어의 새 언어로 지역화 API로 번역된 모든 자산을 여기에서 재번역해야 합니다.
end
-- GetTranslatorForPlayerAsync가 성공했는지 확인
if res then
-- 성공하면 여기에서 번역기를 사용하여 자산을 번역합니다.
-- 플레이어의 로케일 ID 변경으로 듣기
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('GetTranslatorForPlayerAsync 실패: ' .. translator)
endTranslationHelper 모듈 만들기
플레이어의 기본 로케일에 따라 번역기를 로드할 때 코드를 재사용할 수 있습니다. 코드를 재사용하려면 플레이어의 기본 로케일에 따라 번역기를 안전하게 로드하는 도우미 ModuleScript를 설정하고 특정 번역을 제공하는 함수와 언어 전환 기능을 포함해야 합니다.
다음 코드 샘플은 ReplicatedStorage에 ModuleScript로 복사할 수 있는 TranslationHelper를 구현합니다:
local TranslationHelper = {}
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- 로컬 변수
local player = Players.LocalPlayer
local sourceLanguageCode = "en"
-- 번역기 얻기
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
-- TranslationHelper.setLanguage 메서드를 생성하여 TranslationHelper에 대한 새 번역을 로드합니다.
function TranslationHelper.setLanguage(newLanguageCode)
if sourceLanguageCode ~= newLanguageCode then
local success, newPlayerTranslator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
end)
-- 새로운 것이 유효할 경우에만 현재 playerTranslator를 재정의합니다 (fallbackTranslator는 게임의 기본 언어로 남아 있습니다)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- 첫 번째 로드 또는 반환에 실패하거나 성공할 경우 fallback 번역기를 사용하는 Translate 함수를 생성합니다. 기본 객체를 일반 객체로 설정할 수도 있습니다.
function TranslationHelper.translate(text, object)
if not object then
object = game
end
if foundPlayerTranslator then
return playerTranslator:Translate(object, text)
end
if foundFallbackTranslator then
return fallbackTranslator:Translate(object, text)
end
return false
end
-- 첫 번째 로드 또는 반환에 실패하거나 성공할 경우 fallback 번역기를 사용하는 FormatByKey() 함수를 생성합니다.
function TranslationHelper.translateByKey(key, arguments)
local translation = ""
local foundTranslation = false
-- 먼저 플레이어의 언어에 대한 번역을 시도합니다 (번역기가 발견되면)
if foundPlayerTranslator then
foundTranslation = pcall(function()
translation = playerTranslator:FormatByKey(key, arguments)
end)
end
if foundFallbackTranslator and not foundTranslation then
foundTranslation = pcall(function()
translation = fallbackTranslator:FormatByKey(key, arguments)
end)
end
if foundTranslation then
return translation
else
return false
end
end
return TranslationHelper모듈이 ReplicatedStorage에 있으면 LocalScript에서 이를 요구하여 모듈의 함수를 호출합니다. 다음 코드는 이 모듈의 도우미 함수를 사용하여 개별 문자열을 번역합니다:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- 번역 모듈 요구
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))
-- TranslationHelper에서 제공하는 함수 사용
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- 예상 출력 'es': "Pantalla"