Translation Dictionaries Content Development Kit for Word 2002: Version 1.0

  • Article

Click here to download sample - sample.exe. (197 KB) This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

 

Microsoft Corporation

March 2002

Summary: Learn how to add new translation dictionary services to the Word 2002 Translation Task Pane. (9 printed pages)

Download Sample.exe.

Contents

About the Translation Dictionaries CDK
Adding New Translation Services
   Overview
   Formatting Content as XML
   Using Helper Objects
   Building the Service
   Creating a Windows Installer Setup Package

About the Translation Dictionaries CDK

This Translation Dictionaries Content Development Kit (CDK), along with the accompanying files, allows you to add new translation dictionary services to the Microsoft® Word 2002 Translation Task Pane.

The task pane allows you to input a word and output a related definition or translation. This documentation explains how you can create any number of additional dictionaries beyond those that were distributed with Word 2002.

This documentation is designed as a resource for Solution Providers (SP), Independent Software Vendors (ISV), and developers interested in building translation services for Word 2002. To use this documentation effectively, you should be familiar with:

  • Component Object Model (COM)
  • Extensible Markup Language (XML)
  • Microsoft Visual Studio®, Microsoft Visual C++®, or an equivalent development environment

Adding New Translation Services

Overview

A translation service must be built in order for it to work correctly. You begin by creating a source file that contains your content, which must be tagged using the XML tags listed within. Later, you will transform this source file into a set of destination files using BuildLexRefService.EXE. The destination files can then be installed, allowing your service to appear in the Word 2002 Translation Task Pane.

Creating a translation service can be broken down into the following steps:

  1. Produce properly formatted XML for the content and the index.
  2. Determine what helper objects are needed for the translation service, and create any that are necessary for your service.
  3. Build the service by creating an INI file that describes the service and then running BuildLexRefService.EXE.
  4. Create a Windows Installer setup package that installs and registers the service.

Formatting Content as XML

Overview

Although the content can be stored in any format, this CDK comes with sample code that can be used to build a plain-text source file. In order to take advantage of this, you must create a text file that contains your content and that is tagged using the XML tags in the table below.

You may use an alternative storage format, such as a Microsoft Access database file, as your source format (or even your destination format), but you will need to write your own code to build the files, and use that code instead of the samples provided.

Tagging the content

The content should consist of a list of headwords with corresponding translation information. Each headword has one or more translations, with possible other elements, like part-of-speech, examples, context information, and so forth (depending on the language pair).

The following XML tags are provided for a custom translation service.

Table 1. Metalinguistic tags

<HEADWORD> Article headword: the word to be translated
<TRANSLATION> Translation of the headword
<EXAMPLE> Examples of the usage of the headword
<POS> Part-of-speech

Table 2. Formatting tags (a combination of these tags can be used—see also the DTD below)

<B> Bold
<I> Italics
<TEXT> Plain text
<SCAPS> Small capitals
<SUB> Subscript
<SUPER> Superscript

XML DTD

This simplified Document Type Definition (DTD) describes the rules for proper XML formatting. It can be used to determine which formatting combinations are valid, and can also be used to programmatically check large amounts of XML.

Key:

? = zero or 1 times

* = zero or more times

| = or

O = tag may be missing (in fact, the ARTICLE, ARTICLETEXT, FORMATTING, and DOC tags will always be omitted)

- = tag is necessary

DTD Listing:

<!DOC         O   O   (ARTICLE*) >
<!ARTICLE      O   O   (HEADWORD,HOMOGRAPH?, ARTICLETEXT)>
<!ARTICLETEXT   O   O   ((NUM|TRANSLATION|POS|EXAMPLE|FORMATTING)*)>
<!FORMATTING   O   O   (B|I|SUPER|SUB|SCAPS)>
<!HEADWORD   -   -   CDATA>
<!HOMOGRAPH   -   -   CDATA>
<!B         -   -   (I|SUPER|SUB|SCAPS|CDATA)>
<!I         -   -   (B|SUPER|SUB|SCAPS|CDATA)>
<!SUPER      -   -   (I|B|SUB|SCAPS|CDATA)>
<!SUB         -   -   (I|SUPER|B|SCAPS|CDATA)>
<!SCAPS      -   -   (I|SUPER|SUB|B|CDATA)>
<!TRANSLATION   -   -   CDATA>
<!POS         -   -   CDATA>
<!EXAMPLE      -   -   CDATA>
<!NUM         -   -   CDATA>    used for sense numbers

Using Helper Objects

A translation service can be divided into a set of objects that are linked to form an object chain. An object is a piece of functionality related to the translation service. For example, "lookup," the fundamental act of checking to see if a word is in your translation dictionary, is one of many objects in a typical translation service's object chain.

As the author of a new translation service, you can create as simple or complex an object chain as you like. Sample code is provided to help you implement the simplest, most typical type of translation service. The object chain of such a service is shown below:

Aa140289.odc_wordtranscdk_01(en-us,office.10).gif

Figure 1. Object chain

Stemmer Object   An optional object that increases the hit rate of your translation service by changing inflected forms of the query term (for example, jumping) to its root (jump).

