Localización con Scripting

Puede usar API de localización para tareas de traducción especializadas que no se manejan automáticamente por agregar traducciones a la tabla de localización. Roblox proporciona un LocalizationService para manejar todas las necesidades de scripting de localización. Usa el LocalizationService para las siguientes tareas:

• Localizando imágenes y sonidos .
• Traduciendo parte de cadenas individuales .
• Aplicando traducciones de múltiples idiomas .

Si usa cualquier API de localización al traducir su experiencia, escúche cualquier cambio en el LocaleID del usuario para reaccionar a los usuarios que cambian su idioma mientras está en una experiencia.

Al reutilizar el código de traducción, debe usar un TranslationHelper ModuleScript para manejar errores y traducciones faltantes.

Localizando Imágenes y Sonidos

Añade localización más allá del texto en tu experiencia proporcionando imágenes y sonidos únicos basados en el idioma de un usuario. Para localizar recursos, primero agrega los ID de fuente y de destino de los recursos de tu experiencia a la tabla de localización de tu experiencia y luego usa la API de localización para obtener los diferentes recursos.

Para comenzar a localizar imágenes y sonidos, agregue sus ID de fuente y de destino y fuente a su mesa de localización. Las entradas de ID de activos en la mesa de localización deben incluir un 0>Clave0> como identificador para ser llamado por la API.

La siguiente es una entrada de ejemplo en una tabla de localización usando ID de activos:

El siguiente código reemplazará el ID de la propiedad de un ImageLabel con el ID de la propiedad de un espacio de trabajo local:

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

-- variables locales
local localizedImageID
local localizedImage = Instance.new("ImageLabel")

-- Carga el traductor para "es". Envoltura la función dentro de un pcall() para proteger contra fallos.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Obtener el ID de la herramienta de localización al referenciar la Clave
	localizedImageID = translator:FormatByKey("Key_JewelsImage")
	-- Establecer la imagen
	localizedImage.Image = "rbxassetid://" .. localizedImageID
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Traduciendo cuerdas individuales

En algunas ocasiones, puede que desee apuntar a cadenas individuales para la traducción. Translator:Translate() puede recuperar individuales entradas en la tabla de localización según la cadena de origen.

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

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

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

-- Carga el traductor para "es". Envoltura la función dentro de un pcall() para proteger contra fallos.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Usa la función de traducción, proporcionando contexto de objeto y cadena
	local sourceTranslation = translator:Translate(game, "Screen")
	print(sourceTranslation) -- Salida esperada: "Pantalla"
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Usando Overrides de Contexto

Hay algunos casos en los que la misma cadena puede tener múltiples significados. Por ejemplo, la palabra "Pantalla" puede indicar tanto una pantalla de ordenador como una pantalla de ventana, pero las traducciones de español son completamente diferentes.

La columna Contexto de la tabla de localización se utiliza para especificar traducciones a través de anulaciones de contexto. Especifique el objeto en el juego en su tabla de localización como en el siguiente ejemplo:

El siguiente script usa un Override de contexto para priorizar una traducción específica:

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

-- Carga el traductor para "es". Envoltura la función dentro de un pcall() para proteger contra fallos.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- usar la función de traducción, proporcionando contexto de objeto y cadena
	local sourceTranslation = translator:Translate( workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
	print(sourceTranslation) -- Salida esperada: Mosquitero
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Múltiples contextos

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

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

Si se agrega la cadena «Screen» a un objeto playerGui.ScreenGui.TextLabel » en tu experiencia, el servicio de localización muestra «Mosquito» como la traducción en español como el contexto coincidircercano.

Reemplazando Parámetros

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

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

Usa el siguiente código de ejemplo para traducir estos valores de parámetro:

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

-- Carga el traductor para "es". Envoltura la función dentro de un pcall() para proteger contra fallos.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Establece el valor de parámetro en "Key_Prize_1" a 100
	local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
	print(keyTranslation1) -- Output esperado: 100 joyas

	-- Establecer múltiples parámetros a 500 y 100 por nombre
	local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
	print(keyTranslation2) -- Salario esperado: $500.00 dinero y 100 joyas
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Cambio de idiomas

En algunos casos, es posible que desee mostrar traducciones de otros idiomas en su experiencia. Puede configurar un nuevo traductor con un código de país diferente utilizando LocalizationService:GetTranslatorForLocaleAsync() .

El siguiente código de ejemplo establece un traductor con un código de país manual y un traductor adicional basado en las configuraciones globales del usuario:

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

-- variables locales
local player = Players.LocalPlayer

-- Carga el traductor para "pt". Envoltura las funciones de traductor dentro de un pcall() para proteger contra fallos.
local res1, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)

