使用指令碼進行本地化

您可以使用本地化 API 為專用翻譯任務，這些任務不會自動處理在 添加翻譯 到本地化表中。 Roblox 提供一個 LocalizationService 來處理所有本地化腳本需求。使用 LocalizationService 為以下任務：

• 本地化圖像和聲音 .
• 翻譯個別字串的部分 .
• 應用多種語言的翻譯結果 .

如果您在翻譯體驗時使用任何本地化 API，請聽取使用者的語言 反應 在體驗中的用戶切換語言。

重用翻譯碼時，您應該使用 TranslationHelper ModuleScript 來處理錯誤和缺少的翻譯。

本地化圖像和聲音

通過提供基於用戶語言的獨特圖像和聲音來在您的體驗中提供本地化。若要本地化資產，請先添加 來源 和 目標 資產 ID 到您的體驗的 本地表 ，然後使用本地化 API 來擷取不同的資產。

要開始本地化圖像和聲音，請將 源 和 目標 添加到您的本地化表。在本地化表上，資產 ID 必須包含一個 鑰匙 作為識別子，才能由 API 呼叫。

下面是使用資產 ID 的本地化表示示例：

下列代碼將會將 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
	-- 從鑰匙的引用中取得資產 ID
	localizedImageID = translator:FormatByKey("Key_JewelsImage")
	-- 設定圖像
	localizedImage.Image = "rbxassetid://" .. localizedImageID
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

翻譯個別字串

在某些情況下，您可能想要為個別字串設定目標。Translator:Translate() 可以從本地化表中擷取個別項目，基於源字串。

下一個示例中，使用以下本地化入口：

下列指令將輸出 "Screen" 的西班牙語翻譯成 輸出 視窗：

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
	-- 使用「翻譯」功能，提供對象上下文和字串
	local sourceTranslation = translator:Translate(game, "Screen")
	print(sourceTranslation) -- 預期輸出：「Pantalla」
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

使用上下文重覆

有些情況下，相同的字串可能有多個意義。例如，「Screen」的意思可以指範圍的一個電腦螢幕，但西班牙語的翻譯是完全不同的。

本機翻譯桌的 上下文 柱可用來通過上下文覆蓋來指定翻譯。 在下列範例中，將本機翻譯桌的 對象 指定為遊戲中的對象：

下列指令碼使用上下文覆蓋來優先考慮特定的翻譯：

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
	-- 使用「翻譯」功能，提供對象上下文和字串
	local sourceTranslation = translator:Translate( workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
	print(sourceTranslation) -- 預期輸出：Mosquitero
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

多個上下文

在多個上下文中，本地化服務會比較對象關係在 右向左向 的上下文中，使用最接近的相符。

舉例來說，您的體驗中可能有以下共用源字串項目：

如果您在體驗中添加了「playerGui.ScreenGui.TextLabel」對象的「 Screen 」字串，本地化服務會顯示「Mosquitero」作為西班牙語的最佳語言，因為這是最接近上下文的語言。

參數替換

使用參數翻譯 動態內容 時，將值設為 表 並將表作為參數傳递給 API。

在這個範例中，體驗有一個本地化表，其中包含以下項目：

使用以下代碼示例來翻譯這些參數值的字串：

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 顆奧比亞

	-- 將多個參數設置為 500 和 100 按名
	local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
	print(keyTranslation2) -- 預期輸出：$500.00 現金和 100 顆珠寶
else
	print('GetTranslatorForPlayerAsync failed: ' .. 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)

-- 使用第一個翻譯機與第一個翻譯機
if res1 then
	local translate1 = translator:Translate(game, "jewels")
	print(translate1) -- pt:  joyas 的預期輸出
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

-- 使用第二個翻譯機與第一個翻譯機
if res2 then
	local translate2 = fallbackTranslator:Translate(game, "jewels")
	print(translate2) -- 如果使用者設為 'es' 預期輸出： jóias
else
	print('GetTranslatorForPlayerAsync failed: ' .. fallbackTranslator)
end

反應於切換語言的使用者

使用者可以使用他們的語言設定選單隨時變更語言設定。這項使用者設定的變更會自動更新非腳本化語言資產，例如由 自動翻譯 處理的字串，但可能無法更新已經渲染的腳本語言變更。這些語言變更可能會在 GUI 圖像或聲音等非腳本化語言變更後更新。

要確認您的程式碼本地化資產更新正確，請聆聽 GetPropertyChangedSignal 事件的變更，以便了解 Translator 實例由 Class.LocalizationService.

下列代碼示例列出了使用者的語言ID和譯者實例的語言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 has changed to: " .. translator.LocaleId)
	-- 您應該將本地化 API 翻譯的任何資產重新翻譯為玩家的新語言
end

-- 檢查 GetTranslatorForPlayerAsync 成功嗎
if res then
	-- 如果成功，請使用翻譯機在這裡翻譯資產
	-- 聆聽玩家的語言ID 變更
	translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

創建一個翻譯協助模組

當您載入基於玩家的預設語言的翻譯時，您可能會重用代碼。若要重用代碼，請設置一個名為 ModuleScript 的協助器，以安全地載入翻譯，並包含提供特定翻譯和切換語言的功能。

下列代碼示例實現了一個名為 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)

-- 創建 method TranslationHelper.setLanguage 以載入新的翻譯對應器
function TranslationHelper.setLanguage(newLanguageCode)
	if sourceLanguageCode ~= newLanguageCode then
		local success, newPlayerTranslator = pcall(function()
			return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
		end)

		--只有在新的玩家翻譯器有效 (fallbackTranslator 仍為體驗的源語言) 時才能覆蓋現有玩家Translator
		if success and newPlayerTranslator then
			playerTranslator = newPlayerTranslator
			return true
		end
	end
	return false
end

-- 如果第一個失敗載入或返回，創建一個使用預設翻譯器載入或返回的功能。你也可以將指定的對象設為一般遊戲對物件

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

-- 建立一個格式ByKey() 函數，如果第一個失敗載入或返回，使用備份翻譯器載入

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

once the module is in ReplicatedStorage , require it from a LocalScript to call the module's functions. The following code uses this module's helper function to translate an individual strin字串:

local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- 需要翻譯模組
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))

-- 使用TranslateHelper提供的功能
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Expected Output in 'es': "Pantalla"