يمكنك استخدام واجهات برمجة التطبيقات للتعريب لمهام الترجمة المتخصصة التي لا يتم التعامل معها تلقائيًا من خلال إضافة الترجمات إلى جدول التعريب. يوفر Roblox خدمة LocalizationService للتعامل مع جميع احتياجات البرمجة الخاصة بالتعريب. استخدم LocalizationService للمهام التالية:
إذا كنت تستخدم أيًا من واجهات برمجة التطبيقات للتعريب عند ترجمة لعبتك، انتبه لأي تغييرات في مُعرف اللغة (LocaleID) للمستخدم للـ رد على المستخدمين عندما يغيرون لغتهم أثناء اللعب.
عند إعادة استخدام كود الترجمة، يجب استخدام وحدة برمجية TranslationHelper للتعامل مع الأخطاء والترجمات المفقودة.
تعريب الصور والأصوات
أضف التعريب بخلاف النص في لعبتك عن طريق توفير صور وأصوات فريدة بناءً على لغة المستخدم. لتعريب الأصول، أضف أولاً معرفات المصدر والهدف إلى جدول التعريب للعبتك ثم استخدم واجهة برمجة التطبيقات للتعريب لاسترجاع الأصول المختلفة.



للبدء في تعريب الصور والأصوات، أضف معرفات الأصول المصدر والهدف إلى جدول التعريب الخاص بك. يجب أن تتضمن إدخالات معرف الأصول في جدول التعريب مفتاح كمعرّف لاستدعائه عبر واجهة برمجة التطبيقات.
فيما يلي مثال على إدخال في جدول التعريب باستخدام معرفات الأصول:
| المفتاح | المصدر | es | pt |
|---|---|---|---|
| Key_JewelsImage | 2957093606 | 2957093671 | 2957093727 |
سيستبدل الكود التالي معرف الأصول في ImageLabel بمعرف الأصول الإسباني الذي توفره جدول التعريب:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- المتغيرات المحلية
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- تحميل المترجم لـ "es". اختر دالة داخل pcall() لحمايتها من الأخطاء.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- الحصول على معرف الأصول من جدول التعريب عن طريق الإشارة إلى المفتاح
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- تعيين الصورة
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('فشل GetTranslatorForPlayerAsync: ' .. translator)
end
ترجمة السلاسل الفردية
في بعض الحالات، قد ترغب في استهداف سلاسل فردية للترجمة. Translator:Translate() يمكن أن يجلب إدخالات فردية من جدول التعريب استنادًا إلى السلسلة المصدر.
في المثال التالي، يتم استخدام إدخال التعريب التالي:
| المصدر | es | es | pt |
|---|---|---|---|
| الشاشة | Pantalla | 295093671 | 2957093727 |
سوف يطبع السكربت التالي الترجمة الإسبانية لكلمة "الشاشة" إلى نافذة الإخراج:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- تحميل المترجم لـ "es". اختر دالة داخل pcall() لحمايتها من الأخطاء.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- استخدام دالة Translate، مع توفير سياق الكائن والسلسلة
local sourceTranslation = translator:Translate(game, "Screen")
print(sourceTranslation) -- الناتج المتوقع: "Pantalla"
else
print('فشل GetTranslatorForPlayerAsync: ' .. translator)
end
استخدام تجاوزات السياق
هناك بعض الحالات التي قد تعني فيها نفس السلسلة معاني متعددة. على سبيل المثال، يمكن أن تشير كلمة "الشاشة" إلى كل من شاشة الكمبيوتر وشاشة النافذة، لكن الترجمات الإسبانية تختلف تمامًا.
عمود السياق في جدول التعريب مخصص لتحديد الترجمات من خلال تجاوزات السياق. حدد كائن اللعبة في جدول التعريب الخاص بك كما في المثال التالي:
| السياق | المصدر | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | الشاشة | Mosquitero |
| الشاشة | Pantalla |
يستخدم السكربت التالي تجاوز سياق لإعطاء الأولوية لترجمة معينة:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- تحميل المترجم لـ "es". اختر دالة داخل pcall() لحمايتها من الأخطاء.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- استخدام دالة Translate، مع توفير سياق الكائن والسلسلة
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
print(sourceTranslation) -- الناتج المتوقع: Mosquitero
else
print('فشل GetTranslatorForPlayerAsync: ' .. translator)
end
السياقات المتعددة
في حالة وجود سياقات متعددة، يقارن خدمة التعريب علاقات الكائنات في حقل السياق من اليمين إلى اليسار، باستخدام أقرب تطابق.
على سبيل المثال، قد يحتوي جدول التعريب في لعبتك على إدخالات سلسلة المصدر المشتركة التالية:
| السياق | المصدر | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | الشاشة | Mosquitero |
| playerGui.ScreenGui.TextButton | الشاشة | Pantalla |
إذا تمت إضافة السلسلة "الشاشة" إلى كائن playerGui.ScreenGui.TextLabel في لعبتك، تعرض خدمة التعريب "Mosquitero" كترجمة إسبانية باعتبارها أقرب تطابق للسياق.
استبدال المعلمات
عند استخدام المعلمات لترجمة محتوى ديناميكي، عيّن القيم في جدول ومرر الجدول كمعامل من خلال واجهة برمجة التطبيقات.
في هذا المثال، تحتوي اللعبة على جدول تعريب يحتوي على الإدخالات التالية:
| المفتاح | المصدر | es |
|---|---|---|
| Key_Prize_1 | {1:int} مجوهرات | {1:int} joyas |
| Key_Prize_2 | ${AmountCash:fixed} نقد و {NumJewels:int} مجوهرات | ${AmountCash:fixed} dinero y {NumJewels:int} joyas |
استخدم نموذج الكود التالي لترجمة هذه السلاسل بقيم المعلمات:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- تحميل المترجم لـ "es". اختر دالة داخل pcall() لحمايتها من الأخطاء.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- تعيين قيمة المعلمة في "Key_Prize_1" إلى 100
local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
print(keyTranslation1) -- الناتج المتوقع: 100 joyas
-- تعيين قيم المعلمات المتعددة إلى 500 و 100 بالاسم
local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
print(keyTranslation2) -- الناتج المتوقع: $500.00 dinero y 100 joyas
else
print('فشل GetTranslatorForPlayerAsync: ' .. translator)
end
تغيير اللغات
في بعض الحالات، قد ترغب في عرض ترجمات للغات الأخرى في لعبتك. يمكنك تعيين مترجم جديد برمز بلد مختلف باستخدام LocalizationService:GetTranslatorForLocaleAsync().
نموذج الكود التالي يعين مترجم واحد برمز بلد يدوي ومترجم إضافي استنادًا إلى إعدادات اللغة العالمية للمستخدم:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- المتغيرات المحلية
local player = Players.LocalPlayer
-- تحميل المترجم لـ "pt". اختر دالة داخل pcall() لحمايتها من الأخطاء.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- تحميل المترجم الثاني بلكنة اللاعب، في هذا المثال "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- استخدم دالة Translate مع المترجم الأول
if res1 then
local translate1 = translator:Translate(game, "مجوهرات")
print(translate1) -- الناتج المتوقع في pt: joyas
else
print('فشل GetTranslatorForPlayerAsync: ' .. translator)
end
-- استخدم دالة Translate مع المترجم الثاني
if res2 then
local translate2 = fallbackTranslator:Translate(game, "مجوهرات")
print(translate2) -- الناتج المتوقع إذا كان المستخدم مضبوطًا على 'es': jóias
else
print('فشل GetTranslatorForPlayerAsync: ' .. fallbackTranslator)
end
رد على تغيير المستخدمين للغات
يمكن للمستخدمين تغيير إعدادات لغتهم في أي وقت باستخدام قائمة الإعدادات داخل اللعبة. يغير هذا الإعداد للمستخدم تلقائيًا الأصول التعريب غير البرمجية، مثل السلاسل التي تتعامل معها الترجمة التلقائية، ولكن قد لا يقوم بتحديث التغييرات البرمجية للتعريب التي تم عرضها بالفعل، مثل صور الواجهة أو الأصوات.


لتضمن أن الأصول المترجمة برمجيًا يتم تحديثها بشكل صحيح، استمع إلى حدث GetPropertyChangedSignal للتغييرات في خاصية LocaleID الخاصة بالنسخة Translator التي يتم إرجاعها بواسطة LocalizationService.GetTranslatorForPlayerAsync. عند استخدام LocalizationService.GetTranslatorForPlayerAsync, قم بإحاطة الوظيفة داخل pcall() في حالة حدوث أخطاء.
نموذج الكود التالي يطبع معرف اللغة الخاص بالمستخدم ومعرف اللغة الخاص بنسخة المترجم للمستخدم عندما يقوم المستخدم بتغيير اللغات:
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- إذا كانت GetTranslatorForPlayerAsync ناجحة، ستعيد مترجم للغة الحالية للاعب
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- وظيفة يتم استدعاؤها عند الكشف عن تغيير في معرف لغة اللاعب
local function OnLocaleIdChanged()
print("تغيير المترجم إلى: " .. translator.LocaleId)
-- يجب عليك إعادة ترجمة أي أصول مترجمة باستخدام واجهات برمجة التطبيقات للتعريب إلى لغة اللاعب الجديدة هنا
end
-- تحقق مما إذا كانت GetTranslatorForPlayerAsync قد نجحت
if res then
-- إذا نجحت، قم بترجمة الأصول هنا باستخدام المترجم
-- استمع إلى تغيير في معرف لغة اللاعب
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('فشل GetTranslatorForPlayerAsync: ' .. translator)
end
إنشاء وحدة TranslationHelper
عند تحميل المترجمين استنادًا إلى اللغة الافتراضية للاعب، قد تعيد استخدام الكود. لإعادة استخدام الكود، قم بإعداد وحدة برمجية ModuleScript تساعد في تحميل المترجمين استنادًا إلى اللغة الافتراضية للاعب وتضمين وظائف لتوفير الترجمات المحددة وتغيير اللغات.
نموذج الكود التالي ينفذ TranslationHelper الذي يمكنك نسخه إلى مشروعك كـ ModuleScript في ReplicatedStorage:
local TranslationHelper = {}
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- المتغيرات المحلية
local player = Players.LocalPlayer
local sourceLanguageCode = "en"
-- الحصول على المترجمين
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
-- إنشاء أسلوب TranslationHelper.setLanguage لتحميل ترجمات جديدة
function TranslationHelper.setLanguage(newLanguageCode)
if sourceLanguageCode ~= newLanguageCode then
local success, newPlayerTranslator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
end)
-- لا يعدل playerTranslator الحالي إلا إذا كانت الجديدة صالحة (تظل fallbackTranslator كلغة المصدر للعبة)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- إنشاء دالة Translate التي تستخدم المترجم الاحتياطي إذا فشل المترجم الأول في التحميل أو العودة بنجاح. يمكنك أيضًا تعيين الكائن المشار إليه ليكون افتراضيًا للكائن العام
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
-- إنشاء دالة FormatByKey() التي تستخدم المترجم الاحتياطي إذا فشل المترجم الأول في التحميل أو العودة بنجاح
function TranslationHelper.translateByKey(key, arguments)
local translation = ""
local foundTranslation = false
-- يقوم أولاً بمحاولة الترجمة للغة اللاعب (إذا تم العثور على مترجم)
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
بمجرد أن تكون الوحدة في ReplicatedStorage، قم باستدعائها من LocalScript لاستدعاء وظائف الوحدة. يستخدم الكود التالي دالة المساعدة لهذا الوحدة لترجمة سلسلة فردية:
local ReplicatedStorage = game:GetService("ReplicatedStorage")-- استدعاء وحدة الترجمةlocal TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))-- استخدم الوظائف المقدمة في TranslationHelperTranslationHelper.setLanguage("es")local sourceTranslation = TranslationHelper.translate("Screen")print(sourceTranslation) -- الناتج المتوقع في 'es': "Pantalla"