Sitecore Cloud Migration from On-Premise to Microsoft Azure Platform-as-a-Service (PaaS) — Part 2: Custom Culture / Language


Please read Part 1 of the series if you have not already to get a full background of Sitecore Cloud Migration that I am currently tackling.

Multilingual with Custom Language

Our client operates in multiple countries around the world. Some of those countries also has multiple languages. The URL Structures are as follows:

https://<some hostname>/en-us/terms-and-conditions
https://<some hostname>/ja-jp/terms-and-conditions
https://<some hostname>/en-jp/terms-and-conditions

As you can see from the example URL’s above, the URL’s are generated using the out of the box Sitecore Link Provider, with the attribute languageEmbedding=”always”. However, the language English (Japan) does not exist in Windows OS, and hence it needs to be registered in the Registry. Luckily there is a very handy utility in Sitecore Marketplace.

This setup worked like magic, and the custom language / culture has a lot of content pages and page components tied into it. Content Search API is also used to query specific result sets on those cultures as well.

Custom Language / Culture on Azure Web Apps

During an initial phase of cloud migration, we thought we would try to setup the current web site with production database that has all the content on Azure very quickly, just to show a prove of concept that the web application will function and show us a web site. However, during the initial brush testing by just hitting a list of URL’s for key pages in each culture, the custom cultures returned 404.

I quickly Google’ed some examples on registering custom cultures on Windows OS in code, and execute it on Azure Web Apps. I got an exception as the application does not have permission to modify the Globalization settings on Azure Web Apps. My jaw just dropped on the floor.


A lot of other people have the same problems with Azure Web Apps

Here is a semi useful blog post discussing on custom cultures

I had to report this big problem to the client, and also engaging Microsoft Azure support at the same time. The cloud migration project was put on hold until a resolution was found. After pondering for a few days, and taking a break and focusing on other work, I have come up with a workable solution.

The list of cultures that are supported from Azure Web Apps at the moment are the exact same list of cultures from the latest version of Windows 10. That is actually a very helpful fact to discover. Coincidentally, the entire development team is moving away from Windows 8.1 and upgrading to Windows 10. I am using this opportunity to not install the custom cultures so that I can ensure whatever solution I end up implementing will function properly.

So, without further ado, here is the solution…

Wait for it…

Solution: URL Rewriting

The solution is to use URL Rewriting to rewrite the custom culture URL, to a culture that is currently not being used for the web site, but available in Windows 10 / Azure Web Apps. With the example above, I have setup a URL rewriting rule for English (Japan) rewriting to English (Jamaica).

eg. /en-jp/terms-and-conditions is rewritten to /en-jm/terms-and-conditions

Here is a sample of what it looks like in /App_Config/UrlRewritesAndRedirects.config

Custom Culture Rewrite Rule in /App_Config/UrlRewriteAndRedirects.config

Here is a sample of /App_Config/RewriteMaps.config

Rewrite map for Custom Culture in /App_Config/RewriteMaps.config

Link Provider Modification

It is all well and good to interpret URL Requests and resolving it to the rewritten language. But what about the URL’s that are generated ? The Link Provider needs to be modified to handle this situation. The custom culture and language code en-JP needs to be stored against en-JM, so that the link provider can reference en-JM and generate a en-JP url instead.

Other Culture Info and Localisation

The culture that you have selected may not have the correct number formatting, date / time formatting, Default Calendar Type used (eg. Gregorian, Lunar), or currency formatting. In Windows 10 Control Panel -> Region -> Additional Settings, every single setting that can be overridden can be seen clearly.

Localisation formatting in Windows

You will need to build additional functionality to override each of the settings. Our solution includes having an override checkbox as a configuration Sitecore item for that language to store the exact same settings as Windows Region settings.

Migrating the content

Now that the solution in place, the content needs to be migrated from one culture to another. To ensure that existing content and Sitecore item language versions remain in tact with the appropriate workflow still in place, I have opted to migrate the content directly using Update SQL queries on the master and publishing target databases.

The queries are straight forward, just go through every single SQL Table with the Language column, and change en-JP to en-JM. As the content is changed without going through Sitecore, Content Search indexes, Link Databases and Dictionary file are going to be out of sync and rebuild is required. So make sure you have allocated enough content freeze time for this task. We left this running overnight in the production instance.


In this blog post, I have described custom cultures on a Sitecore multilingual site and the problems a lot of people have experienced on Azure Web Apps. I believe I have provided a good solution to people who are currently stuck on this problem.

Please share, comment and clap back on this blog postif you find it useful and has helped you resolve your problem as well.

Series Index

  1. Part 1 — Background Information
  2. Part 2 — Custom Culture / Language
  3. Part 3 — Managing All the Tasks