Soluling home   Document home

WiX Localization and Internationalization

WiX Toolset (Wikipedia) builds Windows Installer packages (.msi) from XML source files. WiX stores the strings of an installer in WiX localization files (.wxl), one file for each language. Soluling Desktop and Soluling Cloud support WiX localization files and WiX project files.

• Internationalize your installer
• Localization process
• Comments in WiX localization files
• Build the localized installers
• Desktop process
• Cloud process
• Samples
• Configuring WiX project file localization
• Configuring WiX localization file localization

The end of the document contains links to get the full source code of the samples. After reading this document, we recommend reading a tutorial about how to use Soluling.

Internationalize your installer

Move the strings of your WiX source file (.wxs) into a WiX localization file and refer to them with !(loc.Id). Here is the Product.wxs file of the Driving sample.

<Product
  Id="*"
  Name="!(loc.ProductName)"
  Language="!(loc.LocaleId)"
  Version="1.0.0.0"
  Manufacturer="Soluling"
  UpgradeCode="021318e6-4cbe-46f5-be37-80ace1a74fe1">

  <Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" SummaryCodepage="!(loc.SummaryCodepage)" />
  <MajorUpgrade DowngradeErrorMessage="!(loc.DowngradeErrorMessage)" />
  <Feature Id="ProductFeature" Title="!(loc.ProductTitle)" Level="1">
  ...

The strings are in the original localization file, en-US.wxl.

<WixLocalization Culture="en-US" xmlns="http://schemas.microsoft.com/wix/2006/localization">
  <String Id="ProductName"><!-- Product name -->Driving</String>
  <String Id="ProductTitle"><!-- _locComment="Product title" -->Driving</String>
  <String Id="DowngradeErrorMessage"><!-- Comment=[ProductName] is a placeholder for product name -->A newer version of [ProductName] is already installed.</String>

  <String Id="LocaleId">1033</String>
  <String Id="SummaryCodepage">1252</String>

  <String Id="CodeValue" Localizable="no">123</String>
</WixLocalization>

Soluling handles the strings as follows:

• [ProductName] is a Windows Installer property. Keep it as it is in the translation.
• LocaleId and SummaryCodepage are not translated. When building, Soluling writes the locale ID (LCID) and the code page of the target language into them. For Finnish, they are 1035 and 1252. Use them in the Language attribute of Product and the SummaryCodepage attribute of Package. You can change the names of these strings on the Options sheet.
• Soluling skips strings that have Localizable="no".

WiX 4 and later can store the string in a Value attribute, <String Id="ProductName" Value="Driving" />. Soluling supports both forms.

Localization process

You can localize a WiX installer in two ways:

• WiX project file (.wixproj). Soluling reads the localization files that the project file contains as EmbeddedResource items. The original language is the culture of the files, for example, en-US.wxl or Strings_en-US.wxl. Use this with WiX 3 projects.
• WiX localization file (.wxl). You add the original localization file to the Soluling project. Use this with SDK-style WiX 4 and later projects, which include the localization files automatically, and when you do not use a project file.

In both cases, Soluling creates the localized localization files next to the original file. It uses the <body>_<id>.<ext> pattern, so en-US.wxl becomes fi.wxl and Strings_en-US.wxl becomes Strings_fi.wxl. Soluling sets the Culture attribute of the localized file to the culture of the target language. If the target language does not have a country, such as Finnish (fi), Soluling uses the default country (fi-FI), because the WiX UI extension contains its dialog strings only for cultures with a country.

<WixLocalization Culture="fi-FI" xmlns="http://schemas.microsoft.com/wix/2006/localization">
  <String Id="ProductName"><!-- Product name -->Ajoaika</String>
  <String Id="ProductTitle"><!-- _locComment="Product title" -->Ajoaika</String>
  <String Id="DowngradeErrorMessage"><!-- Comment=[ProductName] is a placeholder for product name -->[ProductName]:n uudempi versio on jo asennettu.</String>

  <String Id="LocaleId">1035</String>
  <String Id="SummaryCodepage">1252</String>

  <String Id="CodeValue" Localizable="no">123</String>
</WixLocalization>

Comments in WiX localization files

WiX has no standard way to attach a comment to a string. Soluling lets you give the translator more information by adding an XML comment inside the String element, before or after the value. Soluling shows the comment in the translation grid.

<String Id="hello"><!-- This is a comment -->Hello World</String>
<String Id="hello">Hello World<!-- This is a comment --></String>

The comment can also start with Comment=, or it can contain a _locComment attribute, like the comments in the WiX UI extension. Soluling takes only the comment text.

<String Id="hello"><!-- Comment=This is a comment -->Hello World</String>
<String Id="hello"><!-- _locComment="This is a comment" -->Hello World</String>

Build the localized installers

Add the localized localization files to your WiX project. In a WiX 3 project, add them as EmbeddedResource items. If a localized file is missing from the project file, Soluling tells you to add it.

<ItemGroup>
  <EmbeddedResource Include="en-US.wxl" />
  <EmbeddedResource Include="fi.wxl" />
</ItemGroup>

Build the project in Visual Studio or with MSBuild. WiX builds one installer for each culture, for example, bin\Debug\en-US\Driving.msi and bin\Debug\fi-FI\Driving.msi. To build only some cultures, set the Cultures property of the project, for example, <Cultures>en-US;fi-FI</Cultures>.

Desktop process

1. Start Soluling. Drag the WiX project file (e.g., Driving.wixproj) or the original localization file (e.g., en-US.wxl) on Soluling or click the New from File or Files button and select the file.
2. Project Wizard appears. Select the original language and the target languages, for example, Finnish, and complete the wizard. If you use the project file, Soluling gets the original language from the localization file name.
3. Translate the project.
4. Choose Home | Build All to build the localized localization files, for example, fi.wxl.
5. Build the localized installers.

When you change the original localization file, open the Soluling project and choose Home | Scan. Soluling keeps the existing translations, and you only translate the strings that were added or changed.

Cloud process

With Soluling Cloud, you localize the original localization file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans.

If you want to use the WiX project file, create the project in Soluling Desktop first and upload the project. See WiX project files.

Create a project

1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
2. Click Add a new project, then Select files and pick the original localization file (e.g., en-US.wxl), or drag and drop the file onto the page. Click Create.
3. On the next page, check the project's Name. It defaults to the file's name.
4. Set the Original language to the language of the file, for example, English (United States).
5. Under Target languages, check the languages you want to translate to, for example, Finnish and German.
6. Under Source type, select Wix language file (.wxl).
7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

Translate the project

Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Get the localized files

1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
3. The Files section lists the localization file with a download button for each target language. Save each localized file next to the original file, for example, as fi.wxl.
4. Build the localized installers.

Update the project

When you change the strings, upload the new original file, translate what is new or changed, and download the localized files again. On the dashboard, click the project's Update file button (the upload arrow), select the new file or drop it onto the page, and click Update. Existing translations are kept, so you only translate the strings that were added or changed.

The dashboard is one of four ways to use Soluling Cloud. You can also use the SoluCLI command-line tool, Soluling Desktop, or SoluMake, which can run the update and build steps in your build pipeline. See the Cloud tutorial for all of them.

WiX project files

A WiX project file refers to other files, so you create the project in Soluling Desktop, upload it to Soluling Cloud, and build the localized files in Soluling Desktop.

1. Create the project for the .wixproj file in Soluling Desktop as described in Desktop process, and save it. This creates the Soluling project file (.ntp).
2. On the Translate tab, in the Send and Receive group, click Configure Cloud.
3. Log in with your Soluling account, and select the cloud account to use if you have several.
4. Click OK to create the cloud project. When Soluling asks whether to upload the local project to the cloud, click Yes, and Yes again to wait until the cloud has processed it.
5. Translate the project in Translate as described above.
6. In Soluling Desktop, on the Translate tab, click Import from Cloud. Soluling downloads the translations made in the cloud and imports them into your local project. Then choose Home | Build All and build the localized installers.

When the strings change, in Soluling Desktop, on the Home tab, click Scan. On the Translate tab, click Upload to Cloud. The cloud project is updated to match your local one, and translations that exist only in the cloud so far are kept. Translate the new and changed strings, then Import from Cloud and build again.

Samples

GitHub and <data-dir>\Samples\Wix contain the following WiX sample directories:

The installers contain the Localized.exe file of the Delphi VCL Driving sample. Build that sample before you build the installers.

Configuring WiX project file localization

You create a WiX project file localization project by adding a WiX project file (e.g., D:\Sample\Sample.wixproj) into your Soluling project. You can configure how to localize your WiX project file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

• File
• Options
• Output

Configuring WiX localization file localization

You create a WiX localization file localization project by adding a WiX localization file (e.g., D:\Sample\en-US.wxl) into your Soluling project. You can configure how to localize your WiX localization file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

• File
• Options
• Output (file name and encoding)
• Output (default language and output directory)