Overview

The Language control is an add-on control. If it is not included in your system, contact your dealer or Pronexus Sales for pricing.

The Language control performs several functions:

1. Setting of the language for each call by selecting the set of pre-recorded prompts and/or selecting a TTS speaker

2. Overriding default phrase concatenation rules for the built-in system phrases with your own rules

3. Defining your own system phrase type

Each language control specifies the rules for system phrase generation for one language. Up to 24 language controls are allowed on a system. The default language as specified in the VBVFrame language property page is used when the caller first makes a connection until the caller makes a language selection. The default language always uses the standard directories to find files. Other languages use a subdirectory of either the project directory or the default VBVoice directory.

Example

(Note: Use of the system phrases after a language has been selected will require a copy of the system .vap files in each language directory. They have been omitted in the default installation to save space. English is the default language.)

The language for a caller can be changed by routing the call through one of the language controls. This usually occurs when the caller makes a numerical selection matching the desired language. This selection is picked up by the GetDigits control and the appropriate language is then selected and used for further communication.

Each language can have a separate set of rules for saying numbers, dates, and times. In addition, the built-in concatenation rules can be overridden using code. After a call passes through a language control, the default language settings provided by the VBVFrame control are overridden for the duration of the call.

Numbers

VBVoice has built-in support for many languages. For languages not supported, new rules can be added using by overriding the system rules with code in the SayNumber event (and turning on the System event SayNumber).

Some numbers also are gender-specific. The PhraseData field can be used to set the gender of each phrase. The PhraseData field may contain the letters M (masculine), F (feminine), or N (neuter) to indicate grammatical gender.

To support new system phrases formats, your code must analyze the data passed in from the application, usually the string provided in the phrase definition. If the concatenation rules for the new language are the same as the chosen default, then nothing needs to be done. If different, your code must create phrases to vocalize the data. The data string is in the format specified for the appropriate system phrase type described in System Phrase Types.

Date Order

The language control specifies the order in which the date components are said. Possible values are:

1. mmddyy (month, day, year)

2. ddmmyy (day, month, year)

3. yyddmm

4. yymmdd

The date format defined by each phrase specifies the components of each date (i.e. day, month, weekday, month-name, year). This is defined for each phrase. The format of the string to vocalize is defined by the system phrase type.

Times can be vocalized using 12 hour or 24 hour time.

Managing Phrase Files

The phrase files for additional languages must contain equivalent phrases in the same order and position as for the default language. VBVoice relies on the phrase files for all languages having the phrases in the same position in the file, with the same name, or unpredictable results will occur.

ScriptSize property

To simplify maintaining multiple VAP files in different languages, use the ScriptSize property. This property of the VBVFrame control allows you to set the maximum number of characters which VBVoice uses for phrase matching. This allows you to use a numeric or other prefix for each phrase name which VBVoice uses to find the phrase. The remaining characters in the name can be the actual script in the correct language.

EXAMPLE

If the ScriptSize is set to 3, a phrase name in the English VAP file may be 100: hello and in the French VAP file, 100: bonjour.

Language directories

The subdirectory containing the phrase files for that language must be specified in the property page. This directory is a subdirectory of the project directory set in the VBVFrame control and should contain a copy of all the system VAP files in the appropriate language and any other voice files used by the system.

Hard-coded file paths

The language directory paths will be overridden if a complete file path is hard-coded using a WaveFile, or VAP Phrase file type.

Changing voice file paths

The language directory paths will be overridden if the CurrentDirectory property in the VBVFrame control is used to set the directory for a channel.

%CurrentDirectory%

When VBVoice vocalizes phrases that require a file path such as SayFileDate, it does not use the language subdirectory by default. It only uses the language directory when looking for VAP phrase files or files referenced by the VAPPhrase or VapPhraseIndex phrase types which do not have a full path. If it is necessary to reference the language directory, it is available as the CurrentDirectory property of the VBVFrame control. This property can be used to prefix a filename with a language path in order to access a language-dependent file - e.g. %VBVFrame1.CurrentDirectory%msg1.vox.

Example Directory Layouts

EXAMPLE 1

All files, both system files and project files, are contained in the same directory structure. The default language is English, with a secondary language Spanish.

Voice directory (set by Voice INI setting): C:\VBVOICE.

Project directory (set by Frame control): C:\VBVOICE (the default for this property is the same as Voice directory).

