Localizar con scripting

*Este contenido se traduce usando la IA (Beta) y puede contener errores. Para ver esta página en inglés, haz clic en aquí.

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.

Inglés (Fuente) - rbxassetid://2957093606
Español (es) - rbxassetid://2957093671
Portugués (pt) - rbxassetid://2957093727

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:

ClaveFuenteespt
Key_JewelsImage295709360629570936712957093727

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:

Fuenteesespt
ScreenPantalla2950936712957093727

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:

ContextoFuentees
workspace.WindowScreen.SurfaceGui.TextLabelScreenMosquitero
ScreenPantalla

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:

ContextoFuentees
workspace.WindowScreen.SurfaceGui.TextLabelScreenMosquitero
playerGui.ScreenGui.TextButtonScreenPantalla

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:

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

Configuración de Idioma en el juego
Los usuarios pueden elegir entre los idiomas disponibles configurados en el juego

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ón
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))
-- Usar las funciones proporcionadas en TranslationHelper
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Salida esperada en 'es': "Pantalla"
©2026 Roblox Corporation. Roblox, el logotipo de Roblox y "Powering Imagination" son algunas de nuestras marcas registradas y no registradas en los Estados Unidos y otros países.