Writing a grammar file header

As mentioned in Grammar file structure, the grammar file header specifies crucial information about the grammar document, including:

For full details on the GrXML elements in the header and their attributes, refer to the SRGS specification.

Controlling languages in a grammar

Recognizer uses language to convert the text of a word in the grammar into a recognizable pronunciation. Since words spelled the same way can still be pronounced differently in different languages, it’s important to specify the language to use when Recognizer interprets items.

You can specify the language in the following ways:

Method

Description

In the grammar document header

In the grammar header you must specify a default language for the grammar and its imported grammars. The language can still be overridden locally by using the xml:lang attribute, or importing a subgrammar of another language.

When using a built-in grammar or a user dictionary.

When you invoke a built-in grammar, you can specify a language other than the current default.

Using an xml:lang attribute in a tag within the grammar main body

You can override the default language for individual vocabulary items within a grammar.

Recognizer allows you to activate grammars of different languages at the same time. This simultaneous activation invokes parallel grammars.

An application that recognizes more than one language at a time is known as a multi-language application. You can build a multi-language application with different grammars for each language, or you can embed different languages in a single grammar. Recognizer uses more memory for each added language.

Every voice grammar must specify a language in the xml:lang attribute of the <grammar> element, as shown in the example below: 

<grammar xml:lang="fr-FR" version="1.0" root="ROOT"
xmlns="http://www.w3.org/2001/06/grammar">

The language must be compatible with the encoding type specified in the XML declaration. By default, Recognizer supports en-US; other languages must be installed separately.

Applications can recognize speech in any language that has been installed on Recognizer. The following table lists the language codes as used by Recognizer. The list of supported languages is continuously growing; for the most current information, refer to Nuance Network at Nuance Network.

LangCode

Meaning

ca-ES

Catalan, Spain

cn-HK

Cantonese, Hong Kong

cs-CZ

Czech, Czech Republic

da-DK

Danish, Denmark

de-AT

German, Austria

de-CH

German, Switzerland

de-DE

German, Germany

el-GR

Greek, Greece

en-AU

English, Australia

en-GB

English, Great Britain

en-IN

English, India

en-SG

English, Singapore

en-US

English, United States

en-ZA

English, South Africa

es-AR

Spanish, Argentina

es-CO

Spanish, Colombia

es-ES

Spanish, Spain

es-US

Spanish, United States (includes Mexico)

eu-ES

Basque, Spain

fi-FI

Finnish, Finland

fr-BE

French, Belgium

fr-CA

French, Canada

fr-FR

French, France

he-IL

Hebrew, Israel

hi-IN

Hindu, India

hu-HU

Hungarian, Hungry

it-IT

Italian, Italy

ja-JP

Japanese, Japan

ko-KR

Korean, Korea

nl-BE

Flemish, Belgium

nl-NL

Dutch, Netherlands

no-NO

Norwegian, Norway

pl-PL

Polish, Poland

pt-BR

Portuguese, Brazil

pt-PT

Portuguese, Portugal

ru-RU

Russian, Russia

sk-SK

Slovak, Slovakia

sl-SI

Slovenian, Slovenia

sv-SE

Swedish, Sweden

tr-TR

Turkish, Turkey

zh-CN

Mandarin, Mainland China

zh-TW

Mandarin, Taiwan

If the grammar specifies strings other than these codes, Recognizer attempts to map the strings to an installed language. This attempted mapping is controlled by swirec_language_translation_table.

You can also specify a language when using a built-in grammar. For example: 

builtin:grammar/digits?language=fr-FR; ...

If a VoiceXML document invokes a built-in grammar without declaring a language, Recognizer searches through the configuration precedence stack to determine a default (there is more than one way to define the default language).

Note: Application grammars can import built-in grammars. For details, see Importing built-in grammars.

Finally, you can change the language for individual vocabulary items within a grammar by using the xml:lang attribute within the element. This is particularly useful when callers speak in one language, but must occasionally use names of foreign places, people, businesses, and so on in a different language.

