Localizando com Scripting

Você pode usar APIs de localização para tarefas de tradução especializadas que não são automaticamente tratadas ao adicionar traduções à tabela de localização. O Roblox fornece um Class.LocalizationService para lidar com todas as necessidades de script de localização. Use o LocalizationService para as seguintes tarefas:

• Localizando imagens e sons.
• Traduzindo parte de cadeias individuais .
• Aplicando traduções de várias línguas .

Se você usar quaisquer APIs de localização ao traduzir sua experiência, ouça quaisquer alterações no LocaleID do usuário para reagir aos usuários que mudam de idioma enquanto estiver em uma experiência.

Ao reutilizar o código de tradução, você deve usar um Modulo de Script de Tradução Ajudante para lidar com erros e traduções faltando.

Localizando Imagens e Sons

Adicione localização além do texto em sua experiência fornecendo imagens e sons baseados no idioma de um usuário. Para localizar recursos, primeiro adicione os IDs de 源 e target de recursos à tabela de localização da sua experiência e depois use a API de localização para obter os diferentes recursos.

Para iniciar a localização de imagens e sons, adicione seus 源 e target recursos à sua mesa de localização. As entradas de ID de recursos na mesa de localização devem incluir um Key como um identificador para ser chamado pela API (Interface de Programação para Aplicações).

A seguir, um exemplo de entrada em uma tabela de localização usando IDs de recursos:

O seguinte código substituirá o ID de ativo de um ImageLabel com o ID de ativo espanhol fornecido na tabela de localização:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")

-- Variáveis locais
local localizedImageID
local localizedImage = Instance.new("ImageLabel")

-- Carregar Tradutor para "es". Wrap a função dentro de um pcall() para proteger contra falhas.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Obtenha o ID do recurso da tabela de localização ao referenciar a chave
	localizedImageID = translator:FormatByKey("Key_JewelsImage")
	-- Configure a imagem
	localizedImage.Image = "rbxassetid://" .. localizedImageID
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Traduzindo Cadeias individuais

Em alguns casos, você pode querer alvo de cadeias individuais para tradução. Translator:Translate() pode recuperar entradas individuais na tabela de localização com base na string / cadeia / textode origem.

No próximo exemplo, a seguinte entrada de localização é usada:

O seguinte script vai imprimir a tradução espanhola de "Screen" para a Output janela:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")

-- Carregar Tradutor para "es". Wrap a função dentro de um pcall() para proteger contra falhas.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Use a função Traduzir, fornecendo contexto de objeto e string / cadeia / texto
	local sourceTranslation = translator:Translate(game, "Screen")
	print(sourceTranslation) -- Saída esperada: "Pantalla"
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Usando Overrides de Contexto

Existem alguns casos em que a mesma string pode ter vários significados. Por exemplo, a palavra "Tela" pode indicar tanto uma tela de computador quanto uma tela de janela, mas as traduções espanholas são completamente diferentes.

A coluna Conteúdo da tabela de localização é usada para especificar traduções por meio de sub-redefinições de contexto. Especifique o objeto no jogo na sua tabela de localização como no seguinte exemplo:

O seguinte script usa uma覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查理覆檢查

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")

-- Carregar Tradutor para "es". Wrap a função dentro de um pcall() para proteger contra falhas.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- use a função Traduzir, fornecendo contexto de objeto e string / cadeia / texto
	local sourceTranslation = translator:Translate( workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
	print(sourceTranslation) -- Saída Esperada: Mosquito
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Múltiplos Contextos

No caso de múltiplos contextos, o serviço de localização compara relações de objetos no campo de esquerda para direita , usando o conferirmais próximo.

Por exemplo, uma tabela de localização na sua experiência pode ter as seguintes entradas compartilhadas de código de fonte:

Se a string "Screen" for adicionada a um playerGui.ScreenGui.TextLabel objeto na sua experiência, o serviço de localização exibe "Mosquitero" como a tradução espanhola como o contexto conferirpróximo.

Substituindo Parâmetros

Ao usar parâmetros para traduzir conteúdo dinâmico, defina os valores em uma tabela e passe a tabela como um argumento através da API (Interface de Programação para Aplicações).

Neste exemplo, a experiência possui uma tabela de localização com as seguintes entradas:

Use o seguinte código de exemplo para traduzir essas cadeias com valores de parâmetro:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")

-- Carregar Tradutor para "es". Wrap a função dentro de um pcall() para proteger contra falhas.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Defina o valor do parâmetro em "Key_Prize_1" para 100
	local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
	print(keyTranslation1) -- Saída esperada: 100 joias

	-- Definir múltiplos parâmetros para 500 e 100 por nome
	local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
	print(keyTranslation2) -- Saída esperada: $500.00 dinheiro e 100 joias
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Trocando Línguas

Em alguns casos, você pode querer exibir traduções de outros idiomas em sua experiência. Você pode configurar um novo tradutor com um código de país diferente usando LocalizationService:GetTranslatorForLocaleAsync() .

O seguinte código de exemplo configura um tradutor com um código de país manual e um tradutor adicional com base nas configurações globais do usuário:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")

-- Variáveis locais
local player = Players.LocalPlayer

-- Carregar Tradutor para "pt". Wrap tradutor funções dentro de um pcall() para proteger contra falhas.
local res1, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)

