Możesz używać interfejsów API lokalizacji do specjalistycznych zadań tłumaczeniowych, które nie są automatycznie obsługiwane przez dodawanie tłumaczeń do tabeli lokalizacji. Roblox zapewnia LocalizationService do obsługi wszystkich potrzeb związanych z lokalizacją w skryptach. Użyj LocalizationService do następujących zadań:
Jeśli używasz jakichkolwiek interfejsów API lokalizacji podczas tłumaczenia swojej gry, nasłuchuj wszelkich zmian w LocaleID użytkownika, aby reagować na przełączanie języków przez użytkowników podczas gry.
Podczas ponownego używania kodu tłumaczenia powinieneś skorzystać z TranslationHelper ModuleScript, aby obsługiwać błędy i brakujące tłumaczenia.
Lokalizuj obrazy i dźwięki
Dodaj lokalizację poza tekstem w swojej grze, zapewniając unikalne obrazy i dźwięki w zależności od lokalizacji użytkownika. Aby zlokalizować zasoby, najpierw dodaj identyfikatory źródłowych i docelowych zasobów do tabeli lokalizacji, a następnie użyj interfejsu API lokalizacji, aby pobrać różne zasoby.



Aby rozpocząć lokalizację obrazów i dźwięków, dodaj swoje identyfikatory źródłowe i docelowe do tabeli lokalizacji. Wpisy identyfikatorów zasobów w tabeli lokalizacji muszą zawierać Klucz jako identyfikator, który będzie wywoływany przez API.
Poniżej znajduje się przykład wpisu w tabeli lokalizacji używającej identyfikatorów zasobów:
| Klucz | Źródło | es | pt |
|---|---|---|---|
| Key_JewelsImage | 2957093606 | 2957093671 | 2957093727 |
Poniższy kod zastąpi identyfikator zasobu ImageLabel identyfikatorem zasobu hiszpańskiego podanym w tabeli lokalizacji:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Lokalne zmienne
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- Załaduj translatora dla "es". Opakuj funkcję w pcall(), aby chronić przed błędami.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Pobierz identyfikator zasobu z tabeli lokalizacji, odnosząc się do Klucza
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- Ustaw obraz
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('GetTranslatorForPlayerAsync nie powiodło się: ' .. translator)
end
Tłumacz poszczególne napisy
W niektórych okolicznościach możesz chcieć skupić się na tłumaczeniu poszczególnych napisów. Translator:Translate() może pobierać poszczególne wpisy na tabeli lokalizacji na podstawie źródłowego napisu.
W następującym przykładzie używana jest następująca pozycja lokalizacji:
| Źródło | es | es | pt |
|---|---|---|---|
| Ekran | Pantalla | 295093671 | 2957093727 |
Poniższy skrypt wydrukuje hiszpańskie tłumaczenie słowa "Ekran" w oknie Wyjście:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Załaduj translatora dla "es". Opakuj funkcję w pcall(), aby chronić przed błędami.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Użyj funkcji Translate, zapewniając kontekst obiektu i napis
local sourceTranslation = translator:Translate(game, "Screen")
print(sourceTranslation) -- Oczekiwany wynik: "Pantalla"
else
print('GetTranslatorForPlayerAsync nie powiodło się: ' .. translator)
end
Używaj nadpisywania kontekstu
Zdarzają się przypadki, w których ten sam napis może mieć wiele znaczeń. Na przykład słowo "Ekran" może wskazywać zarówno na ekran komputera, jak i ekran okna, ale tłumaczenia hiszpańskie są całkowicie różne.
Kolumna Kontekst tabeli lokalizacji służy do określenia tłumaczeń za pomocą nadpisywania kontekstu. Określ obiekt w grze w swojej tabeli lokalizacji, jak w poniższym przykładzie:
| Kontekst | Źródło | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Ekran | Mosquitero |
| Ekran | Pantalla |
Poniższy skrypt używa nadpisania kontekstu, aby nadać priorytet określonemu tłumaczeniu:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- Załaduj translatora dla "es". Opakuj funkcję w pcall(), aby chronić przed błędami.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- użyj funkcji Translate, zapewniając kontekst obiektu i napis
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
print(sourceTranslation) -- Oczekiwany wynik: Mosquitero
else
print('GetTranslatorForPlayerAsync nie powiodło się: ' .. translator)
end
Wiele kontekstów
W przypadku wielu kontekstów usługa lokalizacji porównuje relacje obiektów w polu Kontekst od prawej do lewej, używając najbliższego dopasowania.
Na przykład tabela lokalizacji w twojej grze może mieć następujące wspólne wpisy dla napisów Źródłowych:
| Kontekst | Źródło | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Ekran | Mosquitero |
| playerGui.ScreenGui.TextButton | Ekran | Pantalla |
Jeśli napis "Ekran" zostanie dodany do obiektu playerGui.ScreenGui.TextLabel w twojej grze, usługa lokalizacji wyświetli "Mosquitero" jako hiszpańskie tłumaczenie, ponieważ to jest najbliższe dopasowanie kontekstu.
Zastąp parametry
Podczas używania parametrów do tłumaczenia dynamicznych treści ustaw wartości w tabeli i przekaż tabelę jako argument przez API.
W tym przykładzie gra ma tabelę lokalizacji z następującymi wpisami:
| Klucz | Źródło | 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 |
Użyj następującego przykładu kodu, aby przetłumaczyć te napisy z wartościami parametrów:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Załaduj translatora dla "es". Opakuj funkcję w pcall(), aby chronić przed błędami.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Ustaw wartość parametru w "Key_Prize_1" na 100
local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
print(keyTranslation1) -- Oczekiwany wynik: 100 joyas
-- Ustaw wiele parametrów na 500 i 100 nazwami
local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
print(keyTranslation2) -- Oczekiwany wynik: $500.00 dinero y 100 joyas
else
print('GetTranslatorForPlayerAsync nie powiodło się: ' .. translator)
end
Zmiana języków
W niektórych przypadkach możesz chcieć wyświetlić tłumaczenia w innych językach w swojej grze. Możesz ustawić nowego translatora z innym kodem kraju używając LocalizationService:GetTranslatorForLocaleAsync().
Poniższy przykład kodu ustawia jednego translatora z ręcznie wprowadzonym kodem kraju i dodatkowego translatora bazującego na globalnych ustawieniach lokalnych użytkownika:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Lokalne zmienne
local player = Players.LocalPlayer
-- Załaduj translatora dla "pt". Opakuj funkcje tłumaczenia w pcall(), aby chronić przed błędami.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- Załaduj drugiego translatora z lokalizacją gracza, w tym przykładzie "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Użyj funkcji Translate z pierwszym tłumaczem
if res1 then
local translate1 = translator:Translate(game, "jewels")
print(translate1) -- Oczekiwany wynik w pt: joyas
else
print('GetTranslatorForPlayerAsync nie powiodło się: ' .. translator)
end
-- Użyj funkcji Translate z drugim tłumaczem
if res2 then
local translate2 = fallbackTranslator:Translate(game, "jewels")
print(translate2) -- Oczekiwany wynik, jeśli użytkownik ma ustawiony 'es': jóias
else
print('GetTranslatorForPlayerAsync nie powiodło się: ' .. fallbackTranslator)
end
Reaguj na zmiany języków przez użytkowników
Użytkownicy mogą zmieniać swoje ustawienia językowe w dowolnym momencie, korzystając z menu Ustawienia w grze. Ta zmiana ustawienia przez użytkownika automatycznie aktualizuje zasoby lokalizacji nienaładowane przez skrypty, takie jak napisy obsługiwane przez automatyczne tłumaczenie, ale może nie aktualizować zmian lokalizacyjnych w skryptach, które zostały już wyrenderowane, takich jak obrazy GUI czy dźwięki.


Aby upewnić się, że Twoje zasoby lokalizowane w skryptach aktualizują się poprawnie, nasłuchuj zdarzenia GetPropertyChangedSignal dla zmian w właściwości LocaleID instancji Translator zwróconej przez LocalizationService.GetTranslatorForPlayerAsync. Podczas używania LocalizationService.GetTranslatorForPlayerAsync opakuj funkcję w pcall() w przypadku błędów.
Poniższy przykład kodu wydrukuje ID lokalizacji użytkownika oraz ID lokalizacji instancji Translator dla użytkownika, gdy użytkownik przełącza języki:
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Jeśli GetTranslatorForPlayerAsync się powiedzie, zwróci translatora dla obecnej lokalizacji gracza
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Funkcja, która zostaje wywołana, gdy zostanie wykryta zmiana ID lokalizacji gracza
local function OnLocaleIdChanged()
print("Translator zmienił się na: " .. translator.LocaleId)
-- Powinieneś ponownie przetłumaczyć wszelkie zasoby przetłumaczone za pomocą interfejsów API lokalizacji na nowy język gracza
end
-- Sprawdź, czy GetTranslatorForPlayerAsync się powiodło
if res then
-- Jeśli się powiodło, przetłumacz zasoby korzystając z translatora
-- Nasłuchuj na zmiany ID lokalizacji gracza
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('GetTranslatorForPlayerAsync nie powiodło się: ' .. translator)
end
Stwórz moduł TranslationHelper
Kiedy ładujesz tłumaczy na podstawie domyślnej lokalizacji gracza, możesz ponownie używać kodu. Aby powtórzyć kod, utwórz pomocniczy ModuleScript, który bezpiecznie ładuje tłumaczy na podstawie domyślnej lokalizacji gracza i zawiera funkcje do dostarczania konkretnych tłumaczeń i przełączania języków.
Poniższy przykład kodu implementuje TranslationHelper, który możesz skopiować do swojego projektu jako ModuleScript w ReplicatedStorage:
local TranslationHelper = {}
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Lokalne zmienne
local player = Players.LocalPlayer
local sourceLanguageCode = "en"
-- Pobierz tłumaczy
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
-- Utwórz metodę TranslationHelper.setLanguage, aby załadować nowe tłumaczenie dla TranslationHelper
function TranslationHelper.setLanguage(newLanguageCode)
if sourceLanguageCode ~= newLanguageCode then
local success, newPlayerTranslator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
end)
-- Tylko nadpisuj aktualnego playerTranslator, jeśli nowy jest ważny (fallbackTranslator pozostaje jako źródłowy język gry)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- Utwórz funkcję Translate, która wykorzystuje fallback translatora, jeśli pierwszy nie uda się załadować lub nie zwrócił sukcesu. Możesz również ustawić referencjowany obiekt jako domyślnie ogólny obiekt
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
-- Utwórz funkcję FormatByKey(), która wykorzystuje fallback translatora, jeśli pierwszy nie uda się załadować lub nie zwrócił sukcesu
function TranslationHelper.translateByKey(key, arguments)
local translation = ""
local foundTranslation = false
-- Po pierwsze próbuje tłumaczyć dla języka gracza (jeśli znaleziono tłumacza)
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
Gdy moduł znajduje się w ReplicatedStorage, załaduj go z LocalScript, aby wywołać funkcje modułu. Poniższy kod używa funkcji pomocniczej tego modułu do przetłumaczenia poszczególnego napisu:
local ReplicatedStorage = game:GetService("ReplicatedStorage")-- Załaduj moduł tłumaczenialocal TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))-- Użyj funkcji dostępnych w TranslationHelperTranslationHelper.setLanguage("es")local sourceTranslation = TranslationHelper.translate("Screen")print(sourceTranslation) -- Oczekiwany wynik w 'es': "Pantalla"