Lookup Object   Performs lookups to your translation service. The lookup object can contain language-specific features (for example, it can attempt to find multi-word matches like "record player" before attempting to find a single-word match like "player").

Build Object   Transforms the source content file into the destination files, and performs error checking. Note that the build object should be a "slave" of the lookup object for structural purposes.

XML to RTF Object   Transforms the XML in the content file into a format that Word 2002 can display.

You must supply the lookup object and build object for your translation service. Sample files are provided to assist you in creating them. The sample files can be used with no changes and will yield a functional text-based translation service with no stemming.

**Note   **The files provided with this documentation have been tested to compile in Visual C++ or Visual Studio. You may use the source code in another development environment as well, but you may need to do additional work to ensure that they compile properly.

The XML to RTF object is supplied with Word 2002 and should be called by any custom translation service that uses XML-formatted content.

Although you may not use any of the stemmer objects supplied with Word 2002, you may create your own and use them as part of your translation service.

Creating additional objects

If necessary, additional objects can be created to add extra features to your translation service. Objects will be COM objects with a generic interface to the main DLL. They must be described in the INI file as a part of the service's object chain, and their DLL files must be installed in the setup package described below.

Building the Service

By this stage you should have:

  • Created a properly formatted source file for your content.
  • Designed the object chain your translation service will use, and implemented any objects needed in your object chain (except for the XML to RTF object, which is supplied with Word 2002).

In order to build the service you will now:

  1. Create an INI, or project, file that describes your service's object chain, and that may also contain any extra attributes needed by your objects.
  2. Ensure that you are building on a machine that has both Word 2002 and the Translation Dictionaries feature installed. This feature may not be installed by default, but you can easily install it by choosing Tools | Languages | Translate from the Word 2002 menu, and performing a translation using one of the included translation services.
  3. Run BuildLexRefService.EXE to create the destination files of your service.

BuildLexRefService.EXE takes the following as input:

  • Source content file containing the lexical data
  • INI file describing the object chain of the translation service
  • Empty ITS file
  • DLL files that contain the objects referenced in your INI file

Aa140289.odc_wordtranscdk_02(en-us,office.10).gif

Figure 2. Create the destination files

Creating the INI file

These are the minimum requirements for an INI file.

  • The file must have Attributes and Object Chains sections.
  • The Attributes section must have Name, Description, GUID, Locator, and Loader ProgID attributes.
  • The Object Chains section must have Main declared for default object chain.
  • The Object Chain:name sections must exist for all object chains declared in the Object Chains section.
  • The Object Chain:name sections must have an Object Sequences attribute that is names of objects delimited by commas.
  • The Object:name sections must exist for all objects declared in Object Sequences attributes.
  • The Object:name sections may have the Build Object attribute defined.
  • The Build Object:name sections must exist for all build objects defined in Build Object attributes.
  • The Object:name and the Build Object:name sections must have the ProgID attribute defined. The ProgID is COM ProgID of Lexical Reference Service Code.

Structure of the INI file

The following information contains a blank sample INI file that runs through the service builder. This sample demonstrates the bare minimum requirements that demonstrate object chaining and use of a slave object.

[Attributes] required
Name = Sample Project File required
Description = This is a Sample Project File required
GUID = {127BA6C6-22D4-4B84-996D-FAE36135FA10} required, must be    unique for every service
Locator = C:\Sample.ITS!Attributes required, all information    contained in this project file gets persisted to this       location using ILlexicalReferenceServiceAttributeLoader          interface through Loader ProgID
Loader ProgID = LR.LexRefBilingualServiceAttribute.1.0 required
 
[Object Chains] required
Main required
 
[Object Chain:Main] required
Object Sequences = ObjectA, ObjectB required
 
[Object:ObjectA] required because of Object Sequences in [Object Chain: Main] section
ProgID = ObjectA ProgID required in Object section
Attribute1 = Setting for Attribute1
Attribute2 = Setting for Attribute2
AttributeN = Setting for AttributeN
 
[Object:ObjectB] required because of Object Sequences in    [Object Chain: Main] section
Build Object = BuildObjectB
Name = Object B
ProgID = ObjectA ProgID required in Object section
Slave Objects = SlaveA, SlaveB
Attribute1 = Setting for Attribute1
Attribute2 = Setting for Attribute2
AttributeN = Setting for AttributeN
 
[Object:SlaveA]  required because of Slave Objects in    [Object:ObjectB] section
ProgID = SlaveA ProgID required in Object section
Attribute1 = Setting for Attribute1
Attribute2 = Setting for Attribute2
AttributeN = Setting for AttributeN
 
[Object:SlaveB]  required because of Slave Objects in    [Object:ObjectB] section
ProgID = SlaveB ProgID required in Object section
Attribute1 = Setting for Attribute1
Attribute2 = Setting for Attribute2
AttributeN = Setting for AttributeN
 
[Build Object:BuildObjectB] required because of Build Object in    [Object:ObjectB] section
ProgID = ObjectB ProgID
Attribute1 = Setting for Attribute1
Attribute2 = Setting for Attribute2
AttributeN = Setting for AttributeN
 

