Localizar com scripts

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

• Localizar imagens e sons.
• Traduzir parte de strings individuais.
• Aplicar traduções de vários idiomas.

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

Ao reutilizar códigos de tradução, você deve usar um TranslationHelper ModuleScript para lidar com erros e traduções ausentes.

Localizar imagens e sons

Adicione localização para além do texto na sua experiência através de imagens e sons únicos e de fora do local de um usuário. Para localizar ativos, adicione primeiro os IDs do ativo do original e da tradução à tabela de localização da sua experiência e use a API de localização para buscar os diferentes ativos.

Para iniciar a localização de imagens e sons, adicione os IDs do ativo do original e da tradução à tabela de localização. As entradas de ID de ativos na tabela de localização devem incluir uma chave como um identificador a ser chamado pela API. O item a seguir é um exemplo de entrada em uma tabela de localização usando os IDs do ativo:

O código a seguir substituirá o ID de ativo de um Class. ImageLabel por um ID de ativo em espanhol fornecido pela tabela de localização.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Load Translator for "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
    -- Use Translate function, providing object context and string
    local sourceTranslation = translator:Translate(game, "Screen")
    print(sourceTranslation) -- Expected Output: "Pantalla"
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Traduzir textos individuais

Em algumas circunstâncias, é possível focar em segmentos individuais para tradução. Class. Translator:Translate()pode buscar entradas individuais na tabela de localização com base no segmento original.

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

O script a seguir executará a tradução em espanhol de "Screen" para a janela Output:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Load Translator for "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
    -- Set the parameter value in "Key_Prize_1" to 100
    local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
    print(keyTranslation1) -- Expected Output: 100 joyas
    -- Set multiple parameters to 500 and 100 by name
    local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
    print(keyTranslation2) -- Expected Output: $500.00 dinero y 100 joyas
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Usar substituições contextuais

Existem alguns casos em que um string pode ter vários significados. Por exemplo, a palavra "Screen" pode indicar uma tela do computador e uma janela, mas as traduções em espanhol são completamente diferentes.

A coluna Contexto da tabela de localização visa especificar traduções por meio de substituições contextuais. Especifique o objeto no jogo na sua tabela de localização conforme o exemplo a seguir:

O script a seguir usa uma substituição contextual para priorizar uma tradução específica:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Load Translator for "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
    -- use Translate function, providing object context and string
    local sourceTranslation = translator:Translate( workspace. WindowScreen. SurfaceGui. TextLabel, "Screen")
    print(sourceTranslation) -- Expected Output: Mosquitero
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Vários contextos

No caso de vários contextos, o serviço de localização compara os relacionamentos de objetos no campo Contexto da direita para a esquerda, usando a correspondência mais próxima.

Por exemplo, a tabela de localização na sua experiência pode ter as seguintes entradas compartilhadas dos strings originais:

Se o string "Screen" for adicionado a um playerGui. ScreenGui. TextLabelobjeto na sua experiência, o serviço de localização exibirá "Mosquitero" como a tradução em espanhol como a correspondência contextual mais próxima.

Substituir parâmetros

Ao usar parâmetros para traduzir um conteúdo dinâmico, configure os valores para uma tabela e libere a tabela como argumento por meio da API.

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

Use seguindo o exemplo de código a seguir para traduzir essas strings com valores de parâmetros:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Load Translator for "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
    -- Set the parameter value in "Key_Prize_1" to 100
    local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
    print(keyTranslation1) -- Expected Output: 100 joyas

    -- Set multiple parameters to 500 and 100 by name
    local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
    print(keyTranslation2) -- Expected Output: $500.00 dinero y 100 joyas
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Mudar idiomas

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

O exemplo de código a seguir define um tradutor com uma codificação manual de país e um tradutor adicional fora das configurações globais do usuário:

local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players. LocalPlayer
-- If GetTranslatorForPlayerAsync succeeds, it will return a Translator for player's current locale
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Function that gets called when change in player's locale ID is detected
local function OnLocaleIdChanged()
    print("Translator has changed to: " ..
translator. LocaleId)
    -- You should re-translate any assets translated with Localization APIs to the player's new language here
