InstallGuide.doc

v2.5 Installation Customization Guide For Language Translations and External Applications

August 27th, 2003
Rev 2

Contents

v2.5 Installation Customization Guide For Language Translations and External Applications  August 27th, 2003 Rev 2              i

Contents              ii

1. Overview              1

2. Performing a Language Translation of the Program              2

3. Changing the Program System Defaults              8

4. Adding API Program Modules              8

v2.11 Installation Customization Guide, March 10th, 2003              7

1.  Overview

In v2.11, Windows Installer installation program extensions were added to provide the ability to create a customized installation of ParaLogix or any derivative private label product.

The installation extensions allow you to add files outside of the Windows Installer .CAB file that are referred to as “externalized program files”. These files could be software components (.DLL files) that were modified or added, as well as translated on-line help documentation components and other files external to the program.

These externalized files are searched for and installed from specific directories on the install disk image. Regardless of which version of the program you have, the standard install disk image top level directory always contains the ENU and Lang Independent directories and the SetupParaLogix.ini file. You are concerned with these folders and this file to perform your customization.

There are several reasons why you might want to customize the installation:

1)       Provide a new language translation

2)       Update or replace the on-line Tutorial

3)       Update or replace the Readme and Release Notes files.

4)       Add or remove custom program modules

5)       Change the system defaults when the program is installed
 

2. 
Performing a Language Translation of the Program

A full language translation of the program requires translating the program prompt, menu and dialog box text, referred to in Windows terminology as “resources”. In addition, the on-line documentation (.hlp) files must be translated. If you want to provide the option to the user to install a new language, you must edit the SetupParaLogix.ini file (found in the top level installation directory). This will notify the installation program that a new language option is to be displayed on the language selection page (in the drop down list) during installation. The possible languages to be displayed in the list are Chinese, Czech, Finnish, French, German, Italian, Japanese, Polish, Spanish and Swedish. You can only install one of these languages because the Windows Installer script is pre-built with these possible options so that the installation prompts themselves will be displayed in the chosen language. As long as the operating system is already set up for the target language, the installation will display the prompts in the target language. Note that there are a couple of installation screens that still will appear in English and are not translatable, but this was deemed a minor deficiency and will be addressed in a future release. 

The SetupParaLogix.ini file looks like this.

; Format of 'Supported Languages' is as follows:

;   Language Name = Language ID, Directory in which language translation exists

;

; Notes:

;   Only the following languages are supported.  The corresponding directory must exist in order for

;   the language install to work properly.  The directory and it's corresponding sub-directories

;   will be copied verbatim to the target directory indicated during the install process.

;

;   Language Name                        Directory

;   -------------                                          ---------

;   Chinese (PRC)                             CHS

;   Czech                                                   CZE

;   English (United States)                   ENU

;   Finnish                                                 FIN

;   French (Standard)                         FRA

;   German (Standard)                         DEU

;   Italian (Standard)                        ITA

;   Japanese                                                JPN

;   Polish                                                  POL

;   Spanish (Traditional Sort)                ESP

;   Swedish                                                 SWE

;

;   You can also have a 'Lang Independent' directory for language independent files.

;

;   To properly support uninstall, you should create a DelTranslatedFiles.bat for each

;   language specific directory supplied and DelLangIndFiles.bat if 'Lang Independent' is

;   supplied.  Typically the contents of these files looks like =>

;

;               del /Q Adx2dRes.dll

;

;   To properly support registering and un-registering of COM based DLLs, you can also optionally

;   supply RegTranslatedFiles.bat and UnRegTranslatedFiles.bat for language specific files.

;   Likewise you can supply RegLangIndFiles.bat and UnRegLangIndFiles.bat for language independent

;   files.  Typically the register batch file would contain something as follows =>

;

;               regsvr32 /s /c Adx2d.dll

;

;   Likewise the un-register batch file would contain something as follows =>

;

;               regsvr32 /s /u /c Adx2d.dll

;

;   If these batch files are supplied, then the install program will take care of registering,

;   un-registering and removing these files accordingly.

;

[Supported Languages]

;Chinese (PRC) = 2052

;Czech = 1029

English (United States) = 1033

;Finnish = 1035

;French (Standard) = 1036

;German (Standard) = 1031

;Italian (Standard) = 1040

;Japanese = 1041

;Polish = 1045

;Spanish (Traditional Sort) = 1034

;Swedish = 1053

[Default Language]

English
 

You need to edit this file by going to the [Supported Languages] section and removing the comment semicolon (;) for the language you wish to install. In the sample SetupParaLogix.ini file above, the only uncommented language is English, so that is the only choice you see on the language selection page in the drop-down list when installing. If you wish to have a language other than English appear as the default choice on the installation language selection page, you must also go to the [Default Language] section and replace the word “English” with the desired language word, using the appropriate word from the Supported Languages list.

Once you have edited the SetupParaLogix.ini file, you need to create the language directory(s) for the language(s) you installed, because the installation program will look for files in this directory. The language directory name consists of three letters, with the choices being as follows:  

CHS (Chinese)              CZE (Czech)              DEU (German)              ENU (English)
ESP (Spanish)              FIN (Finnish)              FRA (French)              ITA (Italian)
JPN (Japan)                            POL (Polish)              SWE (Swedish)

Now, let’s go through the process of adding a language translation (for instance, French), making it the default, step by step.

1.        Edit the SetupParaLogix.ini file and uncomment the line “;French (Standard) = 1036” line by removing the semicolon (;). Replace the word “English” under the [Default Language] section with  “French”. Assuming you are editing the sample SetupParaLogix.ini file described above, the end of the file now looks like this:
.
.
[Supported Languages]

;Chinese (PRC) = 2052

;Czech = 1029

English (United States) = 1033

;Finnish = 1035

French (Standard) = 1036

;German (Standard) = 1031

;Italian (Standard) = 1040

;Japanese = 1041

;Polish = 1045

;Spanish (Traditional Sort) = 1034

;Swedish = 1053

[Default Language]
French
 

2. Create a directory named FRA at the top level installation directory (at the same level as the ENU directory).
3. Copy the entire contents of the ENU directory to the new FRA directory. This ensures that all program files that could be translated exist in the new directory, at least in English. The new directory should now contain the following files and folders:

4. Translate the Program
   To completely translate the program prompts, menus and dialog box text, you need to translate all of the .DLL and .INI files, otherwise some things will display in English. Note that the number and names of these files may vary in different program versions.
   
   To translate the .DLL program files, you can use a commercially available tool, such as Alchemy Catalyst, to extract the text from these files and recreate the .DLL files with the edited text. Alchemy Catalyst is a good tool in that it allows you to reposition the controls on the dialog boxes, if necessary.
   
   The .INI files are text-based and can be edited with any text editor, such as Notepad. Note that you should only translate the Toolbars section. In the ParaLogix.ini and ParaLogixDefaults.ini files. Be sure that the toolbar names you use in these files match the in gafres.dll and cadres.dll.
   
   Toolbar names found in gafres.dll:
   
   String ID              Text
   258              Standard
   263              Diagnostics
   
   Toolbar names found in cadres.dll:
   String ID              Text
   312              Assembly
   313              Viewing
   314              Display Mode
   
   Do not delete any .DLL or .INI files or the program will not function properly.
5. Translate On-Line Help (optional)
   To translate on-line help, you must go to the hlp directory and replace all of the .hlp files with the translated versions.  To do this, you either need a tool that can directly edit .hlp files or Microsoft Word 97 (or higher) to edit the source .doc files. In the case of the latter, you will need a tool such as Robohelp to properly re-generate the .hlp files. A3DS can supply both the .doc files and related Robohelp 7.0 project files upon request.
   
   You should not delete any files found in the hlp directory or you will get errors when using the program on-line help mechanism.
6. Translate the On-Line Tutorial (optional)
   If you want to translate the on-line tutorial, you will find the tutorial .pdf files in the Tutorial directory. To translate these, you will need the Microsoft Word .doc source files. These can be supplied by A3DS upon request.
   
   If desired, you can completely replace the Tutorial directory with your own, including the directory structure underneath. The installation program will install the entire contents of the Tutorial directory in a directory called Tutorial in the program directory.
    
   Note that if you change the file names for the tutorial or add or delete files, you must update the Tutorial.hlp file.
7. Translate the Read Me and Release Notes File (optional)
   The Readme.txt file is a simple text file and easily translated with a text editor. You should not delete this file, because the installation program provides the option to read this file after installation is complete.
   
   The ReleaseNotes.doc file is a Microsoft Word 97 file. Once translated, if you wish to create an Adobe .PDF file, you need to use Adobe Acrobat 4.0x. If desired, you can delete these files or provide files with different names without consequences to program operation.

8.       The last thing to do is to edit the special batch file that will later delete files installed from these directories when uninstalling the program. This file is called DelTranslatedFiles.bat and exists a...