MSI Localizing a Windows Installer Package

What is Localization? (MSI Localizing a Windows Installer Package )

MSI Localizing a Windows Installer Package ,the process of making a software product linguistically and culturally appropriate for use in a different country or region and its language is called localization. This helps cut costs and speeds up the localization process. In addition to adapting screen information and documentation for international use, Help files, scenarios, templates, models, and sample files should also be a part of your localization planning.  Language is not the only relevant factor to consider when you localize an interface. Several countries can share a common language but have different conventions for expressing information. In addition, some countries can share a language but use a different keyboard convention. A subtler factor to consider when preparing software for international markets is cultural differences. For example, users in the U.S. may recognize a rounded mailbox with a flag on the side as an icon for a mail program, but this image may not be recognized by users in other countries. Sounds and their associated meanings may also vary from country to country.

A major aspect of localizing an interface is translating the text used by the software in its title bars, menus and other controls, messages, and some registry entries. To make localization easier, interface text should be stored as resources in your application’s resource file rather than including it in the source code of the application. Also to the menu commands that your application stores in the system registry for its file types should be translated. Translation does not always result in one-to-one correspondence. A single word in English can have multiple translations in another language. Adjectives and articles sometimes change spelling according to the gender of the nouns they modify. Therefore, be careful when re-using a text string in multiple places. Similarly, several English words may have only a single meaning in another language. This is particularly important to remember while creating keywords for an application’s Help index.

How to go about Localization?

The following steps should be followed while localizing a Windows Installer package: –

Prepare for localization when authoring the original installation package. Design the layout of localized files such that different language versions can safely coexist when installed on the user’s computer. Organize files requiring localization into separate components and install these files into separate directories.

Always set the code page of the database being localized prior to adding any localized data

Import a localized Error table and ActionText table into the database. You may import these tables using Msidb.exe or MsiDatabaseImport.

Modify any of the other localizable columns in the database using a table editor or SQL queries.

Set the ProductLanguage property in the Property table to the LANGID of the database. When authoring a package as language neutral, set the ProductLanguage property to 0 and use the MS Shell Dlg font as the text style for all authored dialog boxes. Because some fonts do not support all of the character sets, you can ensure that the text is correctly displayed on all localized versions of the operating system by using this font.

Set the language field of the Template Summary property to reflect the LANGID of the database.

If the text strings in the summary information stream are localized, set the Codepage Summary property to the code page.

Set the ProductCode property in the Property table and set the package code in the Revision Number Summary property to a new package code. A localized product is considered a different product. For example, the German and English versions of an application are considered two different products and must have different product codes.

Localization may require modifying resources that already exist or the addition of new resources such as files or registry keys. Check to be sure that the component code is changed for every existing component that has had a new resource added. Other modifications may also require changes to a component’s code.

Be sure to save localization and other changes to the database by saving the package with the editing tool or by calling MsiDatabaseCommit.

Code Page Handling (MSI Localizing a Windows Installer Package )

If you localize a Windows Installer package, it may involve modifying information in database tables, exporting the tables to ANSI text archive files, and then importing the archive files into the database that is being localized. You can also add localization changes to a database by using a database table editor or the Database Functions. It is important to set the code page of the database that is being localized before you make any localization changes to the database. Do not set the code page of the database after localizing the database, because this can corrupt extended characters. The recommended approach for handling code pages is to author a neutral database that only contains characters that can be translated into any code page. If you add localization information with database archive files, you can use MsiDatabaseExport to export tables from a database that contains localization changes to ANSI text archive files, and then import these into the database being localized with MsiDatabaseImport. The code page of an exported archive file is always the same as its parent database. The code pages of an imported file and the database that is receiving the file must be identical, or at least one of the two code pages must be neutral.  If you add localization information with a text editor or the Database Functions be careful to only pass string parameters to the Windows Installer API that uses the code page of the database that is being localized. If a string parameter contains characters not represented by the code page of the database, an error occurs when calling MsiDatabaseCommit. If one package is used to install multiple language versions of a product, the transform that is used to localize strings can also change the code page of the database.

Code Page Handling of Imported and Exported Tables

You can add localization information to an installation database by importing and exporting ASCII text archive files using MsiDatabaseExport and MsiDatabaseImport. Because the database string pool uses an ANSI code page, both the database and exported Text Archive Files have code pages.

When a Text Archive File is exported from a database, the code page of the archive file is the same as the parent database.

ASCII Text Archive Files

The ASCII Text Archive Files exported by MsiDatabaseExport are explained in the following format:

The names of the table columns are written on the first line.

The column formats are written on the second line.

If the table contains only ASCII data, the third line of the text file is the table name followed by a list of the primary keys.

If the table contains non-ASCII data and the database is stamped with a numeric code page, the code page number appears at the beginning of the third line.

If the database contains non-ASCII data, but the database is not stamped with the numeric code page, the current system code page number is written at the beginning of the third line.

The remaining lines of the text file are the data in the specified code page.

If a table contains streams, MsiDatabaseExport exports each stream in the table to a separate file.

Neutral and Non-Neutral Code Pages

You can facilitate localization by starting with a database that has a neutral code page:

• A blank database has a neutral code page.
• A database that does not contain extended characters that require a code page to be represented in ASCII has a neutral code page.