Sample English to French INI file

For example, suppose you want to create an English-to-French translation dictionary that accepts an English word as input and returns a French equivalent with a definition. The following sample shows an INI file that would provide this functionality:

[Attributes]
Name = English to French
Description = Test English to French Content Service
GUID = {127BA6C6-22D4-4B84-996D-FAE36135FA10}
Locator = C:\BILINGUALS10\CONTENTBUILD\TESTENFR.ITS!Attributes
Loader ProgID = LR.LexRefBilingualServiceAttribute.1.0

[Object Chains]
Main

[Object Chain:Main]
Object Sequences = EnglishToForeignStemmer, EnglishToForeign, XMLToRTF

;UUID_ULexRefPremiumServiceKeyforOffice_RichEditText
GUID = {127BA6C6-22D4-4B84-996D-FAE36135FA01}

;UUID_ULexRefPremiumServicePrivilegeKey
Privilege = {127BA6C6-22D4-4B84-996D-FAE36135FA00}

[Object:EnglishToForeignStemmer]
ProgID = LR.LexRefEnglishStemmer.1.0
Slave Objects = EnglishToForeign

[Object:EnglishToForeign]
Build Object = BuildEnglishToForeign
Name = English to Foreign Bilinguals
ProgID = LR.LexRefBilingualService.1.0

[Object:XMLToRTF]
ProgID = LR.LexRefSampleObject.1.0

[Build Object:BuildEnglishToForeign]
ProgID = LR.LexRefBilingualBuildService.1.0
MDB File Path = C:\BILINGUALS10\CONTENTBUILD\TEST.MDB
ITS File Path = C:\BILINGUALS10\CONTENTBUILD\TESTENFR.ITS
Project File Path = C:\BILINGUALS10\CONTENTBUILD\TEST.ITP
SQL Query = SELECT field1, field2 FROM Hw_enfr;
Index Name = TESTWW

Using the ITS file

An ITS file stores certain attributes of your service, such as the service's filename and GUID, once it is built. An empty ITS file is needed as an input file for the build process. When the service is built, this file is automatically altered so that it can be installed with the rest of your service files. An empty .ITS file (SAMPLE.ITS) is provided to serve this purpose. Note, however, that this sample ITS file is not re-usable, so you will need to copy the file to the folder from which you are building your service. If you want to rebuild your service or create another service, you will need to use a new copy of the empty ITS file at build time.

Running BuildLexRefService.EXE

Once the XML file, INI file, ITS file, and DLL files have been created, you may run BuildLexRefService.EXE.

Place all files in the same folder, open the command prompt, and type "buildlexrefservice [path]" where [path] is the full path to your INI file.

Creating a Windows Installer Setup Package

The final step in creating a translation service is to construct a Microsoft Windows® Installer-based setup package containing the files and settings for the service.

Reference information about Windows Installer can be found in the Windows Installer SDK, which is available as part of the Microsoft Platform SDK.

Your setup package must install all of the files used by your service, and must also register all of the DLL files that are installed. Also, you should add the following information to the Registry table and PublishComponent table of the setup package:

**Note   **Some of the GUIDs listed below are distinct even though they only differ by a single digit.

**Note   **Anywhere a GUID is not explicitly described, it should be used exactly as in the sample MSM provided.

{FAD573D7-E564-11D3-8F5D-00C04F9CF4A0} is the main GUID used during building from the Attributes section of the INI file.

Table 3. Registry

Key Name Value
SOFTWARE\Microsoft\Microsoft Reference\Bilinguals 1.0\{FAD573D7-E564-11D3-8F5D-00C04F9CF4A0} Loader ProgID LR.LexRefBilingualServiceAttribute.1.0
SOFTWARE\Microsoft\Microsoft Reference\Bilinguals 1.0\{FAD573D7-E564-11D3-8F5D-00C04F9CF4A0}     Sample Translation Service
SOFTWARE\Microsoft\Microsoft Reference\Bilinguals 1.0\{FAD573D7-E564-11D3-8F5D-00C04F9CF4A0} Locator [INSTALLDIR]sample.ITS!Attributes

These three rows of the table tell the bilingual service where to find the ITS file with the content service attributes.

Table 4. PublishComponent

ComponentID Qualifier Component_ AppData Feature_
{8E6ABE11-1B9A-11D4-8F62-00C04F9CF4AC} 1033/1033 SAMPLE.FAD573D7_E564_11D3_8F5D_00C04F9CF4AC {FAD573D7-E564-11D3-8F5D-00C04F9CF4A0} YOUR_MSI_FEATURE

This row tells Word about the extra content service. The Component_ column contains the component ID of your package, and the location IDs (LCID) in the Qualifier column determine which languages show in the dropdown with available translation services.

For additional information, see the sample MSM and MSI files provided.

Once the setup package is created and installed on a computer with Word 2002, the new translation service will become available from the drop-down menu in the Translation Task Pane. (Choose Tools | Language | Translate from the Word 2002 menu bar.)