Localizing a LightSwitch Application (Heinrich Wendel)

With Visual Studio Update 2 we finally added a functionality a lot of you (especially outside the US) have been waiting for, the ability to localize a LightSwitch application into multiple languages. Until then you had to hardcode one language into your application. Finally, international companies and companies that are located in countries that use multiple official languages, can provide users with an application in their preferred language.

The concept is simple. For each DisplayName or Description property that you want to localize, you specify a $(ResourceString) instead of the actual string. For each translation, you create a resource file which contains the actual values in the target language. At runtime, we will automatically detect the preferred language based on the user’s browser or operating system setting. In addition to that, strings that you specify on the server, e.g. names for entities or properties, are also propagated to the client, no need to translate them twice. And, you can also localize messages that are created while running business logic on the server or validation rules on the client.

We already published a walkthrough on MSDN which gives you a detailed step by step description. But, there is only one language that everybody in the world understands. It is the language of pictures. I tried to create a visual walkthrough for you guys. Click the picture bellow to start your localization experience (it might take a while to load, there are quite a few pictures in it).

For some reason it doesn’t work as expected, your see strings like “/client/ErrorMessage” or “$(ContactPhone)” in the UI? As so often, the devil lies in the details. In the last part of this blog post I’ll try to summarize the questions and problems that came up most often in our forums:

• What are valid keys for resource identifiers? You should only use letters and numbers for resource identifiers. Don’t use spaces and to be absolutely safe stay away from any special characters.
• What is the naming convention for Server resource files? The server project uses “Service.resx” (Service, not Server ) for the neutral translations and “Service.LocaleID.resx” for individual languages. Those files live in the root folder of the server project.
• What is the naming convention for Silverlight resource files? The Silverlight client uses “Client.resx” for the neutral translations and “Client.LocaleID.resx” for individual languages. Those files live in the root folder of your Silverlight client project.
• What is the naming convention for HTML resource files? For the HTML client use “client.lang-LocaleID.resjson” for all languages. Simply use the appropriate locale id for the neutral language. Those files live in the “Content/Resources” folder of your HTML client project.
• Where do I specify the neutral language? You can specify the neutral language in your project properties. It defaults to your Visual Studio language when creating a new project.
• Why are the naming conventions for HTML and Silverlight/Server different? We tried to follow the conventions of the technologies the individual projects are based on. For the Server and Silverlight we use the .NET conventions and resx files, for HTML we are following the WinJS naming conventions using resjson files.
• How does the language detection mechanism work? If you run a Silverlight application we will use the user’s Windows language as preferred language. If you run an HTML app we will use the browser setting.
• Can I present users with a choice of languages? Not at the moment, sorry. Usually it is pretty easy to change the language of your browser though and you can also change the language of Windows on a per user basis.
• How does the server know about the client’s language? With every HTTP request your browser sends the client language as part of the ACCEPT_LANGUAGES header. ASP.NET will run the thread that is processing the request using the culture specified by the header.
• My client shows the raw resource strings, what is wrong? Did you translate both your client and server into the specific language? We will only pick up a language if both projects actually provide translations, otherwise users could end up with a mix of languages in their UI.

That’s it

I tried to keep it a bit shorter this time. As always, use the comments section and our forums for feedback and questions.

- Heinrich Wendel, Program Manager LightSwitch