-- Carga el segundo traductor con el idioma del jugador, en este ejemplo "es"
local res2, fallbackTranslator = pcall(function()
	return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- Usar la función de traducción con el primer traductor
if res1 then
	local translate1 = translator:Translate(game, "jewels")
	print(translate1) -- Output esperado en pt: joyas
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

-- Usar la función de traducción con el segundo traductor
if res2 then
	local translate2 = fallbackTranslator:Translate(game, "jewels")
	print(translate2) -- Salida esperada en si el usuario está configurado como 'es': joyas
else
	print('GetTranslatorForPlayerAsync failed: ' .. fallbackTranslator)
end

Reaccionando a los usuarios que cambian de idioma

Los usuarios pueden cambiar sus configuraciones de idioma en cualquier momento usando su menú de configuración de lenguaje. Este cambio de configuración de usuario actualiza automáticamente las herramientas de localización no scripting, como las cadenas manejadas por traducción automática, pero no actualiza los cambios de localización de script que ya se han renderizado, como imágenes y sonidos de GUI.

Para asegurar que tus scripts de localización se actualizan correctamente, escucha el evento GetPropertyChangedSignal para cambios en la propiedad de LocaleID de la instancia Translator devuelta por Class.Localization

La siguiente muestra de código imprime el ID de la localización del usuario y el ID de la localización del traductor para el usuario cuando el usuario cambia de idioma:

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

-- Si GetTranslatorForPlayerAsync tiene éxito,返回Translator para el idioma actual del jugador
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- Función que se llama cuando se detecta el ID del idioma del jugador
local function OnLocaleIdChanged()
	print("Translator has changed to: " .. translator.LocaleId)
	-- Deberías volver a traducir cualquier activo traducido con API de localización a la nueva lengua del jugador aquí
end

-- Compruebe si GetTranslatorForPlayerAsync tuvo éxito
if res then
	-- Si se ha utilizado con éxito, traduzca los recursos aquí usando el traductor
	-- Escuchar una cambio en el ID del idioma del jugador
	translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Creando un Módulo de Traducción

Cuando cargas los traductores según el idioma predeterminado del jugador, es posible que reutilices el código. Para reutilizar el código, configura un ayudante ModuleScript que carga los traductores según el idioma predeterminado del jugador y incluye funciones para proporcionar traducciones específicas y cambiar de idioma.

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

local TranslationHelper = {}

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

-- variables locales
local player = Players.LocalPlayer
local sourceLanguageCode = "en"

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

-- Crea un método TranslationHelper.setLanguage para cargar una nueva traducción para el TranslationHelper
function TranslationHelper.setLanguage(newLanguageCode)
	if sourceLanguageCode ~= newLanguageCode then
		local success, newPlayerTranslator = pcall(function()
			return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
		end)

		--Solo anula el transladador de jugador actual si el nuevo es válido (fallbackTranslator se mantiene como el lenguaje de origen de la experiencia)
		if success and newPlayerTranslator then
			playerTranslator = newPlayerTranslator
			return true
		end
	end
	return false
end

-- Crea una función de traducción que usa un traductor de fallback si el primer objeto no se carga o regresa con éxito. También puedes configurar el objeto de referencia por defecto para el objeto de juego 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

-- Crea una función de CreateByKey() que usa un traductor de fallback si el primer falla al cargar o返回 con éxito

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

	-- Primero intenta traducir para el idioma del jugador (si se encontró un traductor)
	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, requírelo de un LocalScript para llamar las funciones del módulo. El siguiente código usa la función de ayuda del módulo para traducir una cadena individual:

local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Requiere un módulo de traducción
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))

-- Usa las funciones proporcionadas en TranslationHelper
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Expected Output in 'es': "Pantalla"