ClickOnce Deployment and Localization

Localization is the process of making your application appropriate for a specific culture. This process involves translating user interface (UI) text to a region-specific language, using correct date and currency formatting, adjusting the size of controls on a form, and mirroring controls from right to left if necessary.

Localizing your application results in the creation of one or more satellite assemblies. Each assembly contains UI strings, images, and other resources specific to a given culture. (Your application's main executable file contains the strings for the default culture for your application.)

This topic describes three ways to deploy a ClickOnce application for other cultures:

  • Generate one deployment for each culture, with a single satellite assembly included in each.

  • Include all satellite assemblies in a single deployment.

  • Download satellite assemblies on demand.

Generate One Deployment for Each Culture

In this deployment strategy, you generate multiple deployments. In each deployment, you include only the satellite assembly needed for a specific culture, and you mark the deployment as specific to that culture.

To use this method in Visual Studio, set the Publish Language property on the Publish tab to the desired region. Visual Studio will automatically include the satellite assembly required for the region you select, and will exclude all other satellite assemblies from the deployment.

You can accomplish the same thing by using the MageUI.exe tool in the Microsoft .NET Framework SDK. Use the Populate button on the Files tab of your application manifest to exclude all other satellite assemblies from the application directory, and then set the Culture field on the Name tab for your deployment manifest in MageUI.exe. These steps not only include the correct satellite assembly, but they also set the language attribute on the assemblyIdentity element in your deployment manifest to the corresponding culture.

After publishing the application, you must repeat this step for each additional culture your application supports. You must be careful to publish to a different Web server directory or file share directory each time, because each application manifest will reference a different satellite assembly, and each deployment manifest will have a different value for the language attribute.

Including All Satellite Assemblies in a Deployment

Instead of publishing multiple ClickOnce deployments, you can publish a single ClickOnce deployment containing all of the satellite assemblies.

To use this method, you must set the culture for your application to the default, which is (Default) in Visual Studio and neutral in MageUI.exe. Next, you must manually include all of the satellite assemblies in your deployment. This is accomplished in Visual Studio using the Application Files dialog box, which you can access from the Publish properties page. In MageUI.exe, you can add the satellite assemblies by using the Populate button on the Files tab of your application manifest.

The benefit of this approach is that it creates a single deployment and simplifies your localized deployment story. At run time, the appropriate satellite assembly will be used, depending upon the default culture of the user's Windows operating system. A drawback of this approach is that it downloads all satellite assemblies whenever the application is installed or updated on a client machine. If your application has a large number of strings, or your customers have a slow network connection, this process can cause a moderate performance hit during application update.

NoteNote

This approach assumes that your application adjusts the height, width, and position of controls automatically to accommodate different text string sizes in different cultures. Windows Forms contains a variety of controls and technologies that enable you to design your form to make it easily localizable, including the FlowLayoutPanel and TableLayoutPanel controls as well as the AutoSize property. How to: Support Localization on Windows Forms Using AutoSize and the TableLayoutPanel Control
How to: Support Localization on Windows Forms Using AutoSize and the TableLayoutPanel Control
How to: Support Localization on Windows Forms Using AutoSize and the TableLayoutPanel Control
How to: Support Localization on Windows Forms Using AutoSize and the TableLayoutPanel Control

Downloading Satellite Assemblies on Demand

If you decide to include all satellite assemblies in a single deployment, you can improve performance by using on-demand downloading, which enables you to mark assemblies as optional. The marked assemblies will not be downloaded when the application is installed or updated. You can install the assemblies when you need them by calling the DownloadFileGroup method on the ApplicationDeployment class.

Downloading satellite assemblies on demand differs slightly from downloading other types of assemblies on demand. For more information and code examples on how to enable this scenario using the .NET Framework SDK tools for ClickOnce, see Walkthrough: Downloading Satellite Assemblies on Demand with the ClickOnce Deployment API.

You can also enable this scenario in Visual Studio. Walkthrough: Downloading Satellite Assemblies on Demand with the ClickOnce Deployment API Using the Designer
Walkthrough: Downloading Satellite Assemblies on Demand with the ClickOnce Deployment API Using the Designer

Testing Localized ClickOnce Applications Before Deployment

A satellite assembly will be used for a Windows Forms application only if the CurrentUICulture property for the main thread of the application is set to the satellite assembly's culture. Customers in local markets will probably already be running a localized version of Windows with their culture set to the appropriate default.

You have three options for testing localized deployments before making your application available to customers:

  • You can run your ClickOnce application on the appropriate localized versions of Windows.

  • You can set the CurrentUICulture property programmatically in your application. (This property must be set before calling the Run method.)

  • You can switch cultures on your operating system if you have installed Windows Multilanguage User Interface Pack (MUI Pack). However, MUI supports only a subset of all possible cultures, so this option may not apply to your project.

    For more information on MUI, see Microsoft Global Development and Computing Portal.

See Also

Reference

<assemblyIdentity> Element

Concepts

ClickOnce Deployment Overview

Other Resources

Globalizing Windows Forms