특수 번역 작업을 위해 지역화 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)
end
TranslationHelper 모듈 만들기
플레이어의 기본 로케일에 따라 번역기를 로드할 때 코드를 재사용할 수 있습니다. 코드를 재사용하려면 플레이어의 기본 로케일에 따라 번역기를 안전하게 로드하는 도우미 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"