Você pode usar APIs de localização para tarefas de tradução especializadas que não são tratadas automaticamente ao adicionar traduções à tabela de localização. O Roblox fornece um LocalizationService para lidar com todas as necessidades de script de localização. Use o LocalizationService para as seguintes tarefas:
Se você usar qualquer API de localização ao traduzir seu jogo, escute por quaisquer mudanças no LocaleID do usuário para reagir às mudanças de idioma dos usuários enquanto estiver em um jogo.
Ao reutilizar o código de tradução, você deve usar um TranslationHelper ModuleScript para lidar com erros e traduções faltantes.
Localizar imagens e sons
Adicione localização além do texto em seu jogo, fornecendo imagens e sons exclusivos com base no local do usuário. Para localizar ativos, primeiro adicione os IDs de ativos source e target à tabela de localização do seu jogo e, em seguida, use a API de localização para buscar os diferentes ativos.



Para começar a localizar imagens e sons, adicione seus IDs de ativos source e target à sua tabela de localização. As entradas de ID de ativo na tabela de localização devem incluir uma Chave como um identificador a ser chamado pela API.
O seguinte é um exemplo de entrada em uma tabela de localização usando IDs de ativos:
| Chave | Fonte | es | pt |
|---|---|---|---|
| Key_JewelsImage | 2957093606 | 2957093671 | 2957093727 |
O código a seguir substituirá o ID de ativo de um ImageLabel pelo ID de ativo em 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". Envolver a função dentro de um pcall() para proteger contra falhas.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Obter ID de ativo da tabela de localização referenciando a Chave
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- Definir a imagem
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('GetTranslatorForPlayerAsync falhou: ' .. translator)
end
Traduzir strings individuais
Em algumas circunstâncias, você pode querer direcionar strings individuais para tradução. Translator:Translate() pode buscar entradas individuais na tabela de localização com base na string fonte.
No próximo exemplo, a seguinte entrada de localização é usada:
| Fonte | es | es | pt |
|---|---|---|---|
| Tela | Pantalla | 295093671 | 2957093727 |
O seguinte script imprimirá a tradução em espanhol de "Tela" na janela Output:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Carregar tradutor para "es". Envolver a função dentro de um pcall() para proteger contra falhas.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Usar função Translate, fornecendo contexto de objeto e string
local sourceTranslation = translator:Translate(game, "Screen")
print(sourceTranslation) -- Saída esperada: "Pantalla"
else
print('GetTranslatorForPlayerAsync falhou: ' .. translator)
end
Usar substituições de contexto
Há alguns casos em que a mesma string pode ter múltiplos significados. Por exemplo, a palavra "Tela" pode indicar tanto uma tela de computador quanto uma tela de janela, mas as traduções em espanhol são completamente diferentes.
A coluna Contexto da tabela de localização serve para especificar traduções através de substituições de contexto. Especifique o objeto no jogo em sua tabela de localização como no exemplo a seguir:
| Contexto | Fonte | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Tela | Mosquitero |
| Tela | Pantalla |
O seguinte script usa uma substituição de contexto para priorizar uma tradução específica:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- Carregar tradutor para "es". Envolver a função dentro de um pcall() para proteger contra falhas.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- usar função Translate, fornecendo contexto de objeto e string
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
print(sourceTranslation) -- Saída esperada: Mosquitero
else
print('GetTranslatorForPlayerAsync falhou: ' .. translator)
end
Múltiplos contextos
No caso de múltiplos contextos, o serviço de localização compara relacionamentos de objetos no campo Contexto da direita para a esquerda, usando a correspondência mais próxima.
Por exemplo, uma tabela de localização em seu jogo pode ter as seguintes entradas de strings de Fonte compartilhadas:
| Contexto | Fonte | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Tela | Mosquitero |
| playerGui.ScreenGui.TextButton | Tela | Pantalla |
Se a string "Tela" for adicionada a um objeto playerGui.ScreenGui.TextLabel em seu jogo, o serviço de localização exibirá "Mosquitero" como a tradução em espanhol como a correspondência de contexto mais próxima.
Substituir parâmetros
Ao usar parâmetros para traduzir conteúdo dinâmico, defina os valores para uma tabela e passe a tabela como um argumento pela API.
Neste exemplo, o jogo possui uma tabela de localização com as seguintes entradas:
| Chave | Fonte | 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 |
Use o seguinte exemplo de código para traduzir essas strings com valores de parâmetros:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Carregar tradutor para "es". Envolver a função dentro de um pcall() para proteger contra falhas.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Definir 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 joyas
-- 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 dinero y 100 joyas
else
print('GetTranslatorForPlayerAsync falhou: ' .. translator)
end
Mudar idiomas
Em alguns casos, você pode querer exibir traduções de outros idiomas em seu jogo. Você pode definir um novo tradutor com um código de país diferente usando LocalizationService:GetTranslatorForLocaleAsync().
O seguinte exemplo de código configura um tradutor com um código de país manual e um tradutor adicional com base nas configurações de local global 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". Envolver funções de tradutor dentro de um pcall() para proteger contra falhas.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- Carregar segundo Tradutor com o local do Jogador, neste exemplo "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Usar função Translate com o primeiro Tradutor
if res1 then
local translate1 = translator:Translate(game, "jewels")
print(translate1) -- Saída esperada em pt: joyas
else
print('GetTranslatorForPlayerAsync falhou: ' .. translator)
end
-- Usar função Translate com o segundo Tradutor
if res2 then
local translate2 = fallbackTranslator:Translate(game, "jewels")
print(translate2) -- Saída esperada se o usuário estiver definido como 'es': jóias
else
print('GetTranslatorForPlayerAsync falhou: ' .. fallbackTranslator)
end
Reagir às mudanças de idioma dos usuários
Os usuários podem alterar suas configurações de idioma a qualquer momento usando o menu de Configurações do jogo. Essa mudança de configuração do usuário atualiza automaticamente ativos de localização não scriptados, como strings tratadas por tradução automática, mas pode não atualizar mudanças de localização scriptadas que já foram renderizadas, como imagens ou sons de GUI.


