Translation for Bamboo's Non-Web Part Products

Last year (wow, does time fly!) I wrote a blog post about the ability to translate Bamboo Solutions Web Parts by updating XML files in the WPResource directory.  Since then, Bamboo Solutions has expanded our portfolio by leaps and bounds, and not just in the area of Web Parts but also in Custom Columns and Application Pages.  With evolution come challenges, and ours involved how to provide the same functionality of product translations while providing the flexibility to our end users which resulted in new translation methods for the following products:

• Alerts Administrator
• My Alerts Organizer
• SharePoint Custom Columns

Bamboo Solutions decided to utilize the SharePoint Language Packs as the engine behind the above products' language translation.  If you are not entirely familiar with the SharePoint Language Packs, let me provide you with a brief overview:

SharePoint Language Packs provide SharePoint Administrators the ability to create sites with different languages other than the original default language deployed with the original installation.  After successfully installing the Language Pack of your choice, when a user creates a future site, a new option will appear which allows the user to select the appropriate language:

If I were to create a Team Site using the English template, the Team Site would look like this:

Whereas a Team Site created in French looks like this:

So how does Microsoft achieve this magical switch?  They have special set of Language files that defines the individual strings.  There are actually 2 main types of language files:

Application Resources: Application Resources are used in the main content areas viewed by end users.  For example, Application Pages, Custom Actions (including site action menu and site settings), Navigation Bars, Web Parts and other Application Resource Elements.  These language files are stored in:

  <drive>:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Config\Resources\

When a new Web Application is created, these files are copied from the directory above into each Web Application's App_GlobalResources directory.  For example:

<drive>:\Inetpub\wwwroot\wss\virtualdirectories\<port>\App_GlobalResources\

The App_GlobalResources directory is the location where the individual Web Applications physically read the language files.

Provisioning Resources:  Provisioning Resources are global variables used for translation within Features, Site Definitions, List Definitions and other Provisioning Resource Elements.  A good example would be when you create a new view, translation of the text displayed in the New View form is controlled by these files.  These language files are stored in:

<drive>:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Resources\

Unlike Application Resources, the Provisioning Resources remain in the 12 hive as they are considered global to the farm.

Now that we've talked about what files are where, let's talk about the actual files themselves.  The whole point of Language Packs is to allow multiple languages to co-exist within the same site collection.  To allow for this flexibility, language files are uniquely identified for each language using a Culture code.  If you have one or more language packs installed, you will notice there will be multiple instances of a file but with one unique difference: a 4-letter code at the end of the file name:

Let's take a look at wss.resx in the example pictured above.  Here you will notice 3 variations:

1. wss.resx
2. wss.fr-fr.resx
3. wss.en-us.resx

The first one is a default file, and I'll get back to that one in a second.  The en-US version is the English translation of the wss.resx, and fr-fr is the French version.  For more details about the country codes, see this TechNet article.

Let's say you've created a new site and the French language pack that was selected.  A given component in SharePoint will first look for their file, say wss is what WSS v3 would be looking for, then it will see if the file exists with the fr-fr culture code.  If the file does exist, it knows to load that file.  But you might now be asking what if the file does not exist with the culture code, well that's where the instance of the file without a specified culture code comes into play.  This is the fallback file format for ALL language packs.  If the system is unable to find the culture code-defined file, it will fall back to the non-defined instance.  Files without the culture code are deployed during the initial installation process, and strings ARE translated automatically based on the installation you run.  So this means if you installed the French edition of WSS v3.0, the wss.resx file have French strings within, not English.  Pretty cool, huh?

Now let's talk about the actual values within the language file.  I'm not going to dive into every piece of the file as, to be perfectly honest, I'm not sure what they all are, but I am going to talk about one important piece: the strings.  We will continue to use the wss.resx file as my use case example.  The individual strings are defined by unique tags called data.  For example, to control the Access Denied message that users receive, the following tag needs to be updated:

  <data name="accessDenied_pagetitle">
    <value>Error: Access Denied</value>
  </data>

In the above example, you will notice 2 main components: a name that is a unique identifier for the string, and a value which is the actual string value displayed to the end user.  Value is the string you want to actually update.

After you have made any necessary changes, as I mentioned earlier, if the changes are being made to the Application Resources, the changes should be reflected in 2 locations: the 12 hive within ..\config\resources, and Web Application within <port>\App_GlobalResources\.  To save time and effort, I suggest the following shortcut:  Make the changes in the 12 hive first and, when those changes are complete, run the following stsadm command:

stsadm -o copyappbincontent

This will push any changes made in the <12 hive>\Config\Resources\ directory to ALL defined Web Application resource directories for you.  One item to note: the command copyappbincontent compares the date and timestamp between the 12 hive file and Web Application file.  If the Web Application file (if it exists) is newer  then the file in 12 hive, it will not overwrite.  A nice protection in case someone updates files in the Web Application directly.

After having gone through all of this, you may be wondering what this has to do with Bamboo products.  As mentioned, the Bamboo Solutions products Alerts Administrator, My Alerts Organizer, and SharePoint Custom Columns all use the same functionality for their translation.  When these products are deployed on a SharePoint installation, we create the fallback language file (for example, Bamboo.LookupPlus.resx) without any culture code.  As a result, all Language Packs will be able to read this file to display text appropriately.  If you have a language pack installed and deployed in your environment, we suggest copying the base file and adding the appropriate culture code at the end.  Now you can translate all the strings listed in the file to that language.  Note: strings for both Application Resources and Provision Resources exist in the same file so we suggest updating one file then copying the entire file to the Provision Resource directory.  After making the appropriate updates to the Application Resources directory, use the copyappbincontent to push the updated language file to all existing Web Applications.  If you do not currently have a Language Pack installed, we suggest adding the appropriate culture code to the file (i.e., if you have the French version of WSS v3 installed, add the culture code fr-fr to the file) because we will overwrite the base file during the upgrade process, causing you to lose any changes made to the base.

That's it!  You have now translated your Bamboo Solutions product!

PLEASE NOTE: The majority of this post was referring to the core files of SharePoint for example purposes only.  It is STRONGLY urged that you do not modify the SharePoint core files as any future service packs can potentially overwrite any changes made.  Bamboo Solutions, on the other hand, will only modify our base file; any culture code-defined files will remain untouched.

PLEASE ALSO NOTE:  You will need to copy any modified culture-based files to all Web Front End Servers.