音譯 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 實作進行。這種作法的影響其實不大，只是不會有具名的建構函式而已。就每個結果而言，系統會呼叫 new Object()，然後在該物件上設定正式屬性。這些屬性如下所示。 <result> error? 如果音譯時發生錯誤，則會顯示這項資訊。 code HTTP 樣式的錯誤代碼。 message 使用者容易理解的錯誤說明字串。 transliterations 大小與輸入 wordsArray 大小相同的陣列。 transliteratedWords 陣列大小上限為 5，包含 wordsArray 中對應字詞的音譯。

音譯控制項 JavaScript 參考資料

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

建構函式 - 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 是包含可編輯元素 ID 字串或元素參照的陣列，您要為這些元素啟用音譯功能。可編輯的元素可以是： 文字欄位 文字區域 具有 contentEditable="true" 的 <div> 具有 designMode="on" 的 <iframe> 具有 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 enum (例如 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 元素的 onload 屬性 (<body onload="OnLoad()">)。如果您完全掌控網頁和網頁載入的所有程式碼，這是不錯的方法，但這種做法可能會導致某些執行階段破壞 body.onload 處理常式。setOnLoadCallback() 沒有這些問題，因此建議您使用這個方法註冊回呼，在 API 完全載入並可供使用時呼叫程式碼。

下列靜態方法是在 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」，這個欄位會設為 true，否則為 false。
• 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。
• 搜尋 討論群組。如果找不到解答問題的貼文，請在群組中發問，並附上顯示問題的網頁連結。