SiriKit官方文档 - Part2-2 参考-App词汇文件格式

最近在看SiriKit的官方文档,自啃 + Google翻译,如有错误或语义不当还望指出。

官方文档原文 - App Vocabulary File Format

具有自定义术语的App可以在其App包中包含一个AppIntentVocabulary.plist文件,以帮助Siri了解该术语是如何使用的。此属性列表文件包括你的App的用户将理解的特定术语、发音标准和如何使用它们的样例。此文件定义了适用于你的App的所有用户的全局术语。

你可以将词汇属性列表文件的本地化版本放在App的特定语言项目(.lproj)目录中。当你将App提交到App Store时,AppIntentVocabulary.plist文件和该文件的本地化版本将发送到Siri进行处理。这些文件的内容保留在服务器上,并且该内容在针对特定App版本。

重要

在开发过程中,Xcode会将你的词汇与Siri进行同步,Siri使用词汇来解释你的开发设备上的App版本的请求。但是,获取你的词汇数据并不是即时的,因此你可能需要等待一两分钟才能测试你的Siri功能。

表7-1列出了AppIntentVocabulary.plist文件中包含的键。让这些键作为Root字典的子项。

表7-1Root级别键

类型 概要
ParameterVocabularies 字典数组 (可选)与应用支持的意图的特定属性相对应的字词,参阅参数词汇表
IntentPhrases 字典数组 (可选,但建议填写)可以在Siri指南中显示的示例短语,以及Siri用于学习你的App术语的短语,参阅意图短语

参数词汇表

ParameterVocabularies key(Array - 可选)包含字典数组,每个字典定义一组术语和这些术语适用的意向属性。

每个字典包含两个必要的键,如表7-2所示。

表7-2参数词汇表键

类型 概要
ParameterNames 字典数组 (必要)指定词汇术语适用的属性,参阅参数名称
ParameterVocabulary 字典数组 (必要)词汇术语的发音和示例,参阅参数词汇

参数名称

ParameterNames key(Array - 必要)字符串数组,每个字符串包含词汇值适用的意图类和属性名。每个字符串的格式为.,其中是意图类的名称,是该类的可解析属性的名称。你可以在全局词汇文件中的以下属性配置自定义词汇表:

  • INRequestRideIntent.rideOptionName
  • INStartWorkoutIntent.workoutName
  • INPauseWorkoutIntent.workoutName
  • INResumeWorkoutIntent.workoutName
  • INEndWorkoutIntent.workoutName
  • INCancelWorkoutIntent.workoutName

参数词汇

ParameterVocabulary key(Array - 必要)字典数组,每个字典包含一个可用于给定参数的自定义术语。

每个字典包含两个必要的键,如表7-3所示。

表7-3单个词汇表条目的键

类型 概要
VocabularyItemIdentifier 字符串 (必要)Siri在识别自定义术语时为你的代码提供的字符串,参阅词汇项标识符
VocabularyItemSynonyms 字典数组 (必要)Siri识别的定义短语,包括发音和示例,参阅词汇项同义词

词汇项标识符

VocabularyItemIdentifier key(String - 必要)希望Siri分配给用于填充意图的INSpeakableString对象的identifier属性的字符串。字符串本身用户是看不到的也不用本地化。实际上,相同的标识符(identifier)字符串应该出现在你的词汇属性列表文件的每个本地化版本中。

此标识符字符串应用在所有被列在词汇项同义词的部分参数条目的同义词。

词汇项同义词

VocabularyItemSynonyms key(Array - 必要)字典数组,每个字典定义用户可能在你的App使用的自定义短语。每个同义词条目还可以包含发音指南和如何使用短语的示例。数组中的所有同义词都与相同的词汇项标识符键相关联。

每个字典可以包含表7-4中列出的键。

表7-4 同义词键

类型 概要
VocabularyItemPhrase 字符串 (必要)自定义短语的拼写方式与你的App使用它的方式相同,参阅词汇项-短语
VocabularyItemPronunciation 字符串 (可选)以“听起来像”的格式来格式化的短语的发音提示,参阅词汇项-发音
VocabularyItemExamples 字符串数组 (可选)如何使用短语的示例,参阅词汇项-示例

词汇项-短语