Para garantir que seus ativos localizados por script atualizem corretamente, ouça o evento GetPropertyChangedSignal para mudanças na propriedade LocaleID da instância Translator retornada por LocalizationService.GetTranslatorForPlayerAsync. Ao usar LocalizationService.GetTranslatorForPlayerAsync, envolva a função dentro de um pcall() em caso de erros.
O seguinte exemplo de código imprime o ID de Localidade do usuário e o ID de Localidade da instância do Tradutor para o usuário quando o usuário muda de idioma:
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Se GetTranslatorForPlayerAsync for bem-sucedido, ele retornará um Tradutor para o local atual do jogador
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Função que é chamada quando a mudança no ID de local do jogador é detectada
local function OnLocaleIdChanged()
print("Tradutor mudou para: " .. translator.LocaleId)
-- Você deve re-traduzir quaisquer ativos traduzidos com APIs de Localização para o novo idioma do jogador aqui
end
-- Verifique se GetTranslatorForPlayerAsync foi bem-sucedido
if res then
-- Se bem-sucedido, traduza ativos aqui usando o tradutor
-- Ouça uma mudança no ID de local do jogador
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('GetTranslatorForPlayerAsync falhou: ' .. translator)
end
Criar um módulo TranslationHelper
Quando você carrega tradutores com base no local padrão do jogador, pode reutilizar o código. Para reutilizar o código, configure um ModuleScript auxiliar que carregue com segurança tradutores com base no local padrão do jogador e inclua funções para fornecer traduções específicas e alternar idiomas.
O seguinte exemplo de código implementa um TranslationHelper que você pode copiar para 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)
-- Criar 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)
-- Apenas sobrepor o playerTranslator atual se o novo for válido (fallbackTranslator permanece como o idioma fonte do jogo)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- Criar uma função Translate que usa um tradutor de fallback se o primeiro falhar ao carregar ou retornar com sucesso. Você também pode definir o objeto referenciado para ser o objeto genérico por padrão
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
-- Criar uma função FormatByKey() que usa um tradutor de fallback se o primeiro falhar ao 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 esteja em ReplicatedStorage, requerê-lo de um LocalScript para chamar as funções do módulo. O seguinte código usa a função auxiliar deste módulo para traduzir uma string individual:
local ReplicatedStorage = game:GetService("ReplicatedStorage")-- Requerer módulo de traduçãolocal TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))-- Usar as funções fornecidas em TranslationHelperTranslationHelper.setLanguage("es")local sourceTranslation = TranslationHelper.translate("Screen")print(sourceTranslation) -- Saída esperada em 'es': "Pantalla"