-- Carregar o segundo Tradutor com o idioma do Jogador, neste exemplo "es"
local res2, fallbackTranslator = pcall(function()
	return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- Use a função Traduzir com o primeiro Tradutor
if res1 then
	local translate1 = translator:Translate(game, "jewels")
	print(translate1) -- Saída Esperada em pt: joyas
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

-- Use a função de tradução com o segundo Tradutor
if res2 then
	local translate2 = fallbackTranslator:Translate(game, "jewels")
	print(translate2) -- Saída Esperada em se o usuário for definido para 'es': jóias
else
	print('GetTranslatorForPlayerAsync failed: ' .. fallbackTranslator)
end

Reagindo aos Usuários que Trocam Línguas

Os usuários podem alterar suas configurações de idioma a qualquer momento usando o menu de configurações de idioma na experiência. Essa configuração de usuário atualiza automaticamente os recursos de localização não script, como tradução automática, mas não atualiza as alterações de localização de script que já renderizaram, como imagens e sons de GUI.

Para garantir que suas ações locais sejam atualizadas corretamente, ouça o evento GetPropertyChangedSignal para alterações na propriedade Translator da instância Class.LocalizationService.GetTrans

O seguinte código de exemplo imprime o ID do Local do usuário e o ID do Local do Tradutor para o usuário quando o usuário troca de idioma:

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

-- Se o GetTranslatorForPlayerAsync tiver sucesso, ele retornará um tradutor para o idioma atual do jogador
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- Função que é chamada quando o ID de localização do jogador é detectado
local function OnLocaleIdChanged()
	print("Translator has changed to: " .. translator.LocaleId)
	-- Você deve re-traduzir qualquer recurso traduzido com APIs de Localização para o novo idioma do jogador aqui
end

-- Verifique se o GetTranslatorForPlayerAsync foi bem-sucedido
if res then
	-- Se tiver sucesso, traduza recursos aqui usando tradutor
	-- Ouça uma mudança no ID do idioma do jogador
	translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Criando um Módulo de Tradução

Quando você carrega tradutores com base no idioma padrão do jogador, você pode reutilizar o código. Para reutilizar o código, configure um ajudante ModuleScript que carrega seguramente os tradutores com base no idioma padrão do jogador e inclui funções para fornecer traduções específicas e alternar idiomas.

O seguinte código de exemplo implementa um TranslationHelper que você pode copiar em seu próprio projeto como um ModuleScript em ReplicatedStorage :

local TranslationHelper = {}

local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")

-- Variáveis locais
local player = Players.LocalPlayer
local sourceLanguageCode = "en"

-- Obter tradutores
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
	playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
	fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)

-- Crie um método TranslationHelper.setLanguage para carregar uma nova tradução para o TranslationHelper
function TranslationHelper.setLanguage(newLanguageCode)
	if sourceLanguageCode ~= newLanguageCode then
		local success, newPlayerTranslator = pcall(function()
			return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
		end)

		--Somente substituir o playerTranslator atual se o novo for válido (fallbackTranslator permanece como o idioma de origem da experiência)
		if success and newPlayerTranslator then
			playerTranslator = newPlayerTranslator
			return true
		end
	end
	return false
end

-- Crie uma função de tradução que usa um tradutor de fallback se o primeiro falhar carregar ou retornar com sucesso. Você também pode configurar o objeto referenciado para padrão para o Objetode jogo genérico

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

-- Crie uma função por Create a FormatByKey() que usa um tradutor de fallback se o primeiro falhar para carregar ou retornar com sucesso

function TranslationHelper.translateByKey(key, arguments)
	local translation = ""
	local foundTranslation = false

	-- Primeiro tenta traduzir para o idioma do jogador (se um tradutor foi encontrado)
	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

Uma vez que o módulo estiver em ReplicatedStorage, exija-o de um LocalScript para chamar as funções do módulo. O seguinte código usa a função de auxílio deste módulo para traduzir uma única string / cadeia / texto:

local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Requer módulo de tradução
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))

-- Use as funções fornecidas no TranslationHelper
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Expected Output in 'es': "Pantalla"