Localización con scripting

Puedes usar las API de localización para tareas de traducción especializadas que no se gestionan automáticamente añadiendo traducciones a la tabla de localización. Roblox proporciona un LocalizationService para gestionar todas las necesidades de scripting de localización. Usa LocalizationService para las siguientes tareas:

• Localizar imágenes y sonidos.
• Traducir parte de cadenas individuales.
• Aplicar traducciones de varios idiomas.

Si usas alguna API de localización al traducir tu experiencia, presta atención a cualquier cambio en el LocaleID del usuario para reaccionar cuando los usuarios cambian de idioma mientras están en una experiencia.

Al reutilizar el código de traducción, debes utilizar una etiqueta TranslationHelper ModuleScript para gestionar los errores y las traducciones que falten.

Localizar imágenes y sonidos

Añade la localización más allá del texto en tu experiencia proporcionando imágenes y sonidos únicos basados en la configuración regional del usuario. Para localizar recursos, añade primero la identificación de los recursos de origen y destino a la tabla de localización de tu experiencia, luego usa la API de localización para recuperar los distintos recursos.

Para empezar a localizar imágenes y sonidos, añade las identificaciones del recurso de origen y destino a tu tabla de localización. Las entradas de identificación de recursos en la tabla de localización deben incluir una Clave como identificador para ser llamado por la API. A continuación se muestra un ejemplo de entrada en una tabla de localización que utiliza identificaciones de recursos:

El siguiente código sustituirá la identificación del recurso de ImageLabel por la identificación del recurso en español proporcionado en la tabla de localización:

local ReplicatedStorage = game: GetService("ReplicatedStorage")
local LocalizationService = game: GetService("LocalizationService")
-- Local variables
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- 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
    -- Get asset ID from localization table by referencing the Key
    localizedImageID = translator: FormatByKey("Key_JewelsImage")
    -- Set the image
    localizedImage. Image = "rbxassetid://" .. localizedImageID
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Traducción de cadenas individuales

En algunas circunstancias, es posible que desees traducir cadenas individuales. Translator:Translate() puede buscar entradas individuales en la tabla de localización basándose en la cadena de origen.

En el siguiente ejemplo, se utiliza la siguiente entrada de localización:

El siguiente script imprimirá la traducción al español de "Screen" en la ventana Salida:

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

Usar invalidación de contexto

Hay algunos casos en que la misma cadena puede tener varios significados. Por ejemplo, la palabra "Screen" puede indicar tanto una pantalla de computadora como una pantalla de ventana, pero las traducciones al español son completamente diferentes.

La columna Contexto de la tabla de localización sirve para especificar traducciones mediante anulaciones de contexto. Especifica el objeto del juego en tu tabla de localización como en el siguiente ejemplo:

El siguiente script utiliza una invalidación de contexto para priorizar una traducción 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

Múltiples contextos

En caso de múltiples contextos, el servicio de localización compara las relaciones de objetos en el campo Contexto de derecha a izquierda, usando la coincidencia más cercana.

Por ejemplo, una tabla de localización en tu experiencia puede tener las siguientes entradas de cadenas de origen compartidas:

Si se añade la cadena "Screen" a un objeto playerGui.ScreenGui.TextLabel en tu experiencia, el servicio de localización mostrará "Mosquitero" como traducción al español por ser la coincidencia de contexto más cercana.

Substituir parámetros

Cuando uses parámetros para traducir contenido dinámico, establece los valores en una tabla y pasa la tabla como argumento a través de la API.

En este ejemplo, la experiencia tiene una tabla de localización con las siguientes entradas:

Usa la siguiente muestra de código para traducir estas cadenas con 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

Cambiar de idioma

En algunos casos, es posible que desees mostrar traducciones de otros idiomas en tu experiencia. Puedes establecer un nuevo traductor con un código de país diferente usando LocalizationService:GetTranslatorForLocaleAsync().

La siguiente muestra de código establece un traductor con un código de país manual y un traductor adicional basado en la configuración regional global del usuario:

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

Reaccionar a los usuarios que cambian de idioma

Los usuarios pueden cambiar su configuración de idioma en cualquier momento a través del menú Configuración de la experiencia. Este cambio en la configuración del usuario actualiza automáticamente los recursos de localización no basados en scripting, como las cadenas gestionadas por traducción automática, pero puede que no actualice los cambios de localización basados en scripting que ya se hayan renderizado, como las imágenes o los sonidos de la GUI.

Para garantizar que tus recursos localizados con script se actualicen correctamente, escucha el evento GetPropertyChangedSignal para cambios en la propiedad LocaleID de la instancia Translator devuelta por LocalizationService.GetTranslatorForPlayerAsync. Cuando uses LocalizationService.GetTranslatorForPlayerAsync, encapsula la función dentro de pcall en caso de error.

La siguiente muestra de código imprime la identificación de configuración regional del usuario y la identificación de configuración regional de la instancia del traductor para el usuario cuando este cambia de idioma:

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

Crear un módulo TranslationHelper

Cuando cargas traductores según la configuración regional predeterminada del jugador, puedes reutilizar código. Para reutilizar el código, configura un helper ModuleScript que cargue de forma segura los traductores según la configuración regional predeterminada del jugador e incluya funciones para proporcionar traducciones específicas y cambiar de idioma.

La siguiente muestra de código implementa un TranslationHelper que puedes copiar en tu propio proyecto como ModuleScript en ReplicatedStorage:

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. 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

Una vez que el módulo está en ReplicatedStorage, solicítalo desde un LocalScript para llamar a las funciones del módulo. El siguiente código utiliza la función helper de este módulo para traducir una cadena 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"