Puedes utilizar las API de localización para tareas de traducción especializadas que no se manejan automáticamente al agregar traducciones a la tabla de localización. Roblox proporciona un LocalizationService para manejar todas las necesidades de scripting de localización. Utiliza el LocalizationService para las siguientes tareas:
Si utilizas alguna API de localización al traducir tu juego, escucha cualquier cambio en el LocaleID del usuario para reaccionar a los cambios de idioma de los usuarios mientras juegan.
Al reutilizar el código de traducción, deberías utilizar un ModuleScript TranslationHelper para manejar errores y traducciones faltantes.
Localizar imágenes y sonidos
Agrega localización más allá del texto en tu juego proporcionando imágenes y sonidos únicos basados en la localidad del usuario. Para localizar activos, primero agrega los ID de fuente y ID de destino a la tabla de localización de tu juego y luego utiliza la API de localización para obtener los diferentes activos.



Para comenzar a localizar imágenes y sonidos, agrega tus IDs de fuente y destino a tu tabla de localización. Las entradas de ID de activo en la tabla de localización deben incluir una Clave como identificador que será llamado por la API.
El siguiente es un ejemplo de entrada en una tabla de localización utilizando IDs de activos:
| Clave | Fuente | es | pt |
|---|---|---|---|
| Key_JewelsImage | 2957093606 | 2957093671 | 2957093727 |
El siguiente código reemplazará el ID de activo de un ImageLabel con el ID de activo en español proporcionado en la tabla de localización:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Variables locales
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- Cargar traductor para "es". Envuelve 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 ID de activo de la tabla de localización haciendo referencia a la Clave
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- Establecer la imagen
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('GetTranslatorForPlayerAsync falló: ' .. translator)
end
Traducir cadenas individuales
En algunas circunstancias, es posible que desees dirigirte a cadenas individuales para la traducción. Translator:Translate() puede obtener entradas individuales en la tabla de localización según la cadena de origen.
En el siguiente ejemplo, se utiliza la siguiente entrada de localización:
| Fuente | es | es | pt |
|---|---|---|---|
| Screen | Pantalla | 295093671 | 2957093727 |
El siguiente script imprimirá la traducción en español de "Screen" en la ventana de Output:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Cargar traductor para "es". Envuelve 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 función Translate, proporcionando el contexto del objeto y la cadena
local sourceTranslation = translator:Translate(game, "Screen")
print(sourceTranslation) -- Salida esperada: "Pantalla"
else
print('GetTranslatorForPlayerAsync falló: ' .. translator)
end
Usar sobrescrituras de contexto
Hay algunos casos en los que la misma cadena puede tener múltiples significados. Por ejemplo, la palabra "Screen" puede indicar tanto una pantalla de computadora como una pantalla de ventana, pero las traducciones en español son completamente diferentes.
La columna Contexto de la tabla de localización es para especificar traducciones a través de sobrescrituras de contexto. Especifica el objeto en el juego en tu tabla de localización como en el siguiente ejemplo:
| Contexto | Fuente | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Screen | Mosquitero |
| Screen | Pantalla |
El siguiente script utiliza una sobrescritura de contexto para priorizar una traducción específica:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- Cargar traductor para "es". Envuelve 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 función Translate, proporcionando el contexto del objeto y la cadena
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
print(sourceTranslation) -- Salida esperada: Mosquitero
else
print('GetTranslatorForPlayerAsync falló: ' .. 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 Contexto de derecha a izquierda, utilizando la coincidencia más cercana.
Por ejemplo, una tabla de localización en tu juego puede tener las siguientes entradas de cadenas de fuente compartidas:
| Contexto | Fuente | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Screen | Mosquitero |
| playerGui.ScreenGui.TextButton | Screen | Pantalla |
Si la cadena "Screen" se añade a un objeto playerGui.ScreenGui.TextLabel en tu juego, el servicio de localización muestra "Mosquitero" como la traducción en español, ya que es la coincidencia de contexto más cercana.
Sustituir parámetros
Al usar parámetros para traducir contenido dinámico, establece los valores en una tabla y pasa la tabla como un argumento a través de la API.
En este ejemplo, el juego tiene una tabla de localización con las siguientes entradas:
| Clave | Fuente | 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 |
Usa el siguiente código de muestra para traducir estas cadenas con valores de parámetro:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Cargar traductor para "es". Envuelve la función dentro de un pcall() para proteger contra fallos.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Establecer el valor del parámetro en "Key_Prize_1" a 100
local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
print(keyTranslation1) -- Salida esperada: 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) -- Salida esperada: $500.00 dinero y 100 joyas
else
print('GetTranslatorForPlayerAsync falló: ' .. translator)
end
Cambiar idiomas
En algunos casos, es posible que desees mostrar traducciones de otros idiomas en tu juego. Puedes establecer un nuevo traductor con un código de país diferente usando LocalizationService:GetTranslatorForLocaleAsync().
El siguiente código de muestra establece un traductor con un código de país manual y un traductor adicional basado en la configuración global de localidad del usuario:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Variables locales
local player = Players.LocalPlayer
-- Cargar traductor para "pt". Envuelve las funciones del traductor dentro de un pcall() para proteger contra fallos.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- Cargar segundo traductor con la localidad del jugador, en este ejemplo "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Usar función Translate con el primer traductor
if res1 then
local translate1 = translator:Translate(game, "jewels")
print(translate1) -- Salida esperada en pt: joyas
else
print('GetTranslatorForPlayerAsync falló: ' .. translator)
end
-- Usar función Translate con el segundo traductor
if res2 then
local translate2 = fallbackTranslator:Translate(game, "jewels")
print(translate2) -- Salida esperada si el usuario está configurado en 'es': jóias
else
print('GetTranslatorForPlayerAsync falló: ' .. fallbackTranslator)
end
Reaccionar a los cambios de idioma de los usuarios
Los usuarios pueden cambiar su configuración de idioma en cualquier momento utilizando el menú de Ajustes en el juego. Este cambio de configuración de usuario actualiza automáticamente activos de localización no relacionados con scripting, como cadenas manejadas por traducción automática, pero puede no actualizar cambios de localización en scripts que ya se han renderizado, como imágenes o sonidos de GUI.