end
-- Check if GetTranslatorForPlayerAsync succeeded
if res then
    -- If succeeded, translate assets here using translator
    -- Listen for a change in player's locale ID
    translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Reagir a usuários que mudam os idiomas

Os usuários podem alterar as configurações do idioma a qualquer momento usando o menu Configurações na experiência. Essa alteração de configuração atualiza automaticamente os ativos de localização que atualização automaticamente, como strings tratadas por tradução automática, porém ela talvez não atualize as alterações de localização com scripts que já tenham sido renderizado, tais como imagens GUI ou sons.

Para garantir que seus ativos de script localizados sejam atualizados corretamente, ouça o evento Class. Instance. GetPropertyChangedSignal|GetPropertyChangedSignal quanto às alterações na propriedade do LocaleID da instância Class. Translator retornada por Class. LocalizationService. GetTranslatorForPlayerAsync. Ao usar Class. LocalizationService. GetTranslatorForPlayerAsync, envolva a função dentro de um pcall em um caso de erros.

O exemplo de código a seguir imprime o ID de localização do usuário e o ID da instância do tradutor para o usuário quando o próprio usuário alterna os idiomas:

local TranslationHelper = {}
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Local variables
local player = Players. LocalPlayer
local sourceLanguageCode = "en"
-- Get translators
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
    playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
    fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
-- Create a method TranslationHelper.setLanguage to load a new translation for the TranslationHelper
function TranslationHelper.setLanguage(newLanguageCode)
    if sourceLanguageCode ~= newLanguageCode then
        local success, newPlayerTranslator = pcall(function()
            return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
        end)
        --Only override current playerTranslator if the new one is valid (fallbackTranslator remains as experience's source language)
        if success and newPlayerTranslator then
            playerTranslator = newPlayerTranslator
            return true
        end
    end
    return false
end
-- Create a Translate function that uses a fallback translator if the first fails to load or return successfully. translator)
end

Criar um módulo TranslationHelper

Ao carregar tradutores com base no local padrão do jogador, você pode reutilizar o código. Para reutilizar o código, configure um Class. ModuleScript de suporte que carregue com segurança os tradutores conforme o local padrão do jogador e inclua funções para fornecer traduções específicas e idiomas disponíveis.

O exemplo de código a seguir implementa um TranslationHelper que você pode copiar para seu próprio projeto como um Class. ModuleScript em Class. ReplicatedStorage:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Local variables
local player = Players. LocalPlayer
-- Load Translator for "pt". Wrap translator functions within a pcall() to protect against failures. local res1, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- Load second Translator with Player's locale, in this example "es"
local res2, fallbackTranslator = pcall(function()
    return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Use Translate function with first Translator
if res1 then
    local translate1 = translator:Translate(game, "jewels")
    print(translate1) -- Expected Output in pt: joyas
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end
-- Use Translate function with second Translator
if res2 then
    local translate2 = fallbackTranslator:Translate(game, "jewels")
    print(translate2) -- Expected Output in if user is set to 'es': jóias
else
    print('GetTranslatorForPlayerAsync failed: ' .. fallbackTranslator)
end You can also set the referenced object to default to the generic game object

function TranslationHelper.translate(text, object)
    if not object then
        object = game
    end
    local translation = ""
    local foundTranslation = false
    if foundPlayerTranslator then
        return playerTranslator:Translate(object, text)
    end
    if foundFallbackTranslator then
        return fallbackTranslator:Translate(object, text)
    end
    return false
end

-- Create a FormatByKey() function that uses a fallback translator if the first fails to load or return successfully

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

    -- First tries to translate for the player's language (if a translator was found)
    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 no Class. ReplicatedStorage, faça uma requisição dele a partir de um Class. LocalScript para chamar as funções do módulo. O código a seguir usa a função de suporte deste módulo para traduzir um string individual:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- Require translation module
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))
-- Use the functions provided in TranslationHelper TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Expected Output in 'es': "Pantalla"