VocabularyItemPhrase key(String - 必要)Siri识别和显示的本地化短语。这里指定术语或短语应该出现在Siri界面中。

词汇项-发音

VocabularyItemPronunciation key(String - 可选)当使用母语中朗读时,声音相同的短语版本。这不是原始短语的语音拼写,而是一个在说话时具有等效声音的字符串。例如,短语“iTunes”可以具有“eye toons”作为其发音字符串。Siri在听用户和说短语时使用这些字符串作为提示。

词汇项-示例

VocabularyItemExamples key(Array - 可选)一个包含上下文中使用的短语示例的字符串数组。通过逐渐削减到包含短语的最短语句来囊括典型和简洁的示例。你可以使用顶级的意图短语键来指定更复杂的术语示例。

意图短语

IntentPhrases key(Array - 可选)包含一个字典数组,每个字典包含用户可能与你App的某个意图相关的示例短语。Siri使用你的例子作为提示帮助它更好地了解你的App的术语。每个示例短语或短语组都必须具有相关联的意图类,这有助于Siri更容易地识别用户的意图。

数组中的每个字典都有两个必要的键,如表7-5所示。

表7-5内容短语键

类型 概要
IntentName 字符串 (必要)示例适用的意图类的名称,参阅意图-名称
IntentExamples 字符串数组 (必填)用户可能说出与特点意图相关的短语,参阅意向-示例

意图-名称

IntentName key(String - 必要)指定每个短语适用的意图类的名称。例如,你可以为涉及乘车预定的示例短语指定字符串“INRequestRideIntent”。

意图-示例

IntentExamples key(Array - 必要)字符串数组,每个字符串包含一个用户可能说的示例短语。示例短语尽可能复杂,但需要反映用户在使用你的应用时可能说的实际短语。你的示例可能包括你使用参数词汇表键定义的任何自定义术语。预订使用名为CharityTruck的App时,示例短语可能包括以下内容:

  • “Ask CharityTruck for a ride to the Red Cross on 3rd and mission.”
  • “Check with CharityTruck if I can get a hauler truck tomorrow.”
  • “See if CharityTruck can send a pickup truck to my house at 7am tomorrow.”

重要

始终在任何示例短语中包含你的应用的名称。

本地化词汇发音规则

对于特定的本地化,当有具体值对应Vocabulary Item Pronunciation的Key时,会应用额外的规则:

  • zh_CN:中国汉语本地化
    • 使用数字1,2,3,4和5表示音调。对中性音使用数字5。在每个字符的拼音表示的结尾处放置音调。例如,“ping2 guo3”。
    • 你可以用“yu”替换拼音中的特殊字符“ü”。例如,“nu”将变成“nyu”。
  • zh_TW:台湾汉语本地化
    • 使用数字1,2,3,4和5表示音调。对中性音使用数字5。在每个字符的拼音表示的结尾处放置音调。例如,苏打绿变成“su1 da3 lyu4”。
  • zh_HK:香港粤语本地化
    • 使用粤语拼音(粤拼)罗马拼音系统化广东话。
    • 使用数字1,2,3,4,5和6表示音调。在Jyutping的结尾放置音调数字。例如,的士变为“dik1si2”,短讯变为“dyun2 seon2”。

样例

图7-1展示了一个示例词汇表文件,该文件为应用CardioBonanza中的锻炼方案定义了一个自定义术语。当用户说出与该App相关的术语“Cardio Craze”时,Siri知道将字符串cardio_craze_workout放在INStartWorkoutIntent对象的workoutName属性中。当处理意图时,CardioBonanzaApp使用该字符串来启动特定的锻炼。

图7-1 一个健身App的全局词汇表文件
图7-1一个健身App的全局词汇表文件

SiriKit译文系列

SiriKit官方文档 - Part1-1 SiriKit介绍
SiriKit官方文档 - Part1-2 创建一个Intents扩展
SiriKit官方文档 - Part1-3 解决和处理意图
SiriKit官方文档 - Part1-4 指定自定义词汇
SiriKit官方文档 - Part1-5 创建Intents UI扩展
SiriKit官方文档 - Part2-1 参考-意图域
SiriKit官方文档 - Part2-2 参考-App词汇文件格式