You can use the xml:lang attribute within the <item>, <one-of>, <ruleref>, or <token> elements in GrXML.

Here is an example of setting the language for a list (assumes US English is the default): 

<rule id="request">
 may I speak to
 <one-of xml:lang="fr-CA">
  <item> Michel Tremblay </item>
  <item> André Roy </item>
 </one-of>
</rule>

An example of setting the language for individual items (US English default): 

<one-of>
 <item>Spain</item>
 <item xml:lang="es-US"> España </item>
 <item xml:lang="fr-FR"> Espagne </item>
</one-of>

Finally, an example of setting the language within a single item: 

<one-of> 
 <item>I want to 
  <item xml:lang="en-US"> call </item> 
  <item xml:lang="es-ES"> España </item> 
 </item> 
</one-of>

DTMF grammars

The mode attribute of the <grammar> element lets you specify whether the grammar will be a voice grammar that supports both speech or a DTMF grammar (Dual-Tone Multi-Frequency) that supports input from the number pad. All scripting that applies to speech grammars applies to DTMF grammars as well.

The terminals of DTMF grammars must be drawn from the set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, #. A, B, C, D}. Any DTMF grammar that tries to use other terminals will cause an error when it is loaded.

Here is a sample DTMF grammar that accepts an unlimited number of digits: 

<?xml version='1.0' encoding='UTF-8'?> 
<grammar xml:lang="en-US" mode="dtmf" version="1.0" 
  tag-format="swi-semantics/1.0"
  root="_digits"
  xmlns="http://www.w3.org/2001/06/grammar">
 <rule id="_digits" scope="public">
  <ruleref uri="#DIGIT_STRING" />
  <tag>
    MEANING=DIGIT_STRING.SWI_literal.replace(/ /g, '')
  </tag>
 </rule>
 <rule id="DIGIT_STRING">
  <item repeat="1-">
   <ruleref uri="#DIGIT"/>
  </item>
 </rule>
 <rule id="DIGIT">
  <one-of>
   <item>0</item>
   <item>1</item>
   <item>2</item>
   <item>3</item>
   <item>4</item>
   <item>5</item>
   <item>6</item>
   <item>7</item>
   <item>8</item>
   <item>9</item>
  </one-of>
 </rule>
</grammar>

Other header elements (<lexicon>, <meta>, and <metadata>)

Grammar file structure describes the main XML declaration and the <grammar> element, both of which are required in any grammar document.

There are three other GrXML elements that can be used in the header. All three elements must be children of the <grammar> element if you use them.

The <lexicon> element specifies the locations of dictionaries to be loaded at the same time as the main grammar.

A dictionary is a collection of words that maps the word text to a pronunciation. Recognizer already has a system dictionary for each language it supports. When you compile a grammar or test it with parseTool, some words may not be recognized, and will generate an error message. For example, terms that are commonly used in your business but are obscure outside that context may be rejected or misinterpreted by Recognizer; or a name may be spelled very differently from how it is pronounced (for example, Worcester in Massachusetts is pronounced “wih-ster” or “woo-stah” instead of “war-sess-ter”).

To account for such words and phrases, you can create your own user dictionary. See Pronunciation dictionaries.

You can use the <meta> element to specify Recognizer-specific parameters. Your settings override the default configuration. For example, you can specify the maximum period of silence that Recognizer uses to determine whether a user has finished speaking: 

<meta name="completetimeout" content="1500"/>

When using <meta> to set parameter values as shown above, be aware of the precedence of these settings. Parameters can be set in various ways including configuration files, other grammars, and in special grammars (see Parameter grammars). The value you assign via a grammar <meta> could be overridden by a different value set elsewhere.

Recognizer is also able to support bigrams though use of the <meta> element. See Applying bigram language models.

Note: All <meta> elements must occur before any rules.

The <metadata> element stores information about the document. Such entries are not interpreted by Recognizer, but can contain notes you may want to include in the document for later reference, such as the author name.