Para asegurar que tus activos localizados por scripting se actualicen correctamente, escucha el evento GetPropertyChangedSignal para cambios en la propiedad LocaleID de la instancia Translator retornada por LocalizationService.GetTranslatorForPlayerAsync. Al usar LocalizationService.GetTranslatorForPlayerAsync, envuelve la función en un pcall() por si ocurren errores.
El siguiente código de muestra imprime el ID de Locale del usuario y el ID de Locale de la instancia de 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, devolverá un traductor para la localidad actual del jugador
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Función que se llama cuando se detecta un cambio en el ID de localidad del jugador
local function OnLocaleIdChanged()
print("El traductor ha cambiado a: " .. translator.LocaleId)
-- Aquí deberías volver a traducir cualquier activo traducido con las API de localización al nuevo idioma del jugador
end
-- Verificar si GetTranslatorForPlayerAsync tuvo éxito
if res then
-- Si tuvo éxito, traduce activos aquí usando el traductor
-- Escucha un cambio en el ID de localidad del jugador
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('GetTranslatorForPlayerAsync falló: ' .. translator)
end
Crear un módulo TranslationHelper
Cuando cargas traductores basados en la localidad predeterminada del jugador, puedes reutilizar código. Para reutilizar código, establece un ModuleScript auxiliar que cargue de forma segura traductores basados en la localidad predeterminada del jugador e incluya funciones para proporcionar traducciones específicas y cambiar idiomas.
El siguiente código de muestra 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)
-- Crear 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 sobreescribir el traductor del jugador actual si el nuevo es válido (fallbackTranslator permanece como el idioma fuente del juego)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- Crear una función Translate que use un traductor de respaldo si el primero falla al cargar o devolver correctamente. También puedes establecer el objeto referenciado para que predetermine al objeto 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
-- Crear una función FormatByKey() que use un traductor de respaldo si el primero falla al cargar o devolver correctamente
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, requiérelo desde un LocalScript para llamar a las funciones del módulo. El siguiente código utiliza la función auxiliar de este módulo para traducir una cadena individual:
local ReplicatedStorage = game:GetService("ReplicatedStorage")-- Requerir módulo de traducciónlocal TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))-- Usar las funciones proporcionadas en TranslationHelperTranslationHelper.setLanguage("es")local sourceTranslation = TranslationHelper.translate("Screen")print(sourceTranslation) -- Salida esperada en 'es': "Pantalla"