Localizza con lo scripting

*Questo contenuto è tradotto usando AI (Beta) e potrebbe contenere errori. Per visualizzare questa pagina in inglese, clicca qui.

Puoi utilizzare le API di localizzazione per compiti di traduzione specializzati che non vengono gestiti automaticamente aggiungendo traduzioni nella tabella di localizzazione. Roblox fornisce un LocalizationService per gestire tutte le esigenze di scripting della localizzazione. Utilizza il LocalizationService per i seguenti compiti:

Se utilizzi delle API di localizzazione quando traduci il tuo gioco, ascolta eventuali cambiamenti nell'LocaleID dell'utente per reagire al cambio di lingua degli utenti mentre si trova in un gioco.

Quando riutilizzi il codice di traduzione, dovresti usare un TranslationHelper ModuleScript per gestire errori e traduzioni mancanti.

Localizza immagini e suoni

Aggiungi localizzazione oltre il testo nel tuo gioco fornendo immagini e suoni unici basati sul locale di un utente. Per localizzare le risorse, prima aggiungi gli ID delle risorse sorgente e di destinazione nella tabella di localizzazione del tuo gioco, quindi utilizza l'API di localizzazione per recuperare le diverse risorse.

Inglese (Sorgente) - rbxassetid://2957093606
Spagnolo (es) - rbxassetid://2957093671
Portoghese (pt) - rbxassetid://2957093727

Per iniziare a localizzare immagini e suoni, aggiungi i tuoi ID delle risorse sorgente e di destinazione alla tua tabella di localizzazione. Le voci degli ID delle risorse nella tabella di localizzazione devono includere una Chiave come identificatore da chiamare tramite l'API.

Di seguito è riportato un esempio di voce in una tabella di localizzazione utilizzando gli ID delle risorse:

ChiaveSorgenteespt
Key_JewelsImage295709360629570936712957093727

Il seguente codice sostituirà l'ID della risorsa di un ImageLabel con l'ID della risorsa spagnola fornito nella tabella di localizzazione:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Variabili locali
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- Carica il traduttore per "es". Avvolgi la funzione all'interno di una pcall() per proteggerti da errori.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Ottieni l'ID della risorsa dalla tabella di localizzazione facendo riferimento alla Chiave
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- Imposta l'immagine
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Traduci stringhe singole

In alcune circostanze, potresti voler prenderti cura di singole stringhe per la traduzione. Translator:Translate() può recuperare voci singole nella tabella di localizzazione basate sulla stringa sorgente.

Nell'esempio successivo, viene utilizzata la seguente voce di localizzazione:

Sorgenteesespt
SchermoPantalla2950936712957093727

Il seguente script stamperà la traduzione spagnola di "Screen" nella finestra Output:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Carica il traduttore per "es". Avvolgi la funzione all'interno di una pcall() per proteggerti da errori.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Usa la funzione Translate, fornendo il contesto dell'oggetto e la stringa
local sourceTranslation = translator:Translate(game, "Screen")
print(sourceTranslation) -- Output previsto: "Pantalla"
else
print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Usa le sostituzioni di contesto

Ci sono alcuni casi in cui la stessa stringa può avere significati diversi. Ad esempio, la parola "Screen" può indicare sia uno schermo di computer che uno schermo di finestra, ma le traduzioni spagnole sono completamente diverse.

La Colonna di Contesto della tabella di localizzazione è per specificare traduzioni attraverso sostituzioni di contesto. Specifica l'oggetto di gioco nella tua tabella di localizzazione come nel seguente esempio:

ContestoSorgentees
workspace.WindowScreen.SurfaceGui.TextLabelScreenMosquitero
ScreenPantalla

Il seguente script utilizza una sostituzione di contesto per dare priorità a una traduzione specifica:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- Carica il traduttore per "es". Avvolgi la funzione all'interno di una pcall() per proteggerti da errori.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- usa la funzione Translate, fornendo il contesto dell'oggetto e la stringa
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
print(sourceTranslation) -- Output previsto: Mosquitero
else
print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Contesti multipli

Nel caso di contesti multipli, il servizio di localizzazione confronta le relazioni degli oggetti nel campo Contesto da destra a sinistra, utilizzando la corrispondenza più vicina.

Ad esempio, una tabella di localizzazione nel tuo gioco potrebbe avere le seguenti voci di stringhe sorgenti condivise:

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

Se la stringa "Screen" viene aggiunta a un oggetto playerGui.ScreenGui.TextLabel nel tuo gioco, il servizio di localizzazione visualizzerà "Mosquitero" come traduzione spagnola poiché è la corrispondenza di contesto più vicina.

Sostituisci parametri

Quando utilizzi parametri per tradurre contenuti dinamici, imposta i valori su una tabella e passa la tabella come argomento tramite l'API.

In questo esempio, il gioco ha una tabella di localizzazione con le seguenti voci:

ChiaveSorgentees
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

Utilizza il seguente campione di codice per tradurre queste stringhe con valori di parametro:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Carica il traduttore per "es". Avvolgi la funzione all'interno di una pcall() per proteggerti da errori.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Imposta il valore del parametro in "Key_Prize_1" a 100
local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
print(keyTranslation1) -- Output previsto: 100 joyas
-- Imposta parametri multipli a 500 e 100 per nome
local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
print(keyTranslation2) -- Output previsto: $500.00 dinero y 100 joyas
else
print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Cambia lingua