The language control will use the directory SPANISH\.

Both C:\VBVOICE and C:\VBVOICE\SPANISH will contain:

1. VBVOICE30.VAP

2. PLAYMSGS.VAP

3. RECORD.VAP

4. MYPROJ.VAP

EXAMPLE 2

This example uses a separate project file for project-specific files, allowing a separate directory structure for each project while avoiding duplication of the system files

The default language is English, with a secondary language being Spanish.

Voice directory (set by INI setting): C:\VBVREL#

Project directory (set by Frame control): C:\MYPROJ

System files: C:\VBVOICE; C:\VBVOICE\SPANISH

Project files: C:\MYPROJ; C:\MYPROJ\SPANISH

The language control will use the directory SPANISH\.

Both C:\VBVOICE and C:\VBVBVOICEV4\SPANISH will contain:

1. VBVOICE30.VAP

2. PLAYMSGS.VAP

3. RECORD.VAP

Both C:\MYPROJ and C:\MYPROJ\SPANISH will contain

1. MYPROJ.VAP

Language Control Examples

Use of the Language control is shown in the example Language.

Initial Setup Properties

When creating your own system phrases, you can use most of the standard system phrases and phrases from VAP and WAV files. System phrases created while in an event does not create another event - the default implementation is always used.

Language Properties

1. TimeFormat

2. DateOrder

3. LanguageID

4. LangProgID

These properties define the characteristics of a language.

Phrase Properties

1. AddType

2. PhraseData1

3. PhraseData2

4. PhraseIndex

5. PhraseName

These properties are used to modify how a phrase is vocalized.

DateOrder

(vbvDateOrderConstants)

DateOrder is a project wide setting that defines the order in which the component parts of dates are vocalized. Note that the components of the date to be vocalized (day, month, year, weekday), and the format (e.g. numeric month, month name) are defined by each individual phrase.

Possible values:

1. ddmmyy

2. yymmdd

3. yyddmm

4. mmddyy

Directory

(String)

Contains the directory or subdirectory where the voice files for this language are located.

EventMask

(Integer)

This property contains a bit pattern defining which phrases will generate an event at runtime. See Language Control Events property page.

LanguageID

(vbvLanguageConstants)

LanguageID is a project wide setting that specifies the concatenation rules for vocalizing numbers. VBVoice has built-in rules for several common languages. Support for dynamic language setting, multiple simultaneous languages, and other languages can be added using the Language control.

See vbvLanguageConstants for all possible values.

LangProgID

(Integer)

If LanguageID is set to VBVCustomLang, then the LangProgID is set to the name of a custom language implementation.

TimeFormat

(vbvTimeFormatConstants)

TimeFormat is a project wide setting that specifies whether times are vocalized in 12 hour or 24 hour time, (for example, eleven twenty two P.M. or twenty three twenty two.

Possible values:

1. vbvTime12

2. vbvTime24

Runtime Properties

AddType

(vbvPhraseTypeConstants)

Set this property to one of the vbvPhraseTypeConstants to add a new phrase to play. First set the PhraseData1, PhraseData2, and/or PhraseIndex or PhraseName properties. A trappable error may be generated if the required properties for the selected phrase type are invalid.

CurrentTTSSpeaker

(Integer, String)String

Use this property to select or retrieve which Speaker mode is for the TTS engine (SayText prompts) for this language. See TTS Speaker.

GotoNode

See GotoNode.

Filename

(String)

This property is used to specify the VAP or WAV file containing the required phrase. Required for VAPPhraseIndex .WAV file phrase types.

PhraseData1, PhraseData2

These properties are used to specify the data to be used when vocalizing a System phrase requiring data to say. See the examples below and System Phrase Types for details of the data required by each phrase.

The vbvVAPPhrase, vbvVAPPhraseIndex, and vbvWavFile do not fire events in the Language control. The vbvNumFiles phrase fires the Number event after calculating the number to vocalize.

PhraseIndex

(Integer)

Used to specify a VAP phrase using the position of the phrase in the file. The first phrase is at position 0. Setting the PhraseIndex property directly is more efficient than using the PhraseName property.

PhraseName

(String)

Used to specify a VAP phrase using the script. When this property is set, the PhraseIndex property contains the index of this phrase in the VAP file. Setting the PhraseIndex property directly is more efficient than using PhraseName.

Methods

TakeCall

See TakeCall.

Events

Each type of system phrase has an event associated with it. When VBVoice attempts to play a system phrase, it fires the associated event. The only exception is the NumFiles system phrase, which generates a SayNumber event. In this event, you can add phrases using the properties described above.

See the Language example for demonstrations of these properties.

Language Example

This example is found in the subdirectory Examples\Language.

The caller can select one of three languages: English, French, or Italian. Next the system says a short language-dependent greeting to the caller which consists of a phrase in a VAP file (This is a phrase in &) and a number. In the French language control, some code is implemented that overrides the default system phrase implementation for the number 234 only. If the system vocalizes the number 234 using the SayNumber system phrase, the code overrides the default behavior and instead vocalizes 2,3,4 as digits.

Note that the code for saying 234 must set the UseDefault parameter to False. If this is not done, the system says the phrases as set by the properties in addition to the default system implementation of SayNumber.

Sample Code for the SayNumber Phrase Type:

Private Sub French_Number(ByVal PhrsValue As String, ByVal Flags As String, UseDefault As Integer)

'this code says '2,3,4' using a different method for each digit

On Error Goto Num_Error

If PhrsValue = 234 Then

'say 2 using SayNumber

French.PhraseData1 = "2"

French.PhraseData2 = "M" 'number flags, optional

French.AddType = vbvSayNumber

'say 3 using a named phrase

French.filename = "vbvoice30.vap"

French.PhraseName = "three"

French.AddType = vbvVAPPhrase

'say 4 using an phrase by index

French.filename = "vbvoice30.vap"

French.PhraseIndex = 4

French.AddType = vbvVAPPhraseIndex

UseDefault = False

End If

Exit Sub

Num_Error:

debug.print "error in create phrase"

Resume Next

End Sub

Error Codes

1. vbvErrCallNotHere: 32005: attempts to set AddType property outside of event

2. vbvErrPhraseNotAllowed: 32010: illegal phrase type

3. vbvErrAddPhrs: 32011: error while attempting to add a phrase

4. vbvErrPhraseNotFound: 32012: could not find phrase in current file

Language Setup Property Page

Language Voice File Directory

See Directory.

Default Number Format

This list allows you to specify the default number system used by this language. At present, English, Italian, French, and German are built into VBVoice. The custom language option provides for additional languages in the future by addition of a DLL specific for that language. Other languages can be implemented by overriding the rules for one of these languages by checking the System Phrase Event for SayNumber, together with code in the SayNumber event.

Time Format

This selection allows the time to be said either in 12 hour (e.g. eleven fifty nine PM) or 24 hour format (e.g. twenty three fifty nine).

Setting new number formats

The Number format fields allow you to select the default number format for each language. For example, your language may be similar to French, with a few differences. In this scenario, select French as the default format and use the Number phrase event to provide the new rules for the set of numbers that differ from French. (See sample code below).

System Phrase events can also be used to set grammatical gender for languages that have gender-specific words for numbers.

Setting new date and time

The date and time fields allow you to specify the format of phrases for dates and times used in each language. For example, some languages realize dates as month-day-year whereas others may use year-month-day.

Date Order

See DateOrder.

Custom Language ProgID

Pronexus distributors use this field to create custom language DLLs for VBVoice.

TTS Speaker

This field is used to select the Speaker for the TTS engine (SayText prompts) for a language. Each speaker supplied by an engine is typically designed for one language. The specified TTS speaker will vocalize the SayText phrases in any subsequent controls until a new TTS speaker is selected in another Language control. On the first SayText call after a new speaker is selected, there may be a short delay while the new speaker is created, if there is not one already available from a previous session.

Dictionary

VBVoice 5.2 supports RealSpeak Telecom User Dictionary. VBVoice will load the TTS engine with a custom dictionary specified in VBVFrame, and keep it enabled until the TTS session is finished and the engine is released.

Use the Dictionary field in the Language control to change this custom dictionary at runtime.

For more information and to learn how to build a custom dictionary, refer to Using a User Dictionary in the RealSpeak Telecom V3 programmer's guide.

Language Control Events Property Page

Used to select which phrases have events fired so that VB code can modify the default system behavior for those phrase types.

System Phrase Events

These check boxes allow you to override most of the VBVoice system phrases with your own implementation of concatenation rules. Your code only need implement the phrase types where the rules differ from those provided by VBVoice.