Neutral and non-neutral code pages have the following characteristics:

If a Text Archive File with a non-neutral code page is imported into a database that has a different non-neutral code page, the Installer returns an error when MsiDatabaseImport is called.

A Text Archive File that has a neutral code page can be imported into a database that has any code page.

A Text Archive File that has any code page can be imported into a database that has a neutral code page.

Importing a Text Archive File into a database with a neutral code page sets the code page of the database to the archive file code page. All archive files subsequently imported into the database must have the same code page as the first file.

The Text Archive Files that are exported by MsiDatabaseExport can be used with version control systems. Use the Database Functions or a database table editor to edit the database.

Code Page Handling of Parameter Strings

You can add localization information to an installation database by using a database table editor such as Orca that is provided with the Windows Installer SDK, or by calling the Database Functions from an application. Be careful to only pass string parameters that use the code page of the database that is being localized. If a string parameter contains characters that cannot be represented by the code page of the database, the Installer returns an error when calling MsiDatabaseImport.

Adding Localization Information to a Database

When you add localization information to a database, the code page of the database must be supported by the operating system. It does not have to be the current code page of the system. IsValidCodePage must return TRUE for the database code page. Because the system converts ANSI strings to Unicode, there is an error if the current user code page is not the same as the database code page.

The following procedure shows you how to store the localization data.

Set the code page of the database to the code page of the localized string.

Convert the ANSI string to Unicode by using the MultiByteToWideChar function, and specify the code page of the localized data.

Call the Unicode version of the Windows Installer API by using the Unicode string to add the localized data.

Commit the localization changes to the database by using MsiDatabaseCommit.

Creating a Database with a Neutral Code Page

The recommended approach for handling code pages is to author a neutral base database that only contains characters that can be translated into any code page. The database may then be set to the code page of the localization and the localization information can be added as described in the previous section. To author a neutral database, avoid extended characters that do not belong to the ASCII character set and therefore require a special code page. For example, the copyright sign, ©, and the registered trademark sign, ®, are not ASCII characters, and require a special ANSI code page for proper display. Instead use (c) and (r), because these characters can be translated or transformed to the symbols for the English-language version. This neutral database can then be localized by setting its code page and adding localization information by table editing or by importing text archive files.

Localizing the Error and ActionText Tables: (MSI Localizing a Windows Installer Package )

The Platform SDK includes localized resource strings, localized Error tables, and localized ActionText tables for the languages listed in the following table. The LANGIDs marked with asterisks indicate that the resource strings are stored as the base language and so can be used with all dialects of that language.

Determining an Installation Database’s Code Page (MSI Localizing a Windows Installer Package )

To determine the code page of a database, call MsiDatabaseExport with hDatabase set to the handle of the database and szTableName set to _ForceCodepage. This exports a text file with an .IDT extension. The first two lines of this file are blank. The third line is the ANSI code page number, followed by a tab, followed by the name _ForceCodepage.

Localizing the Language Displayed by Dialogs

The Windows Installer service uses the current user’s language in all dialogs until a Windows Installer package is opened. On Windows 2000 and later operating systems, the Windows Installer determines this by using GetUserDefaultUILanguage. On operating systems earlier than Windows 2000, it uses GetUserDefaultLangID. When a Windows Installer package is opened, the installer displays dialogs using the package’s language as specified by the Template Summary Property.

Setting the Code Page of a Database (MSI Localizing a Windows Installer Package )

Always set the code page of a database prior to adding any localization information. Attempting to set the code page after entering data into the database is not recommended because this could corrupt extended characters. Localization can be greatly facilitated by starting with a database that is code page neutral. You may set the code page of a blank database, or a database with a neutral code page, by importing a text archive file having a non-neutral code page with MsiDatabaseImport. This sets the code page of the database to the imported file’s code page. All archive files subsequently imported into the database must then have the same code page as the first file. If a text archive file is exported from a database, the code page of the archive file is the same as the parent database. The code page of any database may be set to a specified numeric code page by using MsiDatabaseImport to import a text archive file with the following format: Two blank lines; followed by a line containing the numeric code page, a tab delimiter, and the exact string: _ForceCodepage. Note that with Windows NT or Windows 2000, this translates all of the strings in the database to the code page of _ForceCodepage. This may be intended when localizing an existing database and translating all non-neutral strings to the new code page. However, this causes an error if the database contains non-neutral strings that are not to be translated.

Preparing a Windows Installer Package for Localization

Localization of a Windows Installer package into multiple languages can be greatly facilitated by doing the following:

Author a base installation database that is code page neutral. The code page of the localized database can then be set by importing a text archive table with a non-neutral code page into the base database.

Organize files requiring localization into separate components and install these files into separate directories. This ensures that two localized packages never install identically named files into the same directory.

For example, a worldwide application using the following resources may have three components.

The files that need to be localized may be installed into the following directory locations:

[ProgramFilesFolder]\World\worldwide.exe

[ProgramFilesFolder]\World\English\engui.dll

[ProgramFilesFolder]\World\English\readme.txt

[ProgramFilesFolder]\World\French\fraui.dll

[ProgramFilesFolder]\World\French\readme.txt

Application Packaging Demo Video For Your Preview