One of the most important capabilities provided by SharpSetup compared to using plain WiX is the ability to create installers that allow user to easily choose natural language of the user interface. This article will focus on how to create translations for SharpSetup installer.
Previous articles mentioned that SharpSetup installer consists of several projects. This division will have influence on how translation files need to be prepared. Let us identify components that require translation:
- bootstrapper - localizable strings can be found on the language selection dialog, unpacking progress dialog and various messages like cancellation confirmation, prerequisites missing message, etc.
- MSI package - this part of the installer is responsible for storing feature names and some of the messages sent to GUI.
- main GUI - this is the part which will need most translation work. All installer steps will have to be translated along with any message boxes that you may use in your code.
- SharpSetup library - some of the strings visible in your installer interface come from SharpSetup library itself. You will have to create satellite assemblies for SharpSetup.dll to fully translate your installer.
Now, let's have a closer look at each of these elements in detail.
As you already know during build process all resources from IntermediateBootstrapper are copied to main bootstrapper. This includes version information, main bootstrapper configuration file (mainconfig.txt) but also translations. Translations are stored in resources with identifier IDR_TRANSLATION_OVERRIDES. By default (ie. just after SharpSetup solution is created) there is only one instance of this resource for Neutral language. If you want to add translation for culture en-GB follow these steps:
- switch to Resource View (for example by double-clicking on IntermediateBootstrapper.rc file in Solution Explorer) and expand "CONFIG" node,
- right-click on IDR_TRANSLATION_OVERRIDES [Neutral] node and click Insert Copy... menu item,
- select appropriate language - in our case English (United Kingdom) - and click OK,
- in Properties Window (if not visible press F4 to open) change filename to translation_overrides.en-GB.txt,
- save resources by pressing Ctrl+S.
After you follow these steps a new file named translation_overrides.en-GB.txt will be created in your project. Note that this file has to be encoded as UTF-16LE files (codepage 1200 in Advanced save options dialog).
Now we can move on to the translation process itself. Each line in translation_overrides.en-GB.txt file corresponds to one string in bootstrapper user interface. Lines have the following format:
identifier can be in one of three groups:
- culture identifier - eg. en-US, en-GB, fr-FR, de-DE, pl-PL, etc. Translation would look like this:
- UI element identifiers which by default have the following translation in English:
- LS_CAPTION:Select language
- LS_HEADER:Please select preferred language of the installation program:
- PD_CAPTION:Preparing installation
- PD_HEADER:Please wait...
- PD_CANCEL_QUESTION:Are you sure you want to abort installation?
- PREREQ_MISSING_GENERIC:This program requires %s to be installed on this computer. Setup cannot continue.
- PREREG_MISSING_CAPTION:Prerequisite missing
- prerequisite names that will be substituted for %s in PREREQ_MISSING_GENERIC message, eg.:
The complete list of supported prerequisites: dotnet20, dotnet20sp1, dotnet20sp2, dotnet30, dotnet30sp1, dotnet30sp2, dotnet35, dotnet35sp1, msi31, msi40, msi45, msi50.
- PREREQ_NAME_dotnet35sp1:.NET Framework 3.5 with Service Pack 1
- PREREQ_NAME_msi31:Windows Installer 3.1
Package project needs to be translated to get localized feature names, feature descriptions, installation progress messages, etc. Translating core installation package is done the same way as for every other WiX package. To add a new language you should:
- add a file named after culture code with wxl extension to your Package project (eg. pl-PL.wxl for translation into Polish),
- set encoding to UTF-8 and consequently a Codepage attribute of WiXLocalization element to 65001,
- set Culture attribute to desired culture code,
- add translation of three strings required by SharpSetup: LANGUAGE (windows code for given culture, eg. for Polish it is 1045), CULTURE (culture code) and APPNAME (localized application name, may be the same for all languages).
To simplify these tasks template translation file is available with SharpSetup. You can right-click on Package project -> Add -> New Item..., select Sample WiX/SharpSetup Localization File, name it after culture code (eg. pl-PL.wxl) and press OK - all other steps will be executed automatically.
To translate majority of your installer GUI you can use the same procedures you use to translate any other WinForms application. In short: open designer for given dialog or control, change Language property and start translating UI inside Visual Studio designer. SharpSetup will take care of packaging translations for you at build time.
Some of the controls included with SharpSetup have user visible strings that you may want to translate. For that you will need to create satellite assemblies for SharpSetup.dll containing resources that you want to have translated. Unfortunately this process is somewhat complicated and looks like this:
- identify resource group (eg. SharpSetup.UI.Controls.DestinationPath) and resource name (eg. btnChange.Text) that you want to have translated using tool such as .NET Reflector (open SharpSetup.dll file),
- in Translation project right-click on folder named after appropriate culture code (you can create it if necessary) -> Add -> New Item..., select General -> Resources File and name it after resource group with resx extension (in our case SharpSetup.UI.Controls.DestinationPath.resx),
- open the newly created file and add new resource that you want translated (eg. btnChange.Text),
- change Build Action for newly created file from Embedded Resource to ResourceOverride, change Custom Tool to empty string and delete .Designer.cs file.
This process will be automated in future versions of SharpSetup.
If you want to test how your translation works without rebuilding whole installer you can to to Gui project properties, Debug tab and type culture code (eg. en-GB) in command line arguments text box. When you run main GUI from within Visual Studio by pressing F5 or Ctrl+F5 the specified culture will be used for UI.
This article should contain all information necessary to create full translation of SharpSetup based installer. As usual, if you have any questions, suggestions for improvements or other comments contact me directly.
Previous in series: SharpSetup bootstrappers
Next in series: Using installer dialogs