使用脚本本地化

您可以使用本地化 API 为特殊翻译任务，这些任务通常不会自动处理通过 添加翻译 到本地化表。 Roblox 提供一个 LocalizationService 来处理所有本地化脚本需求。使用 LocalizationService 为下列任务：

• 本地化图像和声音 .
• 翻译个人字符串的部分 .
• 应用多种语言的翻译结果 .

如果您使用体验的本地化 API 时，请听取用户的本地 ID 对应的任何变更，以便在体验中反应用户切换语言 。

使用翻译代验证码时，您应该使用一个 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() 可以根据源字符串从本地化表中获取单个条目。

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

以下脚本将打印“屏幕”的西班牙语翻译到 输出 窗口：

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 failed: ' .. translator)
end

使用上下文覆盖

在某些情况下，同一个字符串可能有多个意义。例如，“屏幕”这个字可以指示 both a 电脑屏幕 and a 窗口屏幕，但是西班牙语的翻译是完全不同的。

本地化表的 上下文 列用于通过上下文覆盖指定翻译。在本地化表的游戏对象上进行指定，如下示例所示：

以下脚本使用上下文覆盖来优先级特定翻译：

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( workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
	print(sourceTranslation) -- 期望输出：Mosquitero
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

多个上下文

在多个上下文中，本地化服务使用最接近的匹配方式在 右侧 和 左侧 中比较对象关系，使用最适合的匹配。

例如，您体验中的本地化表可能包含以下共享源字符串入口：

如果在您的体验中添加了 “屏幕” 字符串，本地化服务将 “Mosquitero” 作为最近上下文匹配的西班牙语翻译显示。

替换参数

使用参数来翻译 动态内容 时，将值设置为 表 ，并通过 API 传递表作为参数。

在此示例中，体验有一个 localization 表，其中包含以下内容：

使用以下代码示例来翻译这些参数值的字符串：

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 现金和 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)

-- 在此示例中，加载第二个 Translator 用“es”的本地语言
local res2, fallbackTranslator = pcall(function()
	return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- 使用第一个 Translator 的 Translate 函数
if res1 then
	local translate1 = translator:Translate(game, "jewels")
	print(translate1) -- 在 pt: joyas 期待的输出
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

-- 使用第二个翻译机与 Translate 函数
if res2 then
	local translate2 = fallbackTranslator:Translate(game, "jewels")
	print(translate2) -- 如果用户设置为“es”，期望输出：jóias
else
	print('GetTranslatorForPlayerAsync failed: ' .. fallbackTranslator)
end

反应于用户切换语言

用户可以使用他们的在体验中设置菜单更改他们的语言设置。此用户设置的更改会自动更新不是脚本的本地化资产，例如由 自动翻译 处理的字符串，但可能无法更新已经渲染完的脚本本地化更改，例如图形用户界面图像或声音。

要确保您的脚本本地化资产正确更新，请听取 GetPropertyChangedSignal 事件的更改，并在 Translator 实例返回的 Class.LocalizationService.GetTranslatorForPlayer

下面的代码示例打印用户的本地ID和用户当前处于翻译器实例的本地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

创建一个 TranslationHelper 模块

当您根据玩家的默认语言加载翻译时，您可能会重用代验证码。要重用验证码，请设置一个帮助器 ModuleScript ，它安全地加载翻译根据玩家的默认语言并包含提供特定翻译和切换语言的功能。

下面的代码示例实现了一个名为 ModuleScript 的 TranslationHelper ，你可以将其复制到你自己的项目作为 ReplicatedStorage 中的 Class.ModuleScript：

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 以加载一个新的翻译帮助器的新翻译
function TranslationHelper.setLanguage(newLanguageCode)
	if sourceLanguageCode ~= newLanguageCode then
		local success, newPlayerTranslator = pcall(function()
			return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
		end)

		--只有在新的玩家翻译器有效时（默认翻译器仍然是体验的源语言）
		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

一旦模块位于 ReplicatedStorage ，请从 LocalScript 调用模块的函数。以下代码使用此模块的帮助函数来翻译一个单个字符串：

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"