In alcuni casi, potresti voler visualizzare traduzioni di altre lingue nel tuo gioco. Puoi impostare un nuovo traduttore con un codice paese diverso utilizzando LocalizationService:GetTranslatorForLocaleAsync().

Il seguente campione di codice imposta un traduttore con un codice paese manuale e un traduttore aggiuntivo in base alle impostazioni locali globali dell'utente:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Variabili locali
local player = Players.LocalPlayer
-- Carica il traduttore per "pt". Avvolgi le funzioni del traduttore all'interno di una pcall() per proteggerti da errori.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- Carica il secondo traduttore con il locale del giocatore, in questo esempio "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Usa la funzione Translate con il primo traduttore
if res1 then
local translate1 = translator:Translate(game, "jewels")
print(translate1) -- Output previsto in pt: joyas
else
print('GetTranslatorForPlayerAsync failed: ' .. translator)
end
-- Usa la funzione Translate con il secondo traduttore
if res2 then
local translate2 = fallbackTranslator:Translate(game, "jewels")
print(translate2) -- Output previsto se l'utente è impostato su 'es': jóias
else
print('GetTranslatorForPlayerAsync failed: ' .. fallbackTranslator)
end

Reagisci al cambio di lingua degli utenti

Gli utenti possono cambiare le loro impostazioni di lingua in qualsiasi momento utilizzando il menu Impostazioni in gioco. Questa modifica delle impostazioni utente aggiorna automaticamente le risorse di localizzazione non scripting, come le stringhe gestite da traduzioni automatiche, ma potrebbe non aggiornare le modifiche di localizzazione scriptate che sono già state renderizzate, come le immagini o i suoni dell'interfaccia grafica.

Impostazione della lingua in gioco
Gli utenti possono scegliere le lingue disponibili impostate nel gioco

Per garantire che le tue risorse localizzate tramite scripting si aggiornino correttamente, ascolta l'evento GetPropertyChangedSignal per i cambiamenti nella proprietà LocaleID dell'istanza Translator restituita da LocalizationService.GetTranslatorForPlayerAsync. Quando utilizzi LocalizationService.GetTranslatorForPlayerAsync, avvolgi la funzione all'interno di un pcall() in caso di errori.

Il seguente campione di codice stampa l'ID del locale dell'utente e l'ID del locale dell'istanza traduttore per l'utente quando questi cambia lingua:


local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Se GetTranslatorForPlayerAsync ha successo, restituirà un traduttore per il locale attuale del giocatore
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Funzione che viene chiamata quando viene rilevato un cambiamento nell'ID locale del giocatore
local function OnLocaleIdChanged()
print("Il traduttore è cambiato in: " .. translator.LocaleId)
-- Qui dovresti ritradurre eventuali risorse tradotte con le API di localizzazione nella nuova lingua del giocatore
end
-- Controlla se GetTranslatorForPlayerAsync ha avuto successo
if res then
-- Se ha avuto successo, traduci le risorse qui utilizzando il traduttore
-- Ascolta un cambiamento nell'ID locale del giocatore
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Crea un modulo TranslationHelper

Quando carichi traduttori in base al locale predefinito del giocatore, potresti riutilizzare il codice. Per riutilizzare il codice, configura un ModuleScript helper che carichi in sicurezza i traduttori in base al locale predefinito del giocatore e includa funzioni per fornire traduzioni specifiche e cambiare lingua.

Il seguente campione di codice implementa un TranslationHelper che puoi copiare nel tuo progetto come ModuleScript in ReplicatedStorage:


local TranslationHelper = {}
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Variabili locali
local player = Players.LocalPlayer
local sourceLanguageCode = "en"
-- Ottieni traduttori
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
-- Crea un metodo TranslationHelper.setLanguage per caricare una nuova traduzione per il TranslationHelper
function TranslationHelper.setLanguage(newLanguageCode)
if sourceLanguageCode ~= newLanguageCode then
local success, newPlayerTranslator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
end)
-- Sovrascrivi solo il playerTranslator corrente se il nuovo è valido (fallbackTranslator rimane come lingua sorgente del gioco)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- Crea una funzione Translate che utilizza un traduttore di fallback se il primo non riesce a caricare o restituire con successo. Puoi anche impostare l'oggetto di riferimento per default all'oggetto generico
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 funzione FormatByKey() che utilizza un traduttore di fallback se il primo non riesce a caricare o restituire con successo
function TranslationHelper.translateByKey(key, arguments)
local translation = ""
local foundTranslation = false
-- Prima cerca di tradurre per la lingua del giocatore (se è stato trovato un traduttore)
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 volta che il modulo è in ReplicatedStorage, richiamalo da uno LocalScript per chiamare le funzioni del modulo. Il seguente codice utilizza la funzione helper di questo modulo per tradurre una stringa singola:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- Richiama il modulo di traduzione
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))
-- Usa le funzioni fornite in TranslationHelper
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Output previsto in 'es': "Pantalla"
© 2026 Roblox Corporation. Roblox, il logo Roblox e Powering Imagination sono tra i nostri marchi registrati e non registrati negli Stati Uniti. e altri paesi.