Dialog Designer Localization Package

Developers Guide

May 14, 2010

Issue Number: 1.0
 License Type(s)
© 2009 Avaya Inc.
Copyright
All Rights Reserved.
Except where expressly stated otherwise, the Product is
protected by copyright and other laws respecting proprietary
Notice
rights. Unauthorized reproduction, transfer, and or use can be a
criminal, as well as a civil, offense under the applicable law.
While reasonable efforts were made to ensure that the
information in this document was complete and accurate at the
Third-party Components
time of printing, Avaya Inc. can assume no liability for any
errors. Changes and corrections to the information in this
document may be incorporated in future releases. Certain software programs or portions thereof included in the
Product may contain software distributed under third party
agreements (“Third Party Components”), which may contain
Documentation disclaimer
terms that expand or limit rights to use certain portions of the
Product (“Third Party Terms”). Information identifying Third
Avaya Inc. is not responsible for any modifications, additions, or Party Components and the Third Party Terms that apply to them
deletions to the original published version of this documentation is available on Avaya's web site at:
unless such modifications, additions, or deletions were http://support.avaya.com/ThirdPartyLicense/
performed by Avaya. Customer and/or End User agree to
indemnify and hold harmless Avaya, Avaya's agents, servants
Avaya Fraud Intervention
and employees against all claims, lawsuits, demands and
judgments arising out of, or in connection with, subsequent
modifications, additions or deletions to this documentation to If you suspect that you are being victimized by toll fraud and you
the extent made by the Customer or End User. need technical assistance or support, call Technical Service
Center Toll Fraud Intervention Hotline at +1-800-643-2353 for the
United States and Canada. For additional support telephone
Link Disclaimer
numbers, see the Avaya Web site:
http://www.avaya.com/support
Avaya Inc. is not responsible for the contents or reliability of any
linked Web sites referenced elsewhere within this
Trademarks
documentation, and Avaya does not necessarily endorse the
products, services, or information described or offered within
them. We cannot guarantee that these links will work all of the Avaya is a trademark of Avaya Inc. All non-Avaya trademarks are
time and we have no control over the availability of the linked the property of their respective owners. Avaya Support Avaya
pages. provides a telephone number for you to use to report problems
or to ask questions about your product. The support telephone
number is 1-800-242-2121 in the United States. For additional
Warranty
support telephone numbers, see the Avaya Web site:
http://www.avaya.com/support
Avaya Inc. provides a limited warranty on this product. Refer to
your sales agreement to establish the terms of the limited
warranty. In addition, Avaya’s standard warranty language, as
well as information regarding support for this product, while
under warranty, is available through the following Web site:
http://www.avaya.com/support

License

USE OR INSTALLATION OF THE PRODUCT INDICATES THE

END USER'S ACCEPTANCE OF THE TERMS SET FORTH
HEREIN AND THE GENERAL LICENSE TERMS AVAILABLE ON
THE AVAYA WEB SITE AT http://support.avaya.com/LicenseInfo/
(“GENERAL LICENSE TERMS”). IF YOU DO NOT WISH TO BE
BOUND BY THESE TERMS, YOU MUST RETURN THE
PRODUCT(S) TO THE POINT OF PURCHASE WITHIN TEN (10)
DAYS OF DELIVERY FOR A REFUND OR CREDIT. Avaya grants
End User a license within the scope of the license types
described below. The applicable number of licenses and units of
capacity for which the license is granted will be one (1), unless a
different number of licenses or units of capacity is specified in
the Documentation or other materials available to End User.
“Designated Processor” means a single stand-alone computing
device. “Server” means a Designated Processor that hosts a
software application to be accessed by multiple users.
“Software” means the computer programs in object code,
originally licensed by Avaya and ultimately utilized by End User,
whether as stand-alone Products or pre-installed on Hardware.
“Hardware” means the standard hardware Products, originally
sold by Avaya and ultimately utilized by End User.
Table of Contents

1. INTRODUCTION............................................................................................................................................. 1
REQUIREMENTS ........................................................................................................................................................ 1
2. ECLIPSE PROJECT SETUP .......................................................................................................................... 2
LINGUISTIC CONSIDERATIONS ................................................................................................................................... 2
CREATING A NEW PROJECT ....................................................................................................................................... 2
3. PROJECT STRUCTURE................................................................................................................................. 5
AUDIO FILES ............................................................................................................................................................. 6
PROMPT METAFILE .................................................................................................................................................... 8
LOCALIZATION LOGIC ............................................................................................................................................ 10
4. DEVELOPING THE LANGUAGE PACKAGE.......................................................................................... 12
FORMATLOCALE AND PROMPT METADATA ............................................................................................................ 12
LOCALIZATION FORMATS ....................................................................................................................................... 13
WRITING THE FORMATLOCALE CLASS .................................................................................................................... 17
5. PACKAGING THE LOCALIZATION BUNDLE FOR DIALOG DESIGNER ...................................... 18
6. LINGUISTIC DEVELOPMENT AND OTHER PRACTICES.................................................................. 20
GRAMMAR DEVELOPMENT AND PHRASES’ IDENTIFICATION .................................................................................... 20
VOCALIST AND STUDIO SELECTION ......................................................................................................................... 21
TESTING OF THE LOCALIZATION BUNDLE ................................................................................................................ 21
APPENDIX A: TEMPLATE FOR RECORDING GUIDELINES ...................................................................... 23
APPENDIX B: SAMPLE ANT SCRIPT FOR PACKAGING A LOCALIZATION BUNDLE. ...................... 25

-i-
1. Introduction

The Localization Package Developers Guide is intended for developers and

localization engineers working on the reusable localization bundles that are used by
Dialog Designer (DD) and DD-generated applications. Dialog Designer is an Eclipse-
based toolkit that contributes tools, editors, and a framework for developing speech-
enabled applications that run on Avaya Voice Portal, Avaya IR, or another VoiceXML
compliant platform.

A localization package consists of a Java executable library (JAR) and associated

resources such as the recorded audio files (.WAV) and Dialog Designer meta-data
files, which are packaged in a container JAR file. The localization package is loaded
at runtime and is used to convert values such as numbers, date, time, and so on, to
a series of pre-recorded audio clips that represent the value. For example, localizing
“1,234” in English would result in a list of audio files that say “One-thousand, two
hundred and thirty-four”, while in Spanish the same value would return the list of
Spanish audio files that speak “Un mil, doscientos treinta y cuatro”. The concept is
that application data can be converted into pre-recorded audio phrases rather than
being synthesized using Text-to-Speech technologies.

This guide is meant to assist a developer who is creating a new localization package
or modifying an existing package. It documents the steps to setting up an Eclipse
environment for Java development, the project structure for each localization
package, the logic involved in writing the localization class, how to deploy and test
the package and general best practices for creation of a new localization bundle.

Requirements
The list of required software is:

• Java J2SE 5 or greater

• Apache Tomcat 5.x or greater
• Microsoft Speech SDK
• Dialog Designer

1
 2.Eclipse Project Setup

Linguistic considerations
Prior to developing the Java code for the localization bundle, it may be worthwhile to
become familiar with some of the linguistic considerations. (See Linguistic
development and other practices).

Creating a new Project

A localization package project is a standard Eclipse Java project. Refer to the Eclipse
documentation for creating Java projects as well as for environment setup. Each
localization package project takes the following format:

To create a new Java project, use the new project wizard to create the project:

File > New Project:

2
The name of the project is not too important. By default Avaya developed
localization projects are named: com.avaya.sce.<language code> where the
language code is the two letter ISO language code followed by the two letter ISO
country code. For example, en-us, es-es, etc.

Language codes: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt

Country codes: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

As long as the localization bundle contents are in the correct format, then Dialog
Designer will be able to import and work with the localization packages.

When creating the project, make sure that the “Create separate source and output
folders” option is selected. This will create separate directories for the source code
and the compiled .class files and will keep the project organized.

The runtime framework classes for the localization packages are required to be on
the classpath for the project. From a Dialog Designer project, copy the “scert-
<version>.jar” file into the project and add to the classpath. The interfaces used by
the localization bundles should never change so you should not have to worry about
updating the build path with updated JAR files very often.

3
4
3.Project Structure

Eclipse by default will create a few project files that are part of every Java project.
In addition to the default project files, localization package projects contain the
following files and directories:

Directory Contents
audio/ The audio files (8bit 8kHz mono wav files).

docs/ Contains documentation on the localization bundle, which

contains the details on what the localization bundle supports,
formats, etc.
lib/ Contains the scertlocale.jar – the framework classes for
localization bundles. The Dialog Designer runtime library,
scert-<version>.jar may also be used in place of
scertlocale.jar.
sage/meta/phrases/ The metadata files for the Dialog Designer phrases. There is a
single .phraseset file the localization bundle.

sage/meta/prompts/ <lang. code>.xml – This is an XML file that defines the

localization properties (formats and additional attributes)
required by the localization package. The Dialog Designer
Prompt Editor uses this file to populate the properties window
with the formats and additional attributes.
src/ <lang code>.properties – This properties file contains at a
minimum one property “bundle.version” which contains the
version string for the localization bundle. For example:
bundle.version=3.1.0. The version string should follow the
format “M.m.i”, where “M” is major version, “m” is minor
version, and “i” is the iteration or build version. This version
string is used in the packaging of the localization bundle and
is also used by Dialog Designer for managing bundle versions
in the workspace.
src/locale/<lang. FormatLocale.java – the implementation of the localization
code>/ logic for the language package.
IPhraseDefs.java – (optional) if the Conversant EBS Phrase >
Dialog Designer phrase conversion utility is used.

5
 Audio files
The audio directory contains the set of audio files that are required to localize
application data in all supported formats. Each file is pre-recorded audio that speaks
all or a portion of a localizable value, for example “one”, “fifteen”, “Monday”, “2004”,
“January”, etc. The audio file must be one of the supported audio formats as
specified by the VoiceXML specification (see:
http://www.w3.org/TR/voicexml20/#dmlAAudioFormats). Dialog Designer requires
the file to be an 8 kHz 8-bit mono WAV file.

There is no naming convention to the audio files—often these files take a numeric
name that makes it easy to perform calculations to determine the audio clip for the
data. For example “one” could correspond to 1.wav, “two” to 2.wav, etc., which
means a string of digits “397” could map to the audio files 3.wav, 9.wav and 7.wav.
For consistency, all audio files should use numerical names with zero padding (i.e.
0003.wav, 0025.wav, etc.).

Existing language packs which already have a numbering/naming convention for

audio files can be reused for new localization packages.

Documentation
The docs directory contains the documentation on the details of the localization
bundle such as supplementary localization formats, data supported, etc. This
document will become part of the Dialog Designer help system and context-sensitive
help, so it is important that the details of the localization bundle are well
documented.

The format of the documentation will be specified at a later date.

Libraries
The lib directory contains the Dialog Designer localization runtime JAR file that is
required for developing and testing the localization bundle. The localization bundle
should not employ any other JAR files which would introduce a requirement on the
Dialog Designer speech application to include the JAR file.

Phraseset metafile
The phraseset metafile is a Dialog Designer-specific file that contains supplemental
information about the audio files. There is one phraseset metafile per localization
bundle and it contains information about every audio file in the bundle. (NOTE: if
the phraseset file does not contain data for one or more audio files that are part of
the localization bundle, then Dialog Designer will not know anything about the audio
files—they are essentially orphaned). The metafile contains information such as the
transcription of the audio file, search words, etc. The phraseset metafile is generally
intended to be used for pre-recorded audio announcements in Dialog Designer
applications, so most of this information is not required for the “standard” phrases
(localization audio files), but these enable the localization phrases to seamlessly
integrate into a Dialog Designer application. If phrase text (transcription)
information is provided for each audio file in the phraseset, then these phrases can
be included in a recording script report.

6
In a Dialog Designer application, the phraseset metafile will generate a similarly
named Java class, which allows the runtime framework to generate a URL to the
audio file that the VoiceXML browser and media platform will use to play the audio to
the caller. If the phrase text (transcription) value is provided and the audio file
doesn’t exist, then the VXML browser can resort to using text-to-speech for the audio
otherwise the voice platform may have runtime errors if the audio files are not
available.

The localization phraseset must follow the following naming convention: “std_<lang
code>.phraseset”, such as “std_en_us.phraseset”. This naming convention will allow
the localization bundle to be loaded by the runtime framework. A phraseset is a
container for another Dialog Designer file type called a “phrase”. The names of
phrases within the phrase set should also follow a similar naming convention. While
this naming convention is not as critical as the naming convention for the phraseset,
it should be followed for consistency and to ensure compatibility with future changes.
Each phrase will start with the prefix “std_” as an abbreviation for “standard”. The
rest of the name should be a relatively descriptive name that identifies the audio
contents of the phrase, for example, “std_one”, “std_fifteen”, “std_monday”,
“std_2004”, “std_january”, etc. The name of the phrase should be all lower case and
should use underscores (‘_’) to separate words if necessary. Numbers are allowed in
the name, but other characters ‘-‘, ‘$’, ‘#’, etc. are not allowed.

To test if a name is valid, use the Java class wizard to create a new Java class. If
the type name is invalid, it will display an error message: (File > New >Class):

Every phrase from localization bundle has typically defined its respective string
constant to be used within java code to reference individual phrases instead of

7
 referring them by their tags directly. Those constants’ definitions are for all
localization bundles isolated in separate file IPhraseDefs.java. The file contains a
definition of all the standard phrases but also provides a good place to define phrase
arrays for “offsetting” the ranges of phrases for simpler code. This definition can be
also placed directly in the FormatLocale.java, however this concept keeps the
phrases better organized for the localization bundle.
public interface IPhraseDefs {

public static final String STD_A = "std_a";

public static final String STD_B = "std_b";
public static final String STD_C = "std_c";
public static final String STD_D = "std_d";
public static final String STD_E = "std_e";
public static final String STD_F = "std_f";
public static final String STD_G = "std_g";
....
....

// Declaration of the consecutive ranges of phrases:

public static final String STD_LETTERS [] = {STD_A, STD_B, STD_C, STD_D, STD_E,
STD_F, STD_G, STD_H, STD_I, STD_J, STD_K, STD_L, STD_M, STD_N,
STD_O, STD_P, STD_Q, STD_R, STD_S, STD_T, STD_U, STD_V, STD_W,
STD_X, STD_Y, STD_Z };

....
....
}

Prompt metafile
Each language package contains one single metafile that specifies the available
localization formats and any additional formatting attributes that are required for the
language. The metafile is an XML file that is named with the two letter ISO language
code followed by the two letter ISO country code: “en_us.xml”, “es_es.xml”,
“fr_ca.xml”, etc.

The Dialog Designer Prompt Editor tool reads this file and uses it in the Eclipse
Properties view to populate the valid formatting choices and other format attributes.
The prompt code generation also uses the file when generating the code that is
ultimately passed to the locale formatting Java class.

This example is an excerpt of the Spanish (es_es) metafile:

8
<LocalizationProperties>
<Property name="format" comment="The value of the variable will be
formatted into pre-recorded audio using the selected format
specification.">
<Option tag="DMDYY" display="Date - 2 digit month, day, 4 digit year"/>
<Option tag="DMSPDYY" display="Date - spoken month, 2 digit day, 4 digit
year"/>
<Option tag="Nm" display="Number - normal intonation">
<Property name="gender" comment="The gender used in audio selection">
<Option tag="N" display="Neutral" default="true"/>
<Option tag="M" display="Male" />
<Option tag="F" display="Female" />
</Property>
</Option>
</Property>
</LocalizationProperties>

The XML document type definition (DTD) for the Prompt metafile
<!ELEMENT LocalizationProperties (Property+)>
<!ELEMENT Property (Option+)>
<!ATTLIST Property
name CDATA #REQUIRED
comment CDATA #IMPLIED>
<!ELEMENT Option (Property*)>
<!ATTLIST Option
tag CDATA #REQUIRED
display CDATA #REQUIRED
default CDATA #IMPLIED>

Note:
All prompt metafiles should be validated against the DTD to ensure that
the document is well formed and thus will be interpreted properly by the
Dialog Designer Prompt Editor.

This metafile allows the localization package developer to configure the Dialog
Designer Prompt Editor such that the formatting values and attributes are passed to
the localization class. It is important that the developer creates this file so that all
formatting rules and additional information (such as gender, etc.) can be supplied.

9
 Localization Logic
Each localization package contains a single Java class that the Dialog Designer
runtime framework loads on demand to localize application data. This Java class
implements the logic required to convert the application data (in String format) into
the list of audio clips as specified by the formatting parameters.

The localization Java class must be named FormatLocale.java and must be in the
package “locale.<lang. code>” where <lang. code> is the two letter ISO language
code followed by the two letter ISO country code. Examples include,
“locale.en_us.FormatLocale” or “locale.fr_ca.FormatLocale”, etc.

In addition to the naming requirements, FormatLocale must implement the interface

com.avaya.sce.runtime.ILocaleFormatter. This interface allows the runtime to
abstractly reference and to invoke the localization method in the FormatLocale class.
The LocaleResults object that is passed to the ILocaleFormatter is a wrapper around
a Java List to allow the localization bundle to log information/error messages.

The ILocaleFormatter interface defines the single method:

public String[] formatTextToAudio(String value, Format format,
LocaleResults resultMessages) throws InputFormatException;

The implementation of this method must be able to inspect the Format object, which
contains the formatting attributes as defined in the prompt metafile, and evaluate
the String “value” to return an array of phrase names. For example:
formatTextToAudio(“123”, formatInfo, messages);

where “formatInfo” contains the format attribute key-value “format”==”digits” may

return the string array:

10
 { “std_one”, “std_two”, “std_three”}

The same example but using format attribute key-value “format”==”number” may
return the string array:
{“std_hundred”, “std_and”, “std_twenty”, “std_three”}

After invoking the formatTextToAudio method, the runtime framework is then able to
resolve the set of phrase names into their corresponding audio files, which the VXML
platform will play to the caller.

Developing the logic to parse value string is the most complicated aspect of
developing a localization package; however example code already exists for English
and Spanish, so this code can provide an excellent starting point. Existing
Conversant/EBS localization packages may also be used as a reference for much of
the logic; however the code must be ported or re-written into Java. A novice or
intermediate Java developer should be able to understand the Spanish/English
example code and begin developing a new language, as most of the code required to
perform the data localization is String parsing.

11
 4.Developing the Language Package

FormatLocale and Prompt metadata

As discussed in the previous section, the prompt metadata file and the FormatLocale
Java class must remain synchronized such that all formats and additional attributes
the Java class supports must be represented in the prompt metadata file. The
prompt editor supports nested formatting properties so if a language requires a
numeric value to be formatted taking into account gender and inflection (i.e. neutral
vs. falling), then these properties can be nested and the prompt editor will generate
the appropriate code to supply these values to the FormatLocale.

Example:
<LocalizationProperties>
<Property name="format" comment="The value of the variable will be
formatted into pre-recorded audio using the selected format
specification.">
<Option tag="number" display="Number">
<Property name="numbertype" comment="Type of numeric value">
<Option tag="integer" display="Integer" default="true">
<Property name="gender" comment="Gender of the spoken
integer number">
<Option tag="Nm" display="masculine gender">
<Property name="inflection" comment = "inflection
variants">
<Option tag = "Nmn" display ="neutral inflection"/>
<Option tag = "Nmf" display ="falling inflection"/>
</Property>
</Option>
<Option tag="Nf" display="feminine gender">
<Property name="inflection" comment = "inflection
variants">
<Option tag = "Nfn" display ="neutral inflection"/>
<Option tag = "Nff" display ="falling inflection" />
</Property>
</Option>
<Option tag="Nn" display="neutral gender">
<Property name="inflection" comment = "inflection
variants">
<Option tag = "Nnn" display ="neutral inflection"/>
<Option tag = "Nnf" display ="falling inflection" />
</Property>
</Option>
</Property>
</Option>
</Property>
</Option>
</Property>
</LocalizationProperties>

12
If the audio variable in the Prompt builder selects “Format = Number”, “Numbertype
= Integer”, “Gender = masculine gender”, and “Inflection = neutral inflection”, then
the generated code would contain the following code that will be passed to the
FormatLocale for the localization package:
Format formatInfo = new Format();
formatInfo.add(“format”, “number”);
formatInfo.add(“numbertype”, “integer”);
formatInfo.add(“gender”, “Nn”);
formatInfo.add(“inflection”, “Nnn”);

The runtime framework and prompt editor should be flexible enough to allow all
necessary localization parameters and attributes to be available to the localization
class. Current design evaluates only the last attribute from the formatInfo which
identifies the format to be applied for the variable. Therefore the format tag
(identifier) must be unique across all the formats defined within the prompt
metadata. It is the responsibility of the language package developer to keep the
prompt metadata file and FormatLocale class synchronized.

Localization Formats
These are the data formats that all localization packages are expected to support as
well as their naming conventions and data format. All localizable data is represented
in String form and it is expected that the data to be localized follow the format
specification. If the data is not in valid form, then the localization package may
throw an exception.

All localization bundles MUST support these formats. Localization bundles may
optionally support additional formats that may be specific for a certain locale. It is
up to the localization bundle developer to document the additional formats that are
supported.

Format Description Data Format Format Tag

(starts with)
Date Formats a date string into set of Type: String D
audio clips depending on the
Format:
particular type of date formatting
(i.e. 2 digit month, 2 digit year; 2 YYYY[-]MM[-]DD
digit month, 4 digit year; spoken
Example:
month, 4 digit year, etc.)
2005-05-04
20050504

13
 Format Description Data Format Format Tag
(starts with)
Time Formats a time string as specified Type: String T
by the format type (i.e. 12 hour,
Format:
minutes, AM/PM; 24 hour,
minutes; 12 hour, minutes, HH[:]MM[:][SS]
seconds, AM/PM, etc.)
Example:
031545
03:15
03:15:45
Number Formats the digit string into Type: String N
numbers as specified by the
Format:
format type (i.e. “one hundred
fifty eight”, with decimal places, [-
fractions, etc.) ]#[,<space>.]###[
,<space>.]#
Example:
The delimiters for this format are
a comma (‘,’), and period (‘.’). 1024
The localization bundle will treat
15,588.345
the right most delimiter as the
decimal part of the number. 10.123,52

Localization bundles may define

numbers to be treated as integers
where decimal places and
fractional parts are ignored. The
format tags (in the prompt
metadata file) should clearly
identify this behavior.
Currency Formats the digit string into a set Type: String M
of audio clips that speak a
Format:
monetary value.
#[,<space>.]###[,
<space>.]#
The format is the same as
Example:
Number
1,245
1048.25

14
Format Description Data Format Format Tag
(starts with)
Characters Speaks a String character by Type: String C
character. At a minimum, all
xxxxxxx
localization bundles must support
A-Z, 0-9, *, #, (comma), Example:
(space). (i.e. “abc” as “a” “b”
aeiou
“c”, or “123” as “one” “two”
“three). 123
Localization bundles may support 401k
additional characters (including
non-Latin characters).
Localization bundles will ignore
extended characters that are not
supported.

Each localization package is expected to define additional format tags that provide
more detailed formatting options than the five listed in the above table—the tags
above are general categories that all localization packages must support. For
example, the Date format tags supported by Conversant US English is:

Tag Description
DMDYY 2 digit month, day, 4 digit year
DMDY 2 digit month, day, 2 digit year
DMD 2 digit month, day, but no year
DMSPDYY spoken month, 2 digit day, 4
digit year
DMSPDY spoken month, 2 digit day, 2
digit year
DMSPD spoken month, 2 digit day, but
no year

And the Date format tags supported by Conversant Czech is:

Tag Description
DDMSPYY day, spoken month and 4 digit year
DDMYY day, month and 4 digit year
DMMSP day, month spoken, no year
DDM day, month, no year
DDMSPYYf day, spoken month and 4 digit falling year
DDMYYf day, month and 4 digit year, falling form
DMMSPf day, month spoken, no year, falling form

15
 DDMf day, month, no year, falling form

Because the format tags will often vary independently across localization packages, it
is important that each localization package support a default format if the tag that is
supplied to the localization package is not supported. This situation may occur in a
Dialog Designer project when a new language is added that is based off an existing
project language. The new language operation makes a copy of all resources in the
base language for the new language, so any prompts that use a format tag from the
base language will use the base language tag unless the Dialog Designer developer
modifies the format. To avoid illegal formats, each localization package should
define some code that determines if the format code is valid, and if it is not a
supported code, then resort to the default code for the language. For example:
/**
* Validates the formatTag is a legal tag supported by this
localization package
* and returns the tag or a default tag if formatTag is not supported.
*/
String getFormatString(String formatTag) {

// test to see if formatTag is a valid format, if not return the default ....

// figure out default formats

if(formatTag.startsWith("M")) {
return "MD2";
} else if (formatTag.startsWith("N")) {
return ("Nmmm");
} else if (formatTag.startsWith("D")) {
return ("DMMDYY");
}
// etc....
}

/**
* Converts the value string into an array of audio phrase names based
* on the attributes set in the Format object. Throws an
* InputFormatException if the value data is not formatted properly to
* be localized.
*/
public String[] formatTextToAudio(String value, Format format, LocaleResults
resultMessage) throws InputFormatException;

// get the requested format tag and if the tag is invalid, get the default
String formatTag = format.get(Format.FORMAT);
formatTag = getFormatString(formatTag);

...

16
Writing the FormatLocale class
The FormatLocale class is responsible for evaluating the value string given the
format attributes and returning an array of audio phrase names. The phrase names
must be the names of phrases in the localization package, and the order of the array
must be in the order the phrases will be played to the caller.

The Java language supplies all of the string parsing and number conversion API that
is required to develop the FormatLocale class. The String class contains useful API
such as startsWith(), indexOf(), substring(), endsWith(), length(), etc. The number
classes, Integer, Float, etc. define static API to convert a String into a float or int.
The String.split() method (or the StringTokenizer class) is a good utility that will
extract segments of a String given delimiters.

String arrays can be used for “offsetting” when evaluating various data values. For
example:
String[] MONTHS = {“std_january”, “std_february”, …, “std_december”};
String[] DIGITS = {“std_zero”, “std_one”, “std_two”, …, “std_nine”};
String[] TENS = {“std_zero”, “std_ten”, “std_twenty”, …, “std_ninety”};

“1040” as digits would convert to:

DIGITS[1], DIGITS[0], DIGITS[4], DIGITS[0]

“75” as a number would convert to:

TENS[7], DIGITS[5]

The ultimate goal for these classes is to be easily readable and understandable,
which makes maintaining the code easier. The names of functions and variables
should be logical and care should be taken so that code (functions) can be called and
reused by other functions as opposed to a single one-thousand line function that
does everything.

17
 5.Packaging the Localization Bundle for
Dialog Designer

Properly packaging the localization bundle for Dialog Designer is important otherwise
it will not be able to be imported into the development environment or invoked
properly.

The localization bundle must be packaged as a JAR file with the name <lang.
code>_<version>.zip, where version is a “dotted string” (i.e. “3.1.0”). The contents
of the bundle JAR are:
<lang. code>.jar The compiled contents of the src/ folder—contains the byte
code for locale.<lang. code>.FormatLocale as well as
any other helper classes. (NOTE: source code may
optionally be included).

This JAR file should also include the <lang

code>.properties file so that the “bundle.version”
property is part of the runtime logic JAR file.
<lang A properties file that contains properties for the bundle.
code>.properties The only mandatory property is “bundle.version” that
has the value of the version string (i.e. “3.1.1”).
audio/*.wav
This directory contains all of the audio files for the bundle.
The audio files must be 8kHz-8bit WAV files.
phraseset/std_<lang
code>.phraseset The phraseset directory contains the one phraseset file that
stores the metadata for all of the audio files in the
localization bundle.
prompt/<lang.
code>.xml The meta data file that is used by the Dialog Designer
Prompt Editor for reading the formats supported by the
localization bundles.

For example, the packaged US English (en-us) localization bundle would look like:
en-us_3.1.0.jar
en-us.jar
Contains locale.en_us.FormatLocale.class,
any helper classes, and the en-us.properties
file.
en-us.properties
Contains the property: bundle.version=3.1.0

(NOTE: the version number should match the

version number of the localization bundle JAR
file)

18
 audio/*.wav
Contains the audio files for the US English
localization bundle
phraseset/std_en_us.phraseset
The phraseset file that contains information
about all of the audio files in the audio/
directory. This information is, at a minimum,
the phrase text, but may contain supplemental
information such as pronunciation comments,
voice talent, etc.
prompt/en-us.xml
The formats supported by the US English
localization bundle.

See Appendix B for an ANT script that can be used to compile and package a
localization bundle.

19
 6.Linguistic development and other
practices

This section describes in general the best practices and common procedures when
creating new language bundle. This knowledge was gathered based on the
experience of the Avaya Globalization team with previous development of voice
applications including Enhanced Basic Speech for IVR platforms and the standard
localization bundles for Dialog Designer for existing languages.

Grammar development and phrases’ identification

As discussed in the former section, every localization bundle needs to support a
minimum of one format for each format category for a given language. These
categories include:

• Date
• Time
• Number (integer)
• Number (decimal)
• Currency
• Spelling (digits & numbers)

It is important to engage a native speaker (linguist) to identify the most common

formats that are used in the target region (country). Multiple formats for each format
category may be identified based on their common usage and implemented within
the localization bundle. This also includes intonation variants, typically covering
neutral, raising or falling inflections. Complexity of the code development relates
closely to how many formats will be supported, which also impacts the number of
necessary phrases (voice fragments) to be created and recorded in studio.

In cooperation with the linguist it should be defined how each format is spoken and
also what individual phrases (voice fragments) would be used for concatenation. It
should be balanced how the formats would be fragmented in contrast to speech flow.
Despite some languages might allow higher fragmentation, for optimization reasons
it is often preferable to record more fragments to achieve smoother voice playback.
For example:

The number 45 can be concatenated as “forty” + “five”. It is very common that

many languages record all numbers from 0-99 range as individual fragments (as
“forty five”) than concatenate those numbers from 2 separate fragments. The
extreme end of speech optimization however may result in large number of voice
files and thus in high cost for recording (and future rerecording) of the voice files.
For example, the UK English localization bundle tried to implement perfect speech
flow so the developer created an extensive set of phrases for numbers 0-99

20
concatenated with word “pound” (for currency format), same for “minutes” multiplied
by intonation variants. The resulting phrase set includes 2500+ individual phrases.

It is also a good practice to experiment during the actual recording session in the
studio to record several voice fragments as separate recordings and concatenate
them manually in sound editor in order to:

- adjust pronunciation of individual voice fragments

- identify whether the concatenation is acceptable or more complete fragments
would be necessary to record

This may fine tune the final set of phrases and respective voice files to be
created/recorded.

Vocalist and studio selection

It is important to consider several factors when selecting vocalist and studio. The
vocalist should be accepted by a target audience (the users of the voice interactive
systems in given region/country) respecting common local customs – gender, age,
voice tone and pitch and tempo of the speaker. The general preference for existing
localization bundles was female vocalist. However it may differ based on cultural
aspects (e.g. Arabic regions may favor male vocalists, etc.)

Further it is necessary to consider the vocalist’s long-term availability (for potential

re-recordings or additions), experience in such type of recordings, hourly rate, etc.
For the studio it is important that they can meet the technical and quality
requirements, and consistency in final sound quality, etc.

The recording script for a studio session should contain a list of phrases with their
respective file names. Release 3.1 of Dialog Designer introduces a new feature that
can generate a recording script for an existing phrase set. In order to create a
recording script, the developer must have a localization bundle pre-built with the
complete set of phrases and used by a dummy DD application. The report can be
created by running a utility from menu Project -> Reports -> Recording script. In
case the recording session is executed before the actual localization bundle is shaped
the recording script must be prepared manually.

Please see Appendix A for recording guidelines which should be shared with studio
prior recording.

Testing of the localization bundle

After all the Java code is in place for the language grammar and formats supported,
the developer can use the Avaya Localization Test Tool to perform development
testing. This tool efficiently allows the developer to exercise the code for various
formats with a set of values that can be used to verify that all the expected
functionality is correct and the returned set of phrases to be spoken is appropriate.

The testing of the localization bundle can occur even before recording takes place
(when the voice files are created) because the tool can return only phrase names
allowing the developer to check whether the correct phrases are returned for the

21
 given value/format as expected. After the voice files are available the test tool can
also play back the voice files (phrases) concatenated so the speech flow can be also
examined.

This is generally a good practice to use an extensive set of values to verify correct
behavior of the Java code for each format. The set of test values should cover
randomly an entire supported range of values for each format, also to cover certain
special cases (e.g. like 00:00 for time, or -0.001 for decimal, specific grammar cases
for that given language, etc.). Test values should also contain invalid ones - either
malformed or out of supported range (e.g 2006-20-20 for date, or 12:011:45 for
time, etc.)

22
Appendix A: Template for recording
guidelines

This is a template the Avaya Globalization team uses to communicate guidelines for
recording audio files to be used in a Dialog Designer Localization Bundle. Developers
may follow these guidelines as needed.

subject: Studio Recording Guidelines date:

Project: Dialog Designer Localization Bundle

Language:
Recording Date:
Recording Studio
Phone:
Studio Contact:
Phone:
Vocal Talent:
Phone:
Customer Contact:

The following are the guidelines to use when conducting the recording session:

1. The final delivery must be a clean recording.

2. Speech is to be recorded on CD-ROM sampled as:
- 44.1kHz , 16-bit linear (no compression) monophonic WAV (pcm)
- 8kHZ , 8-bit linear (no compression) monophonic WAV (pcm)
3. File Naming Convention: must match with the filenames in recording script,
column A – zero padded 4 digit + .wav extension. Should there be a need for
recording alternates, please use the original file name with successive
alphabetic characters appended. Thus, alternate takes to fragment 701 would
be named 0701a.wav, 0701b.wav, etc.
4. Regardless of any alternate takes, there absolutely must be a take of each
fragment exactly as it appears in the recording script.

23
 5. If necessary, apply a DC bias adjustment so that the waveform is centered at
0.
6. Silence at the beginning and end of each waveform should be as follows:

At the beginning of all phrases prepend ~25 milliseconds at the

beginning of the waveform

If phrase ends with a question mark append ~75 milliseconds at the end
(?) or period (.) – raising or falling of the waveform
inflection

If phrase ends with anything else append ~25 milliseconds at the end
(neutral inflection) of the waveform

7. Edit out all audible breaths between words and any “mouth clicks” within
words.
8. A backup of the original recording session must be archived at the studio.
9. Additional comments:

Due to specific nature of this recording the individual prompts should be recorded
considering the concatenation of the individual prompts into larger blocks e.g.:

“February” – “twenty first” – “two” – “thousand” –“five”

The intonation of the prompts (pitch, pace, volume) should remain consistent
throughout the recording. It is a very good practice that during recording session the
individual edited prompts are concatenated in sound editor for test and played back
concatenated to verify that the final speech flow is smooth and sounds naturally. The
necessary adjustments to pronunciation can be made for recording alternates.

The general guidance for reading the recording script is:

- ignore any colons, they are part of most standard phrase names by default
- phrases terminated with question marks (?) should be spoken with raising
inflection
- phrases terminated with period (.) should be spoken with falling inflection

24
Appendix B: Sample ANT script for
packaging a localization bundle.

This ANT script can be used to build and package a localization bundle. The script
relies on the proper project structure, so any packaging errors may indicate that the
project does not have a valid structure.

The ANT script may need some property values to be set so that the Java build
classpath is set correctly.

<?xml version="1.0"?>
<!-- ======================================================================
Aug 24, 2006 1:39:35 PM
====================================================================== -->
<project name="Localization Bundle Build" default="locbundle.build.english" basedir=".">
<description>
Script for building, packaging, and signing localization bundles
</description>

<!-- - - - - - - - - - - - - - - - - -
target: init
- - - - - - - - - - - - - - - - - -->
<target name="init">
<property name="temp.dir" value="${basedir}/temp.folder"/>
<property name="dest.dir" value="/temp"/>

<!-- directories used for the build -->

<property name="dir.java" value="${temp.dir}/java"/>
<property name="dir.java.src" value="${dir.java}/src"/>
<property name="dir.java.bin" value="${dir.java}/bin"/>
<property name="dir.bundle" value="${temp.dir}/bundle"/>
<property name="dir.audio" value="${dir.bundle}/audio"/>
<property name="dir.phraseset" value="${dir.bundle}/phraseset"/>
<property name="dir.prompt" value="${dir.bundle}/prompt"/>

<!-- properties for the classpath for compilation step.

NOTE: Change these properties as needed so jar files are properly
referenced
-->
<property name="jar.scert" value="${basedir}/lib/scert.jar"/>

<!-- To skip signing, comment out this property.

NOTE: signing must be run on a machine that has certificates installed
<property name="sign.jar" value="true"/>
-->

</target>

<!-- - - - - - - - - - - - - - - - - -
target: clean
- - - - - - - - - - - - - - - - - -->
<target name="clean" depends="init">
<delete dir="${temp.dir}" />
</target>

<!-- - - - - - - - - - - - - - - - - -
target: locbundle.build.english
Builds the US english localization bundle.
If the parameter "dest.dir" is provided, the packaged localization bundle

25
 will be copied to this directory.
- - - - - - - - - - - - - - - - - -->
<target name="locbundle.build.english">
<antcall target="locbundle.build">
<param name="lang.code" value="en-us"/>
</antcall>
</target>

<!-- =================================
target: locbundle.build
Builds a localization bundle. Parameters:
- ${lang.code} - The language code for the bundle (ie. en-us)
- ${dest.dir} - The directory where the packaged bundle will be put.
================================= -->
<target name="locbundle.build" depends="init" description="Builds a localization
bundle. Need ${lang.code} and ${dest.dir}" if="lang.code">
<echo>Building language bundle ${lang.code} to directory: ${dest.dir}</echo>
<antcall target="build.bundle"/>

<!-- now cleanup the temp directory -->

<antcall target="clean" />
</target>

<!-- - - - - - - - - - - - - - - - - -
target: build.bundle
Requires param "lang.code"
- - - - - - - - - - - - - - - - - -->
<target name="build.bundle" depends="init">
<echo>Building localization bundle for ${lang.code}.</echo>
<echo>The packaged localization bundle will be copied to: ${dest.dir}</echo>

<!-- set the lang.code property for the rest of the script -->
<property name="lang.code" value="${lang.code}"/>

<!-- start with clean directory -->

<antcall target="clean" />

<!-- prepare the directory -->

<antcall target="build.prepare.build.dir" />

<!-- build the logic JAR file -->

<antcall target="build.localization.logic.jar" />

<!-- build localization bundle deploy JAR -->

<antcall target="build.localization.bundle.jar" />
</target>

<!-- - - - - - - - - - - - - - - - - -
target: build.prepare
Prepares the build directory and copies all necessary files
into the working directory.
- - - - - - - - - - - - - - - - - -->
<target name="build.prepare.build.dir">
<property name="bundle.project" value="../com.avaya.sce.${lang.code}"/>
<echo>Preparing working directory for bundle ${lang.code}.</echo>

<!-- create the build directory -->

<mkdir dir="${temp.dir}"/>
<mkdir dir="${dir.bundle}"/>
<mkdir dir="${dir.audio}"/>
<mkdir dir="${dir.java}"/>
<mkdir dir="${dir.java.src}"/>
<mkdir dir="${dir.java.bin}"/>
<mkdir dir="${dir.phraseset}"/>
<mkdir dir="${dir.prompt}"/>

<!-- copy the java classes -->

<copy todir="${dir.java.src}">
<fileset dir="${bundle.project}/src" />
</copy>

26
 <!-- copy the audio files -->
<copy todir="${dir.audio}">
<fileset dir="${bundle.project}/audio">
<include name="*.wav"/>
</fileset>
</copy>

<!-- copy the phraseset meta file -->

<copy todir="${dir.phraseset}">
<fileset dir="${bundle.project}/sage/meta/phrases">
<include name="*.phraseset"/>
</fileset>
</copy>

<!-- copy the prompt meta file -->

<copy todir="${dir.prompt}">
<fileset dir="${bundle.project}/sage/meta/prompts">
<include name="${lang.code}.xml"/>
</fileset>
</copy>
</target>

<!-- - - - - - - - - - - - - - - - - -
target: build.localization.logic.jar
Compiles the Java classes (the logic) for the localization bundle and
builds a JAR file.
- - - - - - - - - - - - - - - - - -->
<target name="build.localization.logic.jar">

<!-- compile the java class -->

<javac srcdir="${dir.java.src}"
destdir="${dir.java.bin}"
classpath="${jar.scert}"
debug="on"
/>

<!-- now JAR the localization bundle -->

<property name="jar.file" value="${dir.bundle}/${lang.code}.jar"/>
<jar destfile="${jar.file}">
<fileset dir="${dir.java.bin}" />
<fileset dir="${dir.java.src}" />
</jar>

<!-- now sign the JAR file -->

<antcall target="build.sign.jar" />
</target>

<!-- - - - - - - - - - - - - - - - - -
target: build.localization.bundle.jar
Packages the localization bundle into a properly structured JAR file
- - - - - - - - - - - - - - - - - -->
<target name="build.localization.bundle.jar">

<!-- copy properties file to temp dir -->

<copy todir="${dir.bundle}">
<fileset dir="${dir.java.src}">
<include name="${lang.code}.properties"/>
</fileset>
</copy>

<!-- loads the "bundle.version" property from the properties file -->
<loadproperties srcFile="${dir.bundle}/${lang.code}.properties">
<filterchain>
<linecontains>
<contains value="bundle.version"/>
</linecontains>
</filterchain>
</loadproperties>
<echo>Localization bundle ${lang.code} version: ${bundle.version}</echo>

27
 <!-- now JAR the localization bundle -->
<property name="jar.name" value="${lang.code}_${bundle.version}.jar"/>
<property name="jar.file" value="${temp.dir}/${jar.name}"/>
<jar destfile="${jar.file}">
<fileset dir="${dir.bundle}" />
<manifest>
<attribute name="Built-By" value="Avaya, Inc. (Dialog
Designer)"/>
</manifest>
</jar>

<!-- Sign JAR file. -->

<antcall target="build.sign.jar" />

<!-- now copy to the destination directory -->

<copy todir="${dest.dir}">
<fileset dir="${temp.dir}">
<include name="${jar.name}"/>
</fileset>
</copy>
</target>

<!-- - - - - - - - - - - - - - - - - -
target: build.sign jar
Signs the JAR file if the "sign.jar" property is set
- - - - - - - - - - - - - - - - - -->
<target name="build.sign.jar" if="sign.jar">
<echo>Use the signjar task to sign the JAR file.
Certificates must be installed in order to successfully sign JAR files.
</echo>
</target>
</project>

28