Transliterate API 參考資料

簡單音譯

以下方法可讓您操作 JavaScript，不必使用 UI 即可進行簡單的音譯作業。

方法 說明

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

google.language.transliterate(wordsArray, srcLang, destLang, callback) 是一種通用方法，可將特定文字從原文語言翻譯成譯文語言。API 會以非同步方式將結果傳回指定的 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 實作進行。這種作法的影響其實不大，只是不會有具名的建構函式而已。每一個結果都如同系統呼叫新 Object()，然後針對該物件設定正式屬性。這些屬性如下。

  • <result>
    • error?
      音譯錯誤 (如果有) 的話即顯示。
    • transliterations
      大小陣列等於輸入值 wordsArray 的大小。
      • transliteratedWords
        大小上限為 5 的陣列，其中含有對應字詞在 wordsArray 中的翻譯。

音譯控制 JavaScript 參考資料

下列建構函式和方法可讓您在 API 提供的 UI 中執行音譯。

建構函式 - google.elements.transliteration.TransliterationControl(options)

建構函式 說明

google.elements.transliteration.
TransliterationControl(options)

.TransliterationControl(options) 能對一組可編輯的 HTML DOM 元素啟用音譯功能，並提供多種方法讓您控制這些元素的音譯功能。options 引數可能包含下列欄位：

  • sourceLanguage 是 mandatory 字串，可透過 LanguageCode 列舉指定原文語言 (例如在 google.elements.transliteration.ENGLISH 中)。目前，系統僅支援英文語言。
  • destinationLanguage 是 mandatory 陣列，可透過 LanguageCode 列舉指定目的地語言 (例如在 google.elements.transliteration.HINDI 中)。

    在使用者介面中，可用的目的地語言會顯示在選單中，且系統預設會選取陣列中的第一個語言。如要進一步瞭解特定原文語言的有效目的地語言，請參閱 getDestinationLanguages。
  • transliterationEnabled 是選用欄位，用於指定是否要啟用音譯功能。如要預設啟用音譯功能，請在這個欄位中指定 true 的值。預設值為 false。
  • shortcutKey 是選擇性的字串欄位，用來指定切換音譯功能的開關鍵。如要指定快速鍵，請指定包含修飾符的字串，例如 &&33;Ctrl','Alt'&'Shift' 和字母。例如：'Ctrl+g' &&33;Ctrl+Shift+a' 都是有效的快速鍵組合。

    注意：Shift 鍵不能做為唯一的修飾符，但您可以將其與 Alt 或 Control 搭配使用。

以下情況會在下列情況中建立例外：

  • sourceLanguage 或 destinationLanguage 無效
  • sourceLangauge 和 destinationLanguage 語言組合中使用了不支援的語言
  • shortcutsKey 組合無效

以下的程式碼片段示範如何建立音譯控制項的執行個體：

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 是一個陣列，其包含可編輯的元素 ID 字串，或是您要啟用音譯功能的元素參照。可編輯的元素可以是：

    • 文字欄位
    • 文字區域
    • 包含 contentEditable="true"
    • <iframe> 搭配 designMode="on"
    • 內含 contentEditable="true" 內文的 iFrame。請先啟用 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) 會從音譯控制項中移除事件監聽器，其中：

  • 這個引數會從 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 的 ID。此方法沒有傳回值。

.toggleTransliteration()

.toggleTransliteration()在音譯控制項中開啟或關閉音譯功能。此方法不含引數，而且沒有傳回值。

靜態方法

下列靜態方法是在 google.language 命名空間中實作。

靜態方法 說明

.setOnLoadCallback(callback)

.setOnLoadCallback(callback) 是一個靜態函式，會註冊系統載入此呼叫頁面後呼叫的指定處理常式函式，其中 callback 是載入文件且 API 可供使用時 (例如 onLoad) 的必要函式。這個函式可在 google 命名空間 (即google.setOnLoadCallback(callback);)

.setOnLoadCallback() 沒有傳回值。

注意：先前的文件建議使用 body 元素 #<body onload="OnLoad()"> 的 onload 屬性 (<body onload="OnLoad()">)。雖然當您完全掌控網頁及網頁載入的所有程式碼時，這是相當不錯的方法。不過，此方法可能會導致某些執行階段毀損，導致 body.onload 處理常式發生問題。setOnLoadCallback() 沒有這些問題，因此建議您註冊回呼方法，在 API 已載入且可供使用時呼叫您的程式碼。

下列靜態方法是在 google.elements.transliteration 命名空間中實作。

靜態方法 說明

.getDestinationLanguages(sourceLanguage)

.getDestinationLanguages(sourceLanguage) 是一種全域方法，可對指定 sourceLanguage 的譯文語言傳回對應的語言地圖。傳回的地圖包含支援的目的地語言，其中鍵是語言名稱，而值則是語言代碼。傳回的地圖與 LanguageCode 列舉中描述的地圖類似。

列舉

事件類型列舉

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'」，這個欄位則為 true。
  • 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 嘗試與伺服器聯絡，導致無法翻譯文字。

語言代碼列舉

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

支援目的地語言列舉

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 指令碼偵錯工具。
  • 搜尋討論群組。如果您找不到解答到問題中的文章，請將問題張貼至群組，並附上問題網頁連結。