WiX Tutorial

Thank you for your interest in the localization project.

The bulk of the work, the actual development to allow WiX 2.0 and later 3.0 to support easy localization was done by Bob Arnson. My task is to co-ordinate you folks participating in the actual translation of the strings that will appear in localized installation packages.

Languages supported

The following table is based on the languages originally included in the Windows Installer SDK. The list of languages is not exhaustive at all: feel free to suggest any other language if you are willing to do the localization.

Language	Language & Country	Files	v2 status	v3 UI	v3 Extensions
Afrikaans	af-za		in progress	open	open
Arabic	ar-ar		released	in progress	open
Basque	eu-es	ActionError.eu-es.xml	open	open	open
Catalan	ca-es	ActionError.ca-es.xml	open	open	open
Chinese, simplified	zh-cn		released	open	open
Chinese, traditional	zh-tw	WixUI_zh-tw.wxl	released	finished	open
Croatian	hr-hr	ActionError.hr-hr.xml	open	open	open
Czech	cs-cz		released	released	open
Danish	da-dk	WixUI_da-dk.wxl	released	finished	open
Dutch	nl-nl		released	released	open
English	en-us	WixUI_en-us.wxl*	released	released	released
Esperanto	eo-eo		in progress	in progress	open
Estonian	et-ee	ActionError.et-ee.xml	open	open	open
Finnish	fi-fi		released	open	open
French	fr-fr		released	released	open
German	de-de	WixExt_de-de.wxl	released	released	finished
Greek	el-gr		released	open	open
Hebrew	iw-il		released	in progress	open
Hungarian	hu-hu	WixUI_hu-hu.wxl*	released	released	open
Italian	it-it		released	released	open
Japanese	ja-jp		released	released	open
Korean	ko-kr		released	open	open
Latvian	lv-lv	ActionError.lv-lv.xml	open	open	open
Lithuanian	lt-lt	ActionError.lt-lt.xml	open	open	open
Malay	my-ms	WixUI_my-ms.wxl	in progress	open	open
Norwegian	no-no		released	open	open
Polish	pl-pl		released	released	open
Portuguese (Brazil)	pt-br		released	open	open
Portuguese (Portugal)	pt-pt		released	open	open
Romanian	ro-ro	WixUI_ro-ro.wxl	finished	open	open
Russian	ru-ru		released	released	open
Slovakian	sk-sk	WixUI_sk-sk.wxl	finished	open	open
Slovenian	sl-si	ActionError.sl-si.xml	open	open	open
Spanish	es-es	WixExt_es-es.zip	released	released	in progress
Swedish	sv-se		released	open	open
Thai	th-th	ActionError.th-th.xml	open	open	open
Turkish	tr-tr		released	open	open
Ukrainian	uk-ua		released	released	open
Vietnamese	vi-vn	ActionError.vi-vn.xml	open	open	open

* We also offer alternative, cleaner, more fluent, easier-to-understand translations instead of some localization files in the released package. They differ in some places from the usual wording used by Microsoft in their installations but, in our personal opinion, they use simpler and better language. You are completely free to check them out and decide which one you want to use in your install packages.

The legend for the Status column:

open: still unaccounted for, ready to be picked up;
in progress: somebody has already started working on it;
halted: somebody has already started working on it but I haven't seen any progress lately; if you're willing to contribute, I can direct you to the original translator and you can ask him whether you both could co-operate or, if she or he doesn't have the time or interest any more, you could take it over;
outdated: we have a translated localization file but there were some recent changes in WixUi that would necessitate some reworking of these files. The original translators were contacted but no reply came in yet. If you're willing to contribute, I can direct you to the original translator and you can ask him whether you both could co-operate or, if she or he doesn't have the time or interest any more, you could take it over;
finished: the localization file is already translated but it can't yet appear in the release because either the translator hasn't yet signed the required assignment agreement with Microsoft or the process is still under way; but this language will probably appear in a coming release all right. Until then, you can download them from here as a user-to-user contribution but if you happen to know the language and find some errors in the translation, do report it back to me so that the original translator can be contacted and the best translation found;
released: the localization has been done, the legal agreement has been signed and processed and the file is in the released package (but note that sometimes it might take some time for it to appear in the stable version on the main download page, so you might need to look for it in the weekly releases.)

Does my language need to be localized?

If it appears as released in the version 3 Status column, it's already in the toolset, just use it, there is nothing else to do. If it appears there as finished, you will find the link in the File column to the language file you can download and use it until the language officially appears in the toolset. If the version 3 status is in progress, you can still hope it will be finished soon...

If you don't see any reference but open for version 3, check the previous column. If it was released in version 2, you can download the source and find the .wxl file inside. If the version 2 status says finished, the file will be right here for you to download. In both cases, the old version has to be updated in order to work with version 3. We did contact the original translator but no reply came.

If the language is still open for both versions, nobody has started to work on it yet. The details of what to do are outlined in the following section.

If you feel you are willing to contribute or have any question regarding the project, contact me (G´bor is the name, or Gabriel in English, the address can be found at the bottom of the page). Tell me what language you're interested in.

What about extensions?

There are more localizable strings in WiX than just the user interface. Various extension modules often have their own strings. They should be localized as well. Either you are the original translator of any language, or somebody willing to contribute, the original English file WixExt_en-us.wxl can be used to prepare the translated version. The process is the same as with the UI strings.

First the legalese... Your translation will become part of the WiX toolset, an open source project with the copyright held by Microsoft. This status requires an assignment agreement to be signed before your work can be legally incorporated into the toolset, be it source code or human language translation. Please, see Rob's blog entry for details.

What to do

First of all: please, note that we need the translations as UTF-8 coded text files (for the sake of uniformity, all files are in this format, even those of English and other Western European languages that could easily get away with the simpler ANSI coding). To contribute, you have to be able to work with this format. Actually, it's not really important what you use during your work but the end result must conform to this rather simple requirement. No Word documents or RTF files, please. Notepad is perfectly capable of creating such text files, if you have no better alternative at hand.

To start, get WixUI_en-us.wxl from the current release of WiX, this is the original file that has to be localized to your language. For many languages, you don't have to start from scratch, another file already contains a significant part of the strings translated: ActionError.xx-xx contains the action text and error messages. As this is the translation that comes with localized versions of Windows, it is hopefully error-free and familiar to users but some checks would be required to make sure they are perfectly in sync with the English version, especially because we did introduce wording simplifications in the English version and those should preferably be reflected in the translated texts, too. Also note that there are a couple of new error messages not yet translated: 1731-1732, 1935-1938.

If the language was not in the original package, you'll have to provide a translation yourself. The file has two sections: ProgressText and Error strings. In both sections the tag has an identification attribute (Action and Id), those shouldn't be translated or modified in any way. The actual tag contents and, wherever present, the Template attribute of ProgressText are the ones to localize. Please, make sure you keep the quotes, brackets and other codes intact (but, of course, you can move them inside the text as the rules of your language dictate).

<String Id="ProgressTextCostFinalize" Overridable="yes">Computing space requirements</String>
<String Id="ProgressTextCostInitialize" Overridable="yes">Computing space requirements</String>
<String Id="ProgressTextAllocateRegistrySpace" Template="Free space: [1]" Overridable="yes">Allocating registry space</String>
...
<String Id="Error1316">A network error occurred while attempting to read from the file: [2]</String>
<String Id="Error1317">An error occurred while attempting to create the directory: [2]</String>

The remaining strings are used in the user interface. Again, make sure you don't modify the Id attribute. Also keep the property values (in [] brackets) and font references (in {} braces) intact: these will be used as they are now by the Installer, no localization is necessary. You can move the property references inside your text into the location required by your language. If you need to use the characters &, < or > in the text, take care to use the usual XML entities &, &gt; or < instead. Do use the ampersand, put it into the position normally used and expected by your users to facilitate keyboard navigation later in the finished installers.

<String Id="CustomizeDlg_Title" Overridable="yes">[ProductName]</String>
<String Id="CustomizeDlgTree" Overridable="yes">Tree of selections</String>
<String Id="CustomizeDlgBrowse" Overridable="yes">B&amp;rowse...</String>
<String Id="CustomizeDlgReset" Overridable="yes">Re&amp;set</String>
<String Id="ExitDialogTitle" Overridable="yes">{\WixUI_Font_Bigger}Completing the [ProductName] Setup Wizard</String>

Add leading spaces to the first four items if your language requires a space between number and unit.

There are bitmap references in each dialog, those refer to identifiers rather than text read by the user, those should be left unchanged, too.

As the WixUI user interface is rather close to the standard one, you might want to check out some existing localized installers in order to stay compatible with the users' expectations.

And now the fun stuff...

One of our translators and contributors, Jan Široky created a nice little utility to make it real easy to bring a v2 translation up to v3. You provide it with a v3 file (the English one, for instance) and the older v2 translation of your language. The program will create three files in return: first, a full .wxl file with all previously existing translated strings picked up from the earlier version; second, a TODO.wxl with the items still to be translated and third, for reference, a simple text file with all the strings in the localization file.

When you're finished with the translation of the items in the TODO.wxl file, you can run the utility again to merge the new items with the existing ones. Again, the first file selected will be the v3 file, choose TODO.wxl as the second, remember to specify the appropriate culture and the final localization file will be created automatically.

tfeL ot thgiR

The question of right-to-left languages came up recently. Although v2 had localization support for Arabic and Hebrew, as you can see from the table above, those language files are not yet updated to v3. And even if they were, the user interface doesn't seem to comply with RTL requirements. The texts themselves might be mirrored but not the actual layout of the UI dialogs.

In an attempt to bring RTL functionality to WiX, I wrote a simple .NET application to process the WixUI source files. It mirrors the textual elements (bitmaps, icons and lines are left untouched) and decorates them with the RightToLeft and RightAligned attributes where required. The modified UI can then be assembled again.

As I don't speak or even read any of the RTL languages concerned, I ask for your help and co-operation to check out and correct the modified package wherever necessary.

The primary goal is very simple: apart from changing the Language attribute as usual, the only source code change would be the reference to a modified UI dialog set:

<UIRef Id="WixUI_RTL_Mondo" />

But to arrive there, we have a couple of things to do. In the package, you'll find different sets of files, let's concentrate on the modified UI package first (WinUI_RTL folder). The are two sets of source files: the UI dialog sets (WixUI_RTL_*.wxs files) and the actual dialog descriptions (the rest).

What we will now do is the older, v2 way of creating the user interface—later, when everything is ready and done, it can be compiled into the v3 style WixUI extension module. But for now, we have a couple of files to build. First, let's compile the dialog sets:

candle.exe WixUI_RTL_Advanced.wxs WixUI_RTL_FeatureTree.wxs WixUI_RTL_InstallDir.wxs WixUI_RTL_Minimal.wxs WixUI_RTL_Mondo.wxs

Then we compile all the other dialog source files as well. We also have to provide the values of some preprocessor variables:

candle.exe -dlicenseRtf=License.rtf -dbannerBmp=Bitmaps/bannrbmp.bmp -ddialogBmp=Bitmaps/dlgbmp.bmp -dexclamationIco=Bitmaps/exclamic.ico
  -dinfoIco=Bitmaps/info.ico -dnewIco=Bitmaps/New.ico -dupIco=Bitmaps/Up.ico -dprinteulaDll=WixCA.dll
  AdvancedWelcomeEulaDlg_RTL.wxs ... WelcomeEulaDlg_RTL.wxs

Finally, we use the library tool, Lit to create WiX libraries of the modified dialog sets:

lit.exe -out WixUI_RTL_Advanced.wixlib WixUI_RTL_Advanced.wixobj AdvancedWelcomeEulaDlg_RTL.wixobj ... WelcomeEulaDlg_RTL.wixobj
lit.exe -out WixUI_RTL_FeatureTree.wixlib WixUI_RTL_FeatureTree.wixobj AdvancedWelcomeEulaDlg_RTL.wixobj ... WelcomeEulaDlg_RTL.wixobj
lit.exe -out WixUI_RTL_InstallDir.wixlib WixUI_RTL_InstallDir.wixobj AdvancedWelcomeEulaDlg_RTL.wixobj ... WelcomeEulaDlg_RTL.wixobj
lit.exe -out WixUI_RTL_Minimal.wixlib WixUI_RTL_Minimal.wixobj AdvancedWelcomeEulaDlg_RTL.wixobj ... WelcomeEulaDlg_RTL.wixobj
lit.exe -out WixUI_RTL_Mondo.wixlib WixUI_RTL_Mondo.wixobj AdvancedWelcomeEulaDlg_RTL.wixobj ... WelcomeEulaDlg_RTL.wixobj

With the RTL-ized dialog sets built, all that's left is to build the new installer. In the package, you'll also find an Arabic and a Hebrew localization file. Note that (as indicated in the table above) these language files are not yet upgraded to v3. They have been converted syntactically so that Light will accept them but some strings remained in English and still wait to be translated.

candle.exe SampleWixUI_RTL.wxs
light.exe -loc WixUI_ar-ar.wxl -out SampleWixUI_RTL.msi SampleWixUI_RTL.wixobj WixUI_RTL_Mondo.wixlib