使用腳本進行本地化 | 文件 - Roblox 創作者中心

您可以使用本地化 API 進行一些專門的翻譯任務，這些任務無法通過添加翻譯到本地化表來自動處理。Roblox 提供了一個 LocalizationService 來處理所有本地化腳本需求。使用 LocalizationService 進行以下任務：

本地化圖片和聲音
翻譯單個字符串的一部分
應用多語言的翻譯

如果您在翻譯遊戲時使用任何本地化 API，請監聽用戶的 LocaleID 的任何更改，以便在遊戲中響應用戶切換語言。

在重複使用翻譯代碼時，您應該使用TranslationHelper 模組腳本來處理錯誤和缺失的翻譯。

本地化圖片和聲音

通過提供基於用戶語言的獨特圖片和聲音，為您的遊戲增添文本以外的本地化內容。要本地化資產，首先將源和目標資產 ID 添加到您的遊戲本地化表，然後使用本地化 API 獲取不同的資產。

要開始本地化圖片和聲音，將您的源和目標資產 ID 添加到本地化表中。資產 ID 條目在本地化表中必須包含 Key 作為 API 調用的標識符。

以下是使用資產 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

GetTranslatorForPlayerAsync() 和 GetTranslatorForLocaleAsync() 是異步的，並且可能由於連接不良或其他問題而偶爾失敗。建議創建TranslationHelper 模組腳本以捕獲錯誤並提供後備翻譯說明。

翻譯單個字符串

在某些情況下，您可能想要針對單個字符串進行翻譯。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

多個上下文

在多個上下文的情況下，本地化服務從右到左比較上下文欄位中的物件關係，使用最近的匹配。

例如，您遊戲中的一個本地化表可能具有以下共享 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 图片或声音。

為了確保您的腳本本地化資產能夠正確更新，請監聽 GetPropertyChangedSignal 事件，以便監聽 Translator 實例的 LocaleID 屬性的變化，該實例是由 LocalizationService.GetTranslatorForPlayerAsync 返回的。在使用 LocalizationService.GetTranslatorForPlayerAsync 時，將該函數包裝在 pcall() 中以防止錯誤。

以下代碼示例將打印用戶的 Locale ID 以及用戶切換語言時翻譯器實例的 Locale ID：


local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer

-- 如果 GetTranslatorForPlayerAsync 成功，將返回玩家當前語言的翻譯器
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，安全地根據玩家的默認語言加載翻譯器並包含提供特定翻譯和切換語言的功能。

以下代碼示例實現了一個 TranslationHelper，您可以將其複製到自己的項目中作為 ModuleScript 放置在 ReplicatedStorage 中：


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

-- 創建一個 Translate 函數，如果第一個加載或返回失敗，則使用 fallback 翻譯器。您還可以將引用的對象默認設置為通用對象

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

-- 創建一個 FormatByKey() 函數，如果第一個加載或返回失敗，則使用 fallback 翻譯器

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

如果您的遊戲源語言不是英語，請將 sourceLanguageCode 變量的值更改為遊戲源語言的國家代碼。

模組放在 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"