Transliterate API 参考

简单的音译

以下方法可让您在没有用户界面的情况下操作 JavaScript 执行简单的音译。

方法 说明

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

google.language.transliterate(wordsArray, srcLang, destLang, callback) 是一种全局方法，用于将给定的文本从源语言转写为目标语言。该 API 会以异步方式将结果作为 result 对象返回给指定的 callback 函数。此方法的参数包括：

  • 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 参考

以下构造函数和方法可让您在该 API 提供的用户界面中执行音译。

构造函数 - 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 枚举（例如 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 脚本调试器。
  • 搜索 讨论组。如果您找不到能解答您问题的帖子，请将您的问题发布到群组中，并附上能展示问题的网页链接。