مرجع Transliterate API

التحويل الصوتي البسيط

تتيح لك الطريقة التالية إجراء عملية ترجمة صوتية بسيطة بدون واجهة مستخدم من خلال تعديل JavaScript.

الطريقة الوصف

google.language.transliterate(wordsArray, srcLang, destLang, callback)

‫google.language.transliterate(wordsArray, srcLang, destLang, callback) هي طريقة عالمية لنقل الحروف من اللغة المصدر إلى اللغة الهدف. تعرض واجهة برمجة التطبيقات النتيجة بشكل غير متزامن للدالة callback المحدّدة كالعنصر result. المَعلمات الخاصة بهذه الطريقة هي:

  • توفّر wordsArray النص المطلوب تحويله صوتيًا كمصفوفة.
  • توفّر srcLang اللغة المصدر كرمز لغة. راجِع التعداد LanguageCode للاطّلاع على أمثلة.
  • توفّر السمة destLang اللغة المستهدَفة كرمز لغة. راجِع التعداد LanguageCode للاطّلاع على أمثلة.
  • ‫callback هي دالة رد الاتصال التي تتلقّى result.

لا تعرض الدالة google.language.transliterate() أي قيمة.

تستخدم هذه الطريقة المبسّطة للترجمة الصوتية مساحة الاسم google.language.transliterate (وليس google.elements.transliteration، وهي مساحة الاسم لكل طريقة أخرى في Transliterate API).

تعرض google.language.transliterate() العنصر result.

يتم إنشاء عناصر النتائج باستخدام ترميز JSON لطلبات الخادم. نتيجةً لذلك، اخترنا عدم تنفيذ عناصر JavaScript الرسمية، وبدلاً من ذلك، أنشأنا عناصر result بشكلٍ ديناميكي من شكلها المتسلسل.

على الرغم من عدم وجود تنفيذ رسمي للعناصر، إلا أنّها متوفّرة، ونحن نوثّقها كما لو كان هناك تنفيذ JavaScript أساسي. ويكون تأثير كل ذلك ضئيلاً. كل ما يعنيه ذلك هو عدم توفّر دالة إنشاء مسماة. بالنسبة إلى كل نتيجة، يكون الأمر كما لو أنّ النظام استدعى new Object() ثم ضبط الخصائص الرسمية على هذا العنصر. في ما يلي هذه السمات.

  • <result>
    • error?
      يتم عرضها في حال حدوث خطأ في النقل الصوتي.
    • transliterations
      صفيف بحجم يساوي حجم الإدخال wordsArray
      • transliteratedWords
        مصفوفة بحجم 5 كحد أقصى، تحتوي على عمليات نقل صوتي للكلمة المقابلة في اللغة wordsArray.

مرجع JavaScript الخاص بأداة التحويل الصوتي

تتيح لك الدالة الإنشائية والطرق التالية إجراء عملية نقل صوتي ضمن واجهة مستخدم توفّرها واجهة برمجة التطبيقات.

الدالة الإنشائية - google.elements.transliteration.TransliterationControl(options)

الشركة المصنِّعة الوصف

google.elements.transliteration.
TransliterationControl(options)

تتيح .TransliterationControl(options) عملية الترجمة الصوتية على مجموعة من عناصر HTML DOM القابلة للتعديل، وتوفّر عددًا من الطرق التي تتيح لك التحكّم في الترجمة الصوتية في هذه العناصر. يمكن أن تتضمّن الوسيطة options الحقول التالية:

  • ‫sourceLanguage هي سلسلة إلزامية تحدّد اللغة المصدر باستخدام تعداد LanguageCode (كما في google.elements.transliteration.ENGLISH). في الوقت الحالي، اللغة الإنجليزية هي اللغة المصدر الوحيدة المتاحة.
  • ‫destinationLanguage هي مصفوفة إلزامية تحدّد اللغة الهدف باستخدام تعداد LanguageCode كما في (كما في google.elements.transliteration.HINDI ).

    في واجهة المستخدم، تظهر اللغات الهدف المتاحة في القائمة، مع تحديد اللغة الأولى في المصفوفة تلقائيًا. يُرجى الرجوع إلى getDestinationLanguages للحصول على مزيد من التفاصيل حول اللغات المقصودة الصالحة للغة مصدر معيّنة.
  • ‫transliterationEnabled هو حقل اختياري يحدّد ما إذا كان سيتم تفعيل الترجمة الصوتية تلقائيًا. إذا أردت تفعيل الترجمة الصوتية تلقائيًا، حدِّد هذا الحقل بالقيمة true. القيمة التلقائية هي false.
  • ‫shortcutKey هو حقل سلسلة اختياري يحدّد مفتاح اختصار لتفعيل أو إيقاف الترجمة الصوتية. لتحديد مفتاح الاختصار، حدِّد سلسلة تحتوي على أدوات تعديل مثل Ctrl أو Alt أو Shift مع حرف أبجدي. على سبيل المثال، "Ctrl+g" و"Ctrl+Shift+a" هما مجموعتان صالحتان من مفاتيح الاختصار.

    ملاحظة: لا يمكنك استخدام Shift كمعدِّل فقط، ولكن يمكنك استخدامه مع Alt أو Control.

تنشئ هذه الطريقة استثناءات في الحالات التالية:

  • sourceLanguage أو destinationLanguage غير صالح
  • اللغات غير المتاحة في زوج اللغات sourceLangauge وdestinationLanguage
  • مجموعة مفاتيح الاختصار غير صالحة

يوضّح مقتطف الرمز التالي كيفية إنشاء مثيل لعنصر التحكّم في الترجمة الصوتية: 

function onLoad() {
  var options = {
    sourceLanguage: 'en',
    destinationLanguage: ['hi'],
    shortcutKey: 'ctrl+g',
    transliterationEnabled: true
  };

  // Create an instance on TransliterationControl with the required
  // options.
  var control = new google.elements.transliteration.TransliterationControl(options);
}

طرق التحكّم في النقل الصوتي

يتم تنفيذ الطرق التالية في مساحة الاسم google.elements.transliteration.TransliterationControl.

الطريقة الوصف

.addEventListener(eventType, listener, opt_listenerScope)

تضيف .addEventListener(eventType, listener, opt_listenerScope) أداة معالجة إلى عنصر التحكّم في الكتابة الصوتية لنوع الحدث المحدّد. عندما يتم تشغيل نوع الحدث المعيّن، يتم استدعاء أداة الاستماع باستخدام عنصر الحدث. يعتمد محتوى عنصر الحدث على نوع الحدث. المَعلمات الخاصة بهذه الطريقة هي:

  • eventType هو الحدث الذي ستتم إضافة أداة المعالجة إليه. تستمدّ هذه الوسيطة قيمتها من تعداد eventType (مثل google.elements.transliteration.TransliterationControl. EventType.STATE_CHANGED).
  • توفّر listener دالة معالجة الحدث.
  • يستدعي opt_listenerScope أداة معالجة الأحداث مع ضبط this على الكائن المحدّد في opt_listenerScope.

لا تعرض الدالة .addEventListener() أي قيمة.

.disableTransliteration()

يؤدي .disableTransliteration() إلى إيقاف التحويل الصوتي في أداة التحكّم في التحويل الصوتي. لا تتضمّن هذه الطريقة وسيطات ولا تُرجع أي قيمة.

.enableTransliteration()

تتيح .enableTransliteration() استخدام ميزة "مناظرة الأحرف" في عنصر التحكّم في مناظرة الأحرف. لا تتضمّن هذه الطريقة وسيطات ولا تُرجع أي قيمة.

.isTransliterationEnabled()

لا تتضمّن الدالة .isTransliterationEnabled() أي وسيطات وتعرض قيمة منطقية تشير إلى ما إذا كانت ميزة الكتابة بحروف أجنبية مفعّلة في عنصر التحكّم في الكتابة بحروف أجنبية.

.makeTransliteratable(elementIds, opt_options)

تتيح .makeTransliteratable(elementIds, opt_options) عملية الترجمة الصوتية على عناصر HTML المقدَّمة. المَعلمات الخاصة بهذه الطريقة هي:

  • ‫elementIds هي مصفوفة تحتوي على سلاسل من معرّفات العناصر القابلة للتعديل أو مراجع العناصر التي تريد تفعيل الترجمة الصوتية لها. يمكن أن يكون العنصر القابل للتعديل:

    • حقل نص
    • مساحة نص
    • ‫ <div> مع contentEditable="true"
    • إطار <iframe> يتضمّن designMode="on"
    • إطار iFrame يتضمّن نصًا أساسيًا contentEditable="true" تأكَّد من تحميل إطار iFrame قبل تفعيل ميزة الكتابة الصوتية.
  • ‫opt_options هي وسيطة اختيارية توفّر الخيارات المطبّقة على هذه العناصر. يمكن أن تحتوي هذه الوسيطة على الحقول التالية:
    • ‫adjustElementStyle هو حقل منطقي اختياري يتحكّم في ما إذا كانت واجهة برمجة التطبيقات تعدّل تلقائيًا أحجام العناصر والخطوط لتناسب أحرف اللغة المستهدَفة على النحو الأمثل. القيمة التلقائية هي true. يؤثر هذا الخيار في عناصر النص العادي فقط.
    • ‫adjustElementDirection هو حقل منطقي اختياري يتحكّم في اتجاه العنصر القابل للتعديل استنادًا إلى اتجاه destinationLanguage. القيمة التلقائية هي true.

بالنسبة إلى أنظمة الكتابة من اليمين إلى اليسار، مثل اللغة العربية، تعدّل واجهة برمجة التطبيقات تلقائيًا اتجاه عنصر الإدخال وفقًا لاتجاه النص المكتوب ومحتوى عنصر الإدخال. يمكنك ضبط اتجاه النص في عنصر إدخال باستخدام HTML وJavaScript مع direction، والتي يمكن أن تتضمّن القيمة 'ltr' (من اليسار إلى اليمين) أو 'rtl' (من اليمين إلى اليسار). يؤثر استخدام هذه الطريقة في المؤشر ومحاذاة النص في منطقة الإدخال.

يمكنك الاطّلاع على مثال حول إتاحة واجهة برمجة التطبيقات للغات التي تُكتب من اليمين إلى اليسار في مثال الكتابة الصوتية باللغة العربية.

تنشئ هذه الطريقة استثناءات إذا كان أي من elementIds المحدّد غير صالح.

لا تعرض الدالة .makeTransliteratable() أي قيمة.

.removeEventListener(eventType, listener, opt_listenerScope)

تزيل .removeEventListener(eventType, listener, opt_listenerScope) أداة معالجة حدث من عنصر التحكّم في الكتابة الصوتية، حيث:

  • تستمدّ هذه الوسيطة قيمتها من التعداد eventType (مثل google.elements.transliteration.TransliterationControl. EventType.STATE_CHANGED).
  • ‫listener هي الدالة الخاصة بالحدث الذي يجب إزالته.
  • ‫opt_listenerScope هو النطاق الذي تم فيه تسجيل المستمع في وقت إضافته.

لا تعرض الدالة .removeEventListener() أي قيمة.

.setLanguagePair(sourceLanguage, destinationLanguage)

تتيح لك السمة .setLanguagePair(sourceLanguage, destinationLanguage) تغيير زوج اللغات المستخدَم في عنصر التحكّم في الكتابة الصوتية بشكلٍ ديناميكي، حيث:

  • توفّر sourceLanguage نوع اللغة المطلوب نقلها صوتيًا. تستمدّ هذه الوسيطة قيمتها من تعداد LanguageCode (مثل google.elements.transliteration.TransliterationControl. LanguageCode.ENGLISH).
  • توفّر السمة destinationLanguage نوع اللغة للنص المحوّل صوتيًا.

تعرض الدالة .setLanguagePair() قيمة منطقية تشير إلى ما إذا كان الإجراء setLanguage قد تم بنجاح.

.showControl(divElement)

تعرض .showControl(divElement) عنصر التحكّم في الترجمة الصوتية في DIV المحدّد، حيث divElement هو معرّف DIV. لا تتضمّن هذه الطريقة أي قيمة معروضة.

.toggleTransliteration()

يؤدي النقر على .toggleTransliteration() إلى تفعيل التحويل الصوتي أو إيقافه في أداة التحكّم في التحويل الصوتي. لا تتضمّن هذه الطريقة وسيطات ولا تُرجع أي قيمة.

طريقة ثابتة

يتم تنفيذ الطريقة الثابتة التالية في مساحة الاسم google.language.

طريقة ثابتة الوصف

.setOnLoadCallback(callback)

‫.setOnLoadCallback(callback) هي دالة ثابتة تسجّل دالة المعالجة المحدّدة ليتم استدعاؤها عند تحميل الصفحة التي تحتوي على هذا الاستدعاء، حيث callback هي دالة مطلوبة يتم استدعاؤها عند تحميل المستند الذي يحتوي على الدالة وتصبح واجهة برمجة التطبيقات جاهزة للاستخدام (مثلاً، بعد onLoad). يتم تنفيذ هذه الدالة في مساحة الاسم google (أي google.setOnLoadCallback(callback);)

لا تعرض الدالة .setOnLoadCallback() أي قيمة.

ملاحظة: كانت المستندات السابقة تنصح باستخدام السمة onload لعنصر body (<body onload="OnLoad()">). على الرغم من أنّ هذه الطريقة مناسبة عندما يكون لديك تحكّم كامل في الصفحة وجميع الرموز التي يتم تحميلها من خلالها، إلا أنّ هذا الأسلوب يمكن أن يتسبّب في حدوث مشاكل مع بعض أوقات التشغيل التي تتلف معالج body.onload. لا يواجه setOnLoadCallback() هذه المشاكل، وبالتالي فهو الطريقة المقترَحة لتسجيل دالة ردّ الاتصال التي تستدعي الرمز البرمجي عند تحميل واجهة برمجة التطبيقات بالكامل وتكون جاهزة للاستخدام.

يتم تنفيذ الطريقة الثابتة التالية في مساحة الاسم google.elements.transliteration.

طريقة ثابتة الوصف

.getDestinationLanguages(sourceLanguage)

‫.getDestinationLanguages(sourceLanguage) هي طريقة عامة تعرض خريطة للغات الوجهة التي تتوفّر لها خدمة الترجمة الصوتية للكلمات المحدّدة في sourceLanguage. تحتوي الخريطة التي يتم عرضها على اللغات المقصودة المتاحة، ويكون المفتاح هو اسم اللغة والقيمة هي رمز اللغة. تكون الخريطة التي يتم عرضها مشابهة للخريطة الموضّحة في التعداد LanguageCode.

عمليات التعداد

تعداد EventType

تسرد عملية التعداد google.elements.transliteration.TransliterationControl.EventType الأحداث المحتملة أثناء الترجمة الصوتية. يمكنك توفير معالِجات مخصّصة لهذه الأحداث في الرمز البرمجي.

var google.elements.transliteration.TransliterationControl.EventType = {
   STATE_CHANGED : 'state_changed',
   LANGUAGE_CHANGED : 'language_changed',
   SERVER_REACHABLE : 'server_reachable',
   SERVER_UNREACHABLE : 'server_unreachable'
};
  • google.elements.transliteration.TransliterationControl.EventType.STATE_CHANGED: النتائج عند تفعيل أو إيقاف ميزة الكتابة الصوتية في أداة التحكّم في الكتابة الصوتية من خلال:
    • مفتاح اختصار
    • الطرق enableTransliteration أو disableTransliteration أو toggleTransliteration
    • نقرة ماوس على عنصر التحكّم في الكتابة الصوتية الذي تم رسمه باستخدام الطريقة showControl
    يحتوي عنصر الحدث الذي تم تمريره إلى المستمع على الحقل transliterationEnabled. تكون قيمة هذا الحقل صحيحة إذا كانت الكتابة الصوتية هي 'on'، وإلا تكون خاطئة.
  • google.elements.transliteration.TransliterationControl.EventType.LANGUAGE_CHANGED: النتائج عند تغيير زوج لغة التحويل الصوتي في أداة التحكّم في التحويل الصوتي من خلال:
    • طريقة setLanguagePair
    • عنصر التحكّم في الكتابة الصوتية الذي تم إنشاؤه باستخدام طريقة showControl
    يحتوي عنصر الحدث الذي تم تمريره إلى معالج الأحداث على الحقلَين sourceLanguage وdestinationLanguage.
  • ‫google.elements.transliteration.TransliterationControl.EventType.SERVER_REACHABLE: النتائج التي تظهر عند التواصل بنجاح مع الخادم لنقل النص الصوتي إلى نص مكتوب
  • google.elements.transliteration.TransliterationControl.EventType.SERVER_UNREACHABLE نتيجة عند تعذّر الاتصال بالخادم لنقل النص إلى نظام كتابة آخر

تعداد LanguageCode

تربط google.elements.transliteration.LanguageCode ثوابت الأسماء برموز اللغات التي يمكنك استخدامها لتحديد اللغتَين المصدر والوجهة في طرق الترجمة الصوتية.

var google.elements.transliteration.LanguageCode = {
    ENGLISH: 'en',
    AMHARIC: 'am',
    ARABIC: 'ar',
    BENGALI: 'bn',
    CHINESE: 'zh',
    GREEK: 'el',
    GUJARATI: 'gu',
    HINDI: 'hi',
    KANNADA: 'kn',
    MALAYALAM: 'ml',
    MARATHI: 'mr',
    NEPALI: 'ne',
    ORIYA: 'or',
    PERSIAN: 'fa',
    PUNJABI: 'pa',
    RUSSIAN: 'ru',
    SANSKRIT: 'sa',
    SINHALESE: 'si',
    SERBIAN: 'sr',
    TAMIL: 'ta',
    TELUGU: 'te',
    TIGRINYA: 'ti',
    URDU: 'ur'
};

تعداد SupportedDestinationLanguages

تعيّن تعداد google.elements.transliteration.SupportedDestinationLanguages ثوابت الأسماء إلى مصفوفات من رموز اللغات التي يمكنك استخدامها لتحديد مجموعات من اللغات المستهدَفة في عنصر التحكّم في الكتابة الصوتية.

var google.elements.transliteration.SupportedDestinationLanguages = {
    // ALL includes all languages supported in the Transliterate API.
    // As support for more languages becomes available, this enum will be
    // automatically updated to include the new languages transparently.
    ALL: [
        google.elements.transliteration.LanguageCode.AMHARIC,
        google.elements.transliteration.LanguageCode.ARABIC,
        google.elements.transliteration.LanguageCode.BENGALI,
        google.elements.transliteration.LanguageCode.CHINESE,
        google.elements.transliteration.LanguageCode.GREEK,
        google.elements.transliteration.LanguageCode.GUJARATI,
        google.elements.transliteration.LanguageCode.HINDI,
        google.elements.transliteration.LanguageCode.KANNADA,
        google.elements.transliteration.LanguageCode.MALAYALAM,
        google.elements.transliteration.LanguageCode.MARATHI,
        google.elements.transliteration.LanguageCode.NEPALI,
        google.elements.transliteration.LanguageCode.ORIYA,
        google.elements.transliteration.LanguageCode.PERSIAN,
        google.elements.transliteration.LanguageCode.PUNJABI,
        google.elements.transliteration.LanguageCode.RUSSIAN,
        google.elements.transliteration.LanguageCode.SANSKRIT,
        google.elements.transliteration.LanguageCode.SERBIAN,
        google.elements.transliteration.LanguageCode.SINHALESE,
        google.elements.transliteration.LanguageCode.TAMIL,
        google.elements.transliteration.LanguageCode.TELUGU,
        google.elements.transliteration.LanguageCode.TIGRINYA,
        google.elements.transliteration.LanguageCode.URDU],
 
    // INDIC includes all Indic languages supported in the Transliterate API.
    // As support for more Indic languages becomes available, this enum will be
    // automatically updated to include the new languages transparently.
    INDIC: [
        google.elements.transliteration.LanguageCode.BENGALI,
        google.elements.transliteration.LanguageCode.GUJARATI,
        google.elements.transliteration.LanguageCode.HINDI,
        google.elements.transliteration.LanguageCode.KANNADA,
        google.elements.transliteration.LanguageCode.MALAYALAM,
        google.elements.transliteration.LanguageCode.MARATHI,
        google.elements.transliteration.LanguageCode.NEPALI,
        google.elements.transliteration.LanguageCode.ORIYA,
        google.elements.transliteration.LanguageCode.PUNJABI,
        google.elements.transliteration.LanguageCode.SANSKRIT,
        google.elements.transliteration.LanguageCode.SINHALESE,
        google.elements.transliteration.LanguageCode.TAMIL,
        google.elements.transliteration.LanguageCode.TELUGU,
        google.elements.transliteration.LanguageCode.URDU]
};

تحديد المشاكل وحلّها

في حال مواجهة مشاكل، اتّبِع الخطوات التالية:

  • ابحث عن الأخطاء الإملائية. تذكَّر أنّ JavaScript هي لغة حساسة لحالة الأحرف.
  • استخدِم برنامج تصحيح أخطاء JavaScript. يتضمّن Google Chrome مجموعة كاملة من أدوات المطوّرين. في Firefox، يمكنك استخدام وحدة تحكّم JavaScript أو Firebug. في IE، يمكنك استخدام Microsoft Script Debugger.
  • ابحث في مجموعة المناقشة. إذا لم تتمكّن من العثور على مشاركة تجيب عن سؤالك، يمكنك نشر سؤالك في المجموعة مع رابط يؤدي إلى صفحة ويب توضّح المشكلة.