Bạn có thể sử dụng các API địa phương hóa cho các tác vụ dịch thuật chuyên biệt mà không được tự động xử lý bằng cách thêm bản dịch vào bảng địa phương hóa. Roblox cung cấp LocalizationService để xử lý tất cả các nhu cầu lập trình địa phương hóa. Sử dụng LocalizationService cho các tác vụ sau:
Nếu bạn sử dụng bất kỳ API địa phương hóa nào khi dịch trò chơi của mình, hãy lắng nghe bất kỳ thay đổi nào đối với LocaleID của người dùng để phản ứng với việc người dùng chuyển đổi ngôn ngữ trong khi chơi game.
Khi tái sử dụng mã dịch thuật, bạn nên sử dụng TranslationHelper ModuleScript để xử lý lỗi và các bản dịch bị thiếu.
Địa phương hóa hình ảnh và âm thanh
Thêm địa phương hóa ngoài văn bản trong trò chơi của bạn bằng cách cung cấp hình ảnh và âm thanh độc nhất dựa trên ngôn ngữ của người dùng. Để địa phương hóa tài sản, trước tiên hãy thêm mã nguồn và mã nhắm ID tài sản vào bảng địa phương hóa của trò chơi của bạn, sau đó sử dụng API địa phương hóa để lấy các tài sản khác nhau.



Để bắt đầu địa phương hóa hình ảnh và âm thanh, hãy thêm ID tài sản mã nguồn và mã nhắm vào bảng địa phương hóa của bạn. Các mục ID tài sản trong bảng địa phương hóa phải bao gồm một Khóa như một định danh để được gọi bởi API.
Dưới đây là ví dụ về một mục trong bảng địa phương hóa sử dụng ID tài sản:
| Khóa | Nguồn | es | pt |
|---|---|---|---|
| Key_JewelsImage | 2957093606 | 2957093671 | 2957093727 |
Mã sau đây sẽ thay thế ID tài sản của một ImageLabel bằng ID tài sản tiếng Tây Ban Nha được cung cấp trong bảng địa phương hóa:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Biến cục bộ
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- Tải Translator cho "es". Bao bọc chức năng trong một pcall() để bảo vệ khỏi các lỗi.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Lấy ID tài sản từ bảng địa phương hóa bằng cách tham chiếu đến Khóa
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- Đặt hình ảnh
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('GetTranslatorForPlayerAsync không thành công: ' .. translator)
end
Dịch các chuỗi cá nhân
Trong một số trường hợp, bạn có thể muốn nhắm đến các chuỗi cá nhân để dịch. Translator:Translate() có thể lấy các mục cá nhân trên bảng địa phương hóa dựa trên chuỗi nguồn.
Trong ví dụ tiếp theo, mục địa phương hóa sau đây được sử dụng:
| Nguồn | es | es | pt |
|---|---|---|---|
| Màn hình | Pantalla | 295093671 | 2957093727 |
Mã sau đây sẽ in ra bản dịch tiếng Tây Ban Nha của "Màn hình" vào cửa sổ Đầu ra:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Tải Translator cho "es". Bao bọc chức năng trong một pcall() để bảo vệ khỏi các lỗi.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Sử dụng hàm Dịch, cung cấp ngữ cảnh đối tượng và chuỗi
local sourceTranslation = translator:Translate(game, "Screen")
print(sourceTranslation) -- Dự kiến Đầu ra: "Pantalla"
else
print('GetTranslatorForPlayerAsync không thành công: ' .. translator)
end
Sử dụng ghi đè ngữ cảnh
Có một số trường hợp mà cùng một chuỗi có thể có nhiều nghĩa. Ví dụ, từ "Màn hình" có thể chỉ ra cả màn hình máy tính và màn hình cửa sổ, nhưng các bản dịch tiếng Tây Ban Nha là hoàn toàn khác nhau.
Cột Ngữ cảnh của bảng địa phương hóa là để chỉ định các bản dịch thông qua các ghi đè ngữ cảnh. Chỉ định đối tượng trong trò chơi của bạn trên bảng địa phương hóa của bạn như trong ví dụ sau:
| Ngữ cảnh | Nguồn | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Màn hình | Mosquitero |
| Màn hình | Pantalla |
Mã sau đây sử dụng một ghi đè ngữ cảnh để ưu tiên một bản dịch cụ thể:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- Tải Translator cho "es". Bao bọc chức năng trong một pcall() để bảo vệ khỏi các lỗi.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- sử dụng hàm Dịch, cung cấp ngữ cảnh đối tượng và chuỗi
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
print(sourceTranslation) -- Dự kiến Đầu ra: Mosquitero
else
print('GetTranslatorForPlayerAsync không thành công: ' .. translator)
end
Nhiều ngữ cảnh
Trong trường hợp có nhiều ngữ cảnh, dịch vụ địa phương hóa so sánh mối quan hệ của đối tượng trong trường Ngữ cảnh từ phải sang trái, sử dụng cái gần nhất.
Ví dụ, bảng địa phương hóa trong trò chơi của bạn có thể có các mục chuỗi Nguồn chia sẻ sau:
| Ngữ cảnh | Nguồn | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Màn hình | Mosquitero |
| playerGui.ScreenGui.TextButton | Màn hình | Pantalla |
Nếu chuỗi "Màn hình" được thêm vào một đối tượng playerGui.ScreenGui.TextLabel trong trò chơi của bạn, dịch vụ địa phương hóa sẽ hiển thị "Mosquitero" là bản dịch tiếng Tây Ban Nha do đó là ngữ cảnh gần nhất.
Thay thế tham số
Khi sử dụng tham số để dịch nội dung động, hãy đặt các giá trị vào một bảng và truyền bảng như một đối số qua API.
Trong ví dụ này, trò chơi có một bảng địa phương hóa với các mục sau:
| Khóa | Nguồn | 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 |
Sử dụng đoạn mã sau để dịch các chuỗi này với các giá trị tham số:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Tải Translator cho "es". Bao bọc chức năng trong một pcall() để bảo vệ khỏi các lỗi.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Đặt giá trị tham số trong "Key_Prize_1" thành 100
local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
print(keyTranslation1) -- Dự kiến Đầu ra: 100 joyas
-- Đặt nhiều tham số thành 500 và 100 theo tên
local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
print(keyTranslation2) -- Dự kiến Đầu ra: $500.00 dinero y 100 joyas
else
print('GetTranslatorForPlayerAsync không thành công: ' .. translator)
end
Chuyển đổi ngôn ngữ
Trong một số trường hợp, bạn có thể muốn hiển thị các bản dịch của các ngôn ngữ khác trong trò chơi của bạn. Bạn có thể thiết lập một dịch giả mới với mã quốc gia khác bằng cách sử dụng LocalizationService:GetTranslatorForLocaleAsync().
Mã mẫu sau đây thiết lập một dịch giả với mã quốc gia thủ công và một dịch giả bổ sung dựa trên cài đặt ngôn ngữ toàn cầu của người dùng:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Biến cục bộ
local player = Players.LocalPlayer
-- Tải Translator cho "pt". Bao bọc các chức năng dịch giả trong một pcall() để bảo vệ khỏi các lỗi.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- Tải dịch giả thứ hai với ngôn ngữ của Player, trong ví dụ này là "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Sử dụng hàm Dịch với Dịch giả đầu tiên
if res1 then
local translate1 = translator:Translate(game, "jewels")
print(translate1) -- Dự kiến Đầu ra bằng pt: joyas
else
print('GetTranslatorForPlayerAsync không thành công: ' .. translator)
end
-- Sử dụng hàm Dịch với Dịch giả thứ hai
if res2 then
local translate2 = fallbackTranslator:Translate(game, "jewels")
print(translate2) -- Dự kiến Đầu ra nếu người dùng được cài đặt là 'es': jóias
else
print('GetTranslatorForPlayerAsync không thành công: ' .. fallbackTranslator)
end
Phản ứng với việc người dùng chuyển đổi ngôn ngữ
Người dùng có thể thay đổi cài đặt ngôn ngữ của họ bất cứ lúc nào thông qua menu Cài đặt trong trò chơi. Thay đổi cài đặt người dùng này sẽ tự động cập nhật các tài sản địa phương hóa không lập trình, chẳng hạn như các chuỗi được xử lý bởi dịch tự động, nhưng có thể không cập nhật những thay đổi lập trình địa phương hóa đã được hiển thị, chẳng hạn như hình ảnh GUI hoặc âm thanh.


Để đảm bảo rằng các tài sản địa phương hóa lập trình của bạn được cập nhật chính xác, hãy lắng nghe sự kiện GetPropertyChangedSignal cho các thay đổi trong thuộc tính LocaleID của phiên bản Translator được trả về bởi LocalizationService.GetTranslatorForPlayerAsync. Khi sử dụng LocalizationService.GetTranslatorForPlayerAsync, hãy bao bọc chức năng trong một pcall() trong trường hợp có lỗi.
Mẫu mã sau sẽ in ra ID ngôn ngữ của người dùng và ID ngôn ngữ của phiên bản Translator cho người dùng khi người dùng chuyển đổi ngôn ngữ:
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Nếu GetTranslatorForPlayerAsync thành công, nó sẽ trả về một Translator cho ngôn ngữ hiện tại của người chơi
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Hàm sẽ được gọi khi phát hiện thay đổi ID ngôn ngữ của người chơi
local function OnLocaleIdChanged()
print("Dịch giả đã chuyển sang: " .. translator.LocaleId)
-- Bạn nên dịch lại bất kỳ tài sản nào được dịch bằng các API địa phương hóa cho ngôn ngữ mới của người chơi ở đây
end
-- Kiểm tra xem GetTranslatorForPlayerAsync có thành công không
if res then
-- Nếu thành công, dịch các tài sản ở đây bằng cách sử dụng dịch giả
-- Lắng nghe sự thay đổi trong ID ngôn ngữ của người chơi
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('GetTranslatorForPlayerAsync không thành công: ' .. translator)
end
Tạo một mô-đun TranslationHelper
Khi bạn tải các dịch giả dựa trên ngôn ngữ mặc định của người chơi, bạn có thể tái sử dụng mã. Để tái sử dụng mã, hãy thiết lập một ModuleScript trợ giúp an toàn tải các dịch giả dựa trên ngôn ngữ mặc định của người chơi và bao gồm các chức năng để cung cấp các bản dịch cụ thể và chuyển đổi ngôn ngữ.
Mẫu mã sau đây triển khai một TranslationHelper mà bạn có thể sao chép vào dự án của mình như một ModuleScript trong ReplicatedStorage:
local TranslationHelper = {}
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Biến cục bộ
local player = Players.LocalPlayer
local sourceLanguageCode = "en"
-- Lấy các dịch giả
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
-- Tạo một phương thức TranslationHelper.setLanguage để tải một bản dịch mới cho TranslationHelper
function TranslationHelper.setLanguage(newLanguageCode)
if sourceLanguageCode ~= newLanguageCode then
local success, newPlayerTranslator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
end)
-- Chỉ ghi đè dịch giả người chơi hiện tại nếu cái mới là hợp lệ (fall backTranslator vẫn giữ nguyên như ngôn ngữ nguồn của trò chơi)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- Tạo một hàm Dịch sử dụng dịch giả thay thế nếu cái đầu tiên không tải hoặc trả về thành công. Bạn cũng có thể đặt đối tượng tham chiếu để mặc định là đối tượng chung
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
-- Tạo một hàm FormatByKey() sử dụng dịch giả thay thế nếu cái đầu tiên không tải hoặc trả về thành công
function TranslationHelper.translateByKey(key, arguments)
local translation = ""
local foundTranslation = false
-- Đầu tiên cố gắng dịch cho ngôn ngữ của người chơi (nếu một dịch giả được tìm thấy)
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
Khi mô-đun nằm trong ReplicatedStorage, hãy yêu cầu nó từ một LocalScript để gọi các chức năng của mô-đun. Mã sau đây sử dụng hàm trợ giúp của mô-đun này để dịch một chuỗi cá nhân:
local ReplicatedStorage = game:GetService("ReplicatedStorage")-- Yêu cầu mô-đun dịchlocal TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))-- Sử dụng các chức năng được cung cấp trong TranslationHelperTranslationHelper.setLanguage("es")local sourceTranslation = TranslationHelper.translate("Screen")print(sourceTranslation) -- Dự kiến Đầu ra trong 'es': "Pantalla"