Mit Skripting lokalisieren

*Dieser Inhalt wurde mit KI (Beta) übersetzt und kann Fehler enthalten. Um diese Seite auf Englisch zu sehen, klicke hier.

Sie können Lokalisierungs-APIs für spezialisierte Übersetzungsaufgaben verwenden, die nicht automatisch durch Hinzufügen von Übersetzungen zur Lokalisierungstabelle behandelt werden. Roblox bietet einen LocalizationService, um alle Lokalisierungs-Scripting-Anforderungen zu erfüllen. Verwenden Sie den LocalizationService für die folgenden Aufgaben:

Wenn Sie in Ihrem Spiel Lokalisierungs-APIs verwenden, hören Sie auf Änderungen der LocaleID des Benutzers, um auf Sprachwechsel der Benutzer zu reagieren.

Bei der Wiederverwendung von Übersetzungscode sollten Sie ein TranslationHelper ModuleScript verwenden, um Fehler und fehlende Übersetzungen zu behandeln.

Lokalisieren von Bildern und Tönen

Fügen Sie Ihrer Lokalisierung über Texte hinaus hinzu, indem Sie einzigartige Bilder und Töne basierend auf der Sprache eines Benutzers bereitstellen. Um Assets zu lokalisieren, fügen Sie zuerst die Source- und Target-Asset-IDs in die Lokalisierungstabelle Ihres Spiels ein, und verwenden Sie dann die Lokalisierungs-API, um die verschiedenen Assets abzurufen.

Englisch (Quelle) - rbxassetid://2957093606
Spanisch (es) - rbxassetid://2957093671
Portugiesisch (pt) - rbxassetid://2957093727

Um mit der Lokalisierung von Bildern und Tönen zu beginnen, fügen Sie Ihre Source und Target Asset-IDs in Ihre Lokalisierungstabelle ein. Die Asset-ID-Einträge in der Lokalisierungstabelle müssen einen Key als Identifikator beinhalten, der von der API aufgerufen werden kann.

Das folgende Beispiel zeigt einen Eintrag in einer Lokalisierungstabelle mit Asset-IDs:

KeySourceespt
Key_JewelsImage295709360629570936712957093727

Der folgende Code ersetzt die Asset-ID eines ImageLabel mit der spanischen Asset-ID, die in der Lokalisierungstabelle bereitgestellt wird:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Lokale Variablen
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- Translator für "es" laden. Wickeln Sie die Funktion in eine pcall() ein, um gegen Fehler zu schützen.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Asset-ID aus der Lokalisierungstabelle abrufen, indem der Key referenziert wird
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- Das Bild festlegen
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('GetTranslatorForPlayerAsync ist fehlgeschlagen: ' .. translator)
end

Übersetzen einzelner Strings

In einigen Fällen möchten Sie möglicherweise einzelne Strings für die Übersetzung anvisieren. Translator:Translate() kann einzelne Einträge in der Lokalisierungstabelle basierend auf dem Quellstring abrufen.

Im nächsten Beispiel wird der folgende Lokalisierungseintrag verwendet:

Sourceesespt
ScreenPantalla2950936712957093727

Das folgende Skript gibt die spanische Übersetzung von "Screen" im Output-Fenster aus:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Translator für "es" laden. Wickeln Sie die Funktion in eine pcall() ein, um gegen Fehler zu schützen.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Funktion Translate verwenden, indem Objektkontext und String bereitgestellt werden
local sourceTranslation = translator:Translate(game, "Screen")
print(sourceTranslation) -- Erwartete Ausgabe: "Pantalla"
else
print('GetTranslatorForPlayerAsync ist fehlgeschlagen: ' .. translator)
end

Verwenden von Kontextüberschreibungen

Es gibt einige Fälle, in denen der gleiche String mehrere Bedeutungen haben kann. Zum Beispiel kann das Wort "Screen" sowohl einen Computermonitor als auch einen Fensterbildschirm bedeuten, aber die spanischen Übersetzungen sind vollkommen unterschiedlich.

Die Kontext-Spalte der Lokalisierungstabelle dient dazu, Übersetzungen durch Kontextüberschreibungen anzugeben. Geben Sie das Spielobjekt in Ihrer Lokalisierungstabelle wie im folgenden Beispiel an:

ContextSourcees
workspace.WindowScreen.SurfaceGui.TextLabelScreenMosquitero
ScreenPantalla

Das folgende Skript verwendet eine Kontextüberschreibung, um eine bestimmte Übersetzung zu priorisieren:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- Translator für "es" laden. Wickeln Sie die Funktion in eine pcall() ein, um gegen Fehler zu schützen.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Funktion Translate verwenden, indem Objektkontext und String bereitgestellt werden
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
print(sourceTranslation) -- Erwartete Ausgabe: Mosquitero
else
print('GetTranslatorForPlayerAsync ist fehlgeschlagen: ' .. translator)
end

Mehrere Kontexte

Im Falle mehrerer Kontexte vergleicht der Lokalisierungsdienst die Objektbeziehungen im Kontextfeld von rechts nach links und verwendet die nächstgelegene Übereinstimmung.

Zum Beispiel kann eine Lokalisierungstabelle in Ihrem Spiel die folgenden gemeinsamen Source-Strings-Einträge haben:

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

Wenn der String "Screen" an ein playerGui.ScreenGui.TextLabel-Objekt in Ihrem Spiel hinzugefügt wird, zeigt der Lokalisierungsdienst "Mosquitero" als die spanische Übersetzung an, da dies die nächstgelegene Kontextübereinstimmung ist.

Parameter ersetzen

Beim Verwenden von Parametern zur Übersetzung von dynamischem Inhalt legen Sie die Werte auf einer Tabelle fest und übergeben die Tabelle als Argument über die API.

In diesem Beispiel hat das Spiel eine Lokalisierungstabelle mit den folgenden Einträgen:

KeySourcees
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

Verwenden Sie das folgende Codebeispiel, um diese Strings mit Parameterwerten zu übersetzen:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Translator für "es" laden. Wickeln Sie die Funktion in eine pcall() ein, um gegen Fehler zu schützen.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Setzen Sie den Parameterwert in "Key_Prize_1" auf 100
local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
print(keyTranslation1) -- Erwartete Ausgabe: 100 joyas
-- Setzen Sie mehrere Parameter auf 500 und 100 nach Name
local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
print(keyTranslation2) -- Erwartete Ausgabe: $500.00 dinero y 100 joyas
else
print('GetTranslatorForPlayerAsync ist fehlgeschlagen: ' .. translator)
end

Sprachen wechseln

In einigen Fällen möchten Sie möglicherweise Übersetzungen anderer Sprachen in Ihrem Spiel anzeigen. Sie können einen neuen Translator mit einem anderen Ländercode mit LocalizationService:GetTranslatorForLocaleAsync() festlegen.

Das folgende Codebeispiel setzt einen Translator mit einem manuellen Ländercode und einen zusätzlichen Translator basierend auf den globalen Lokaleeinstellungen des Benutzers:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Lokale Variablen
local player = Players.LocalPlayer
-- Translator für "pt" laden. Wickeln Sie die Übersetzungsfunktionen in eine pcall() ein, um gegen Fehler zu schützen.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- Zweiten Translator mit der Sprache des Spielers laden, in diesem Beispiel "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Funktion Translate mit dem ersten Translator verwenden
if res1 then
local translate1 = translator:Translate(game, "jewels")
print(translate1) -- Erwartete Ausgabe in pt: joyas
else
print('GetTranslatorForPlayerAsync ist fehlgeschlagen: ' .. translator)
end
-- Funktion Translate mit dem zweiten Translator verwenden
if res2 then
local translate2 = fallbackTranslator:Translate(game, "jewels")
print(translate2) -- Erwartete Ausgabe, wenn der Benutzer auf 'es' eingestellt ist: jóias
else
print('GetTranslatorForPlayerAsync ist fehlgeschlagen: ' .. fallbackTranslator)
end

Auf Sprachwechsel der Benutzer reagieren

Benutzer können ihre Spracheinstellungen jederzeit über das In-Game-Einstellungsmenü ändern. Diese Änderung der Benutzereinstellung aktualisiert automatisch nicht-scripting Lokalisierungsressourcen wie Strings, die durch automatische Übersetzungen behandelt werden. Sie aktualisieren jedoch möglicherweise keine scripting-basierten Lokalisierungsänderungen, die bereits gerendert wurden, wie GUI-Bilder oder Töne.

In-Game-Spracheinstellung
Benutzer können verfügbare Sprachen wählen, die im Spiel festgelegt sind

Um sicherzustellen, dass Ihre skriptbezogenen lokalisierten Assets korrekt aktualisiert werden, hören Sie auf das GetPropertyChangedSignal-Ereignis für Änderungen an der LocaleID-Eigenschaft der Translator-Instanz, die von LocalizationService.GetTranslatorForPlayerAsync zurückgegeben wird. Wenn Sie LocalizationService.GetTranslatorForPlayerAsync verwenden, wickeln Sie die Funktion in eine pcall() ein, falls Fehler auftreten.

Das folgende Codebeispiel gibt die Locale-ID des Benutzers und die Locale-ID der Translator-Instanz für den Benutzer aus, wenn der Benutzer die Sprache wechselt:


local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Wenn GetTranslatorForPlayerAsync erfolgreich ist, wird ein Translator für die aktuelle Sprache des Spielers zurückgegeben
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Funktion, die aufgerufen wird, wenn eine Änderung der Locale-ID des Spielers erkannt wird
local function OnLocaleIdChanged()
print("Translator wurde geändert zu: " .. translator.LocaleId)
-- Sie sollten hier alle mit Lokalisierungs-APIs übersetzten Assets neu übersetzen, um die neue Sprache des Spielers zu berücksichtigen
end
-- Überprüfen, ob GetTranslatorForPlayerAsync erfolgreich war
if res then
-- Wenn erfolgreich, hier Assets mit dem Translator übersetzen
-- Auf eine Änderung der Locale-ID des Spielers hören
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('GetTranslatorForPlayerAsync ist fehlgeschlagen: ' .. translator)
end

Erstellen eines TranslationHelper-Modules

Wenn Sie Translator basierend auf der Standard-Sprache des Spielers laden, möchten Sie möglicherweise Code wiederverwenden. Um Code wiederzuverwenden, richten Sie ein Hilfs-ModuleScript ein, das sicher Translator basierend auf der Standard-Sprache des Spielers lädt und Funktionen zum Bereitstellen spezifischer Übersetzungen und zum Wechseln der Sprachen enthält.

Das folgende Codebeispiel implementiert ein TranslationHelper, das Sie als ModuleScript in ReplicatedStorage in Ihr eigenes Projekt kopieren können:


local TranslationHelper = {}
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Lokale Variablen
local player = Players.LocalPlayer
local sourceLanguageCode = "en"
-- Translator abrufen
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
-- Methode TranslationHelper.setLanguage erstellen, um eine neue Übersetzung für den TranslationHelper zu laden
function TranslationHelper.setLanguage(newLanguageCode)
if sourceLanguageCode ~= newLanguageCode then
local success, newPlayerTranslator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
end)
-- Nur den aktuellen playerTranslator überschreiben, wenn der neue gültig ist (fallbackTranslator bleibt as Spielers Ausgangssprache)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- Funktion Translate erstellen, die einen fallbackTranslator verwendet, wenn der erste nicht erfolgreich geladen oder zurückgegeben werden kann. Sie können das referenzierte Objekt auch standardmäßig auf das generische Objekt setzen
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
-- 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

Sobald das Modul in ReplicatedStorage ist, fordern Sie es von einem LocalScript an, um die Funktionen des Moduls aufzurufen. Der folgende Code verwendet diese Hilfsfunktion des Moduls, um einen einzelnen String zu übersetzen:


local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- Übersetzungsmodul anfordern
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))
-- Verwenden Sie die in TranslationHelper bereitgestellten Funktionen
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Erwartete Ausgabe in 'es': "Pantalla"
©2026 Roblox Corporation. Roblox, das Roblox-Logo und "Powering Imagination" gehören zu unseren eingetragenen und nicht eingetragenen Markenzeichen in den USA und anderen Ländern.