Transliterate API Reference

תעתיק פשוט

השיטה הבאה מאפשרת לבצע תעתיק פשוט ללא ממשק משתמש באמצעות מניפולציה של JavaScript.

שיטה תיאור

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

‫google.language.transliterate(wordsArray, srcLang, destLang, callback) היא שיטה גלובלית שמבצעת תעתיק של טקסט נתון משפת המקור לשפת היעד. ה-API מחזיר את התוצאה באופן אסינכרוני לפונקציה callback שצוינה כאובייקט result. הפרמטרים של השיטה הזו הם:

  • ‫wordsArray מספק את הטקסט שצריך לתעתק כמערך.
  • ‫srcLang מספק את שפת המקור כקוד שפה. דוגמאות אפשר לראות ב-enum‏ LanguageCode.
  • ‫destLang מספק את שפת היעד כקוד שפה. דוגמאות אפשר לראות ב-enum‏ LanguageCode.
  • ‫callback היא פונקציית הקריאה החוזרת שמקבלת את result.

לפונקציה google.language.transliterate() אין ערך מוחזר.

השיטה המפושטת הזו לתעתיק משתמשת במרחב השמות google.language.transliterate (ולא ב-google.elements.transliteration, שהוא מרחב השמות של כל שיטה אחרת ב-Transliterate API).

‫google.language.transliterate() outputs the result object.

אובייקטים של תוצאות נוצרים באמצעות קידוד JSON של בקשות שרת. לכן, בחרנו שלא להטמיע אובייקטים רשמיים של JavaScript, ובמקום זאת ליצור באופן דינמי את האובייקטים result מהטופס הסדרתי שלהם.

למרות שאין הטמעה רשמית של האובייקטים, הם קיימים, ואנחנו מתעדים אותם כאילו הייתה הטמעה של JavaScript. ההשפעה של כל זה היא מינימלית. כלומר, אין בנאי עם שם. לכל תוצאה, המערכת קוראת לפונקציה new Object()‎ ואז מגדירה מאפיינים רשמיים באובייקט הזה. המאפיינים האלה מפורטים בהמשך.

  • <result>
    • error?
      הערך הזה מופיע אם הייתה שגיאה בתעתיק.
    • transliterations
      מערך בגודל ששווה לגודל הקלט wordsArray.
      • transliteratedWords
        מערך בגודל מקסימלי של 5, עם תעתיקים של המילה התואמת ב-wordsArray.

הפניה ל-JavaScript של כלי התעתיק

הקונסטרוקטור והשיטות הבאים מאפשרים לבצע תעתיק בממשק משתמש שסופק על ידי ה-API.

Constructor - google.elements.transliteration.TransliterationControl(options)

יצרן תיאור

google.elements.transliteration.
TransliterationControl(options)

‫.TransliterationControl(options) מאפשרת תעתיק על קבוצה של רכיבי HTML DOM שניתנים לעריכה, ומספקת מספר שיטות שמאפשרות לכם לשלוט בתעתיק ברכיבים האלה. הארגומנט options יכול לכלול את השדות הבאים:

  • ‫sourceLanguage הוא מחרוזת חובה שמציינת את שפת המקור באמצעות LanguageCode enum (כמו ב-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) מוסיף listener לרכיב השליטה בתעתיק עבור סוג האירוע שצוין. כשמופעל סוג האירוע הספציפי, ה-listener מופעל עם אובייקט האירוע. התוכן של אובייקט האירוע תלוי בסוג האירוע. הפרמטרים של השיטה הזו הם:

  • ‫eventType הוא האירוע שאליו רוצים להוסיף את ה-listener. הערך של הארגומנט הזה נלקח מה-enum‏ eventType (למשל google.elements.transliteration.TransliterationControl. EventType.STATE_CHANGED)).
  • ‫listener מספק פונקציית listener לאירוע.
  • ‫opt_listenerScope קורא ל-listener עם 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 הוא שדה בוליאני אופציונלי שקובע אם ה-API ישנה באופן אוטומטי את גודל הרכיב והגופן כדי להתאים בצורה אופטימלית לתווים של שפת היעד. ערך ברירת המחדל הוא true. האפשרות הזו משפיעה רק על רכיבי הטקסט הפשוט.
    • ‫adjustElementDirection הוא שדה בוליאני אופציונלי שקובע את הכיוון של הרכיב שניתן לעריכה בהתאם לכיוון של destinationLanguage. ערך ברירת המחדל הוא true.

במערכות כתיבה מימין לשמאל כמו ערבית, ה-API מתאים באופן אוטומטי את הכיוון של רכיב הקלט, בהתאם לכיוון של הסקריפט הכתוב ולתוכן של רכיב הקלט. אפשר להגדיר את כיוון הטקסט ברכיב קלט באמצעות HTML ו-JavaScript עם direction, שיכול לקבל את הערך 'ltr' (משמאל לימין) או 'rtl' (מימין לשמאל). השימוש בשיטה הזו משפיע על הסמן ועל יישור הטקסט באזור הקלט.

בדוגמה לתעתיק של ערבית אפשר לראות איך ה-API תומך בשפות שכותבים מימין לשמאל.

השיטה הזו יוצרת חריגים אם אחד מהערכים שצוינו ב-elementIds לא תקין.

לפונקציה .makeTransliteratable() אין ערך מוחזר.

.removeEventListener(eventType, listener, opt_listenerScope)

‫.removeEventListener(eventType, listener, opt_listenerScope) מסיר event listener מפקד התעתיק, כאשר:

  • הארגומנט הזה מקבל את הערך שלו מה-enum‏ eventType (למשל, google.elements.transliteration.TransliterationControl. EventType.STATE_CHANGED)).
  • ‫listener היא הפונקציה של האירוע שצריך להסיר.
  • ‫opt_listenerScope הוא ההיקף שבו המאזין נרשם בזמן הוספת המאזין.

לפונקציה .removeEventListener() אין ערך מוחזר.

.setLanguagePair(sourceLanguage, destinationLanguage)

‫.setLanguagePair(sourceLanguage, destinationLanguage) מאפשר לשנות באופן דינמי את צמד השפות שמשמש את אמצעי הבקרה של התעתיק, כאשר:

  • ‫sourceLanguage מספק את סוג השפה שרוצים לתעתק. הערך של הארגומנט הזה נלקח מה-enum‏ 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 היא פונקציה נדרשת שהמערכת קוראת לה כשהמסמך המכיל נטען וה-API מוכן לשימוש (למשל, אחרי onLoad). הפונקציה הזו מיושמת במרחב השמות google (כלומר, google.setOnLoadCallback(callback);)

לפונקציה .setOnLoadCallback() אין ערך מוחזר.

הערה: במסמכים קודמים המלצנו להשתמש במאפיין onload של רכיב body ‏ (<body onload="OnLoad()">). זו דרך טובה אם יש לכם שליטה מלאה בדף ובכל הקוד שנטען על ידי הדף, אבל הגישה הזו עלולה לגרום לבעיות בזמני ריצה מסוימים שמשמידים את ה-handler של body.onload. ‫setOnLoadCallback() לא סובלת מהבעיות האלה, ולכן היא השיטה המומלצת לרישום קריאה חוזרת שמפעילה את הקוד שלכם כשה-API נטען במלואו ומוכן לשימוש.

השיטה הסטטית הבאה מיושמת במרחב השמות google.elements.transliteration.

שיטה סטטית תיאור

.getDestinationLanguages(sourceLanguage)

‫.getDestinationLanguages(sourceLanguage) היא שיטה גלובלית שמחזירה מפה של שפות יעד שבהן יש תמיכה בתעתיק עבור sourceLanguage הנתון. המפה שמוחזרת מכילה שפות יעד נתמכות, שבהן המפתח הוא שם השפה והערך הוא קוד השפה. המפה שמוחזרת דומה לזו שמתוארת ב-enum‏ LanguageCode.

טיפוסים בני מנייה (enum)

טיפוסים בני מנייה (enum) של 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.
    אובייקט האירוע שמועבר אל listener מכיל את השדה transliterationEnabled. הערך של השדה הזה הוא True אם התעתיק הוא on, אחרת הוא False.
  • ‫google.elements.transliteration.TransliterationControl.EventType.LANGUAGE_CHANGED: תוצאות כשמשנים את זוג השפות של התעתוק בכלי התעתוק באמצעות:
    • השיטה setLanguagePair
    • הפקד לתעתיק שנוצר על ידי השיטה showControl
    אובייקט האירוע שמועבר אל listener מכיל את השדות sourceLanguage ו-destinationLanguage.
  • ‫google.elements.transliteration.TransliterationControl.EventType.SERVER_REACHABLE: התוצאות שמתקבלות כשיוצרים קשר עם השרת כדי לבצע תעתיק של טקסט.
  • תוצאות google.elements.transliteration.TransliterationControl.EventType.SERVER_UNREACHABLE אחרי ניסיון כושל ליצור קשר עם השרת כדי לתעתק טקסט.

טיפוס בן מנייה (enum) LanguageCode

הקובץ google.elements.transliteration.LanguageCode maps ממפה קבועים של שמות לקודי שפה שאפשר להשתמש בהם כדי לציין את שפת המקור ושפת היעד בשיטות התעתיק.

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'
};

טיפוסים בני מנייה (enum) של שפות יעד נתמכות

הספירה 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 היא שפה שבה יש הבחנה בין אותיות רישיות לאותיות קטנות (case-sensitive).
  • משתמשים בכלי לניפוי באגים ב-JavaScript. ל-Google Chrome יש קבוצה מלאה של כלים למפתחים. ב-Firefox, אפשר להשתמש במסוף JavaScript או ב-Firebug. ב-IE, אפשר להשתמש ב-Microsoft Script Debugger.
  • מחפשים ב קבוצת הדיון. אם לא מצאתם פוסט עם תשובה לשאלה שלכם, אתם יכולים לפרסם את השאלה בקבוצה ולצרף אליה קישור לדף אינטרנט שבו הבעיה מופיעה.