Understanding the Multilingual User Interface (MUI)
Applies to: SharePoint Foundation 2010
The Multilingual User Interface (MUI) functionality in Microsoft SharePoint Foundation 2010 gives users the ability to change the language of the user interface (UI) for a website.
For example, a Spanish-speaking user who is working with an English UI can change the language of the UI to Spanish. The site's toolbars, navigation bars, list titles, and column headings appear in Spanish. Similarly, an Arabic-speaker can change the UI to Arabic. In this case, the toolbars, navigation bars, list titles, and column headings appear in Arabic, and the left-to-right orientation of the site changes to a right-to-left orientation.
For this to be possible, the languages must be made available through language packs that are installed on the servers where SharePoint Foundation 2010 is installed, and the owner of the SharePoint Foundation site must enable the languages as alternate languages for the site.
Language packs provide translations for the UI text that is included with SharePoint Foundation 2010. Text that users add to a website after it is created can also be localized. Although SharePoint Foundation 2010 has no support for localizing the content of list items, it does support localization for a list's chrome, including the list title and description, column headings, names and descriptions of custom content types used on the list, and display text used in extensions to list menus. When you customize the UI for the website itself, perhaps by adding nodes to the top navigation bar or to the Quick Launch area, or by adding extensions to the ribbon, you can also add translations of the display text for these new elements in all languages that are supported by the site. Any UI text that can be customized can also be supported by user-created language resources.
Multilingual User Interface Terminology
The following sections define standard terminology related to the MUI for SharePoint Foundation.
SKU Language
The language in which SharePoint Foundation was installed is called the SKU language. This is the language that is used by the Central Administration application, and it is the default language in which websites and site collections are created throughout the farm.
You can determine the SKU language by using the SharePoint Foundation object model. The GlobalServerLanguage static property of the SPRegionalSettings class returns an SPLanguage object with information about the display name of the SKU language and its Locale ID (LCID). For a list of LCIDs, see the SPLocale.LCID property.
Installed Languages
An installed language is either the SKU language or a language that a farm administrator adds to servers in the farm by downloading and installing a language pack.
Note
For a list of the language packs that are available, see Language Packs for SharePoint Foundation 2010.
The GlobalInstalledLanguages static property of the SPRegionalSettings class returns an SPLanguageCollection object that you can enumerate to discover which language packs are installed. Each SPLanguage object in the collection has information about the display name and LCID for an installed language.
Default Language
When website owners or site collection administrators create websites or new site collections, they can select a language. This selection becomes the default language for the new website or, in the case of a new site collection, the default language for the root website. The default language is used for text in the user interface that is created automatically when a website is provisioned. It is also the language used for untranslated user interface text that is added to a website that supports multiple languages.
The UICulture property of the SPWeb class returns a CultureInfo object with information about the default language.
Alternate Languages
The owner of a website can specify which of the installed languages the site will support. Users who navigate to the site can then change the display language of the user interface to any of these alternate languages.
The SupportedUICultures property of the SPWeb class returns an enumerable collection of CultureInfo objects with information about the languages that are supported by the website's user interface. This collection includes an object for the default language and also objects for alternate languages.
Note
If the MUI has not been enabled for a website, the collection that is returned by the SupportedUICultures property contains only one CultureInfo object, and it represents the default language. You can determine whether the MUI is enabled by getting the value of the IsMultilingual property.
User Resources
Any user interface text that can be customized in SharePoint Foundation is backed by a collection of strings, one string for each language that is supported by the website. A collection of user-created, localizable strings is called a user resource.
In the SharePoint Foundation object model, a user resource is represented by an instance of the SPUserResource class. For example, the display text for a list title is provided by the Title property of the SPList object that represents the list. The Title property, in turn, gets its value from an SPUserResource object that is returned by the list's TitleResource property.
When new user interface text is added to a website after it is created, the SPUserResource object that backs the text returns the same value—the initial value—for all languages until someone adds translations.
Note
User resources are not the same as language resource (.resx) files. Language resource files are language-specific. They contain many pieces of text in one language. SPUserResource objects, in contrast, are text-specific. They contain representations of one piece of text in many languages.
Enabling Support for Alternate Languages
The owner of a website can enable the MUI by navigating to the Language Settings page (/_layouts/muisetng.aspx) in the user interface. (Click Site Actions, and then click Site Settings. Under Site Administration, click Language settings.) Installed languages are listed in the Alternate language(s) group. The alternate languages that are currently supported by the website have check marks in the check boxes beside their names. You add or remove support for a language by selecting or clearing a check box.
You can use the SharePoint Foundation object model to do the same thing by getting a reference to a SPWeb object, setting its IsMultilingual property to true, and then calling the AddSupportedUICulture method to add support for one or more alternate languages or the RemoveSupportedUICulture method to remove support. The procedure for adding alternate language support is illustrated by the following console application:
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using Microsoft.SharePoint;
namespace ConsoleApp
{
class Program
{
static void Main(string[] args)
{
using (SPSite site = new SPSite("https://localhost"))
{
using (SPWeb web = site.RootWeb)
{
// A website can be created from a template that does not support MUI.
SPWebTemplateCollection templates = site.GetWebTemplates(web.Language);
SPWebTemplate template = templates[web.WebTemplate];
if (template.SupportsMultilingualUI)
{
// Enable MUI.
web.IsMultilingual = true;
// Add support for any installed language currently not supported.
SPLanguageCollection installed = SPRegionalSettings.GlobalInstalledLanguages;
IEnumerable<CultureInfo> supported = web.SupportedUICultures;
foreach (SPLanguage language in installed)
{
CultureInfo culture = new CultureInfo(language.LCID);
if (!supported.Contains(culture))
{
Console.WriteLine("Adding {0}", culture.Name);
web.AddSupportedUICulture(culture);
}
}
web.Update();
}
}
}
Console.Write("\nPress ENTER to continue....");
Console.Read();
}
}
}
Imports System
Imports System.Collections.Generic
Imports System.Globalization
Imports System.Threading
Imports Microsoft.SharePoint
Module ConsoleApp
Sub Main()
Using site As New SPSite("https://localhost")
Using web As SPWeb = site.RootWeb
' A website can be created from a template that does not support MUI.
Dim templates As SPWebTemplateCollection = site.GetWebTemplates(web.Language)
Dim template As SPWebTemplate = templates(web.WebTemplate)
If template.SupportsMultilingualUI Then
' Enable MUI.
web.IsMultilingual = True
' Add support for any installed language currently not supported.
Dim installed As SPLanguageCollection = SPRegionalSettings.GlobalInstalledLanguages
Dim supported As IEnumerable(Of CultureInfo) = web.SupportedUICultures
For Each language As SPLanguage In installed
Dim culture As New CultureInfo(language.LCID)
If Not supported.Contains(culture) Then
Console.WriteLine("Adding {0}", culture.Name)
web.AddSupportedUICulture(culture)
End If
Next
web.Update()
End If
End Using
End Using
Console.Write(vbCrLf & "Press ENTER to continue....")
Console.Read()
End Sub
End Module
Note that the console application checks whether the website is based on a web template that supports MUI. It is possible to create a web template that does not support alternate languages. For more information, see the SupportsMultilingualUI attribute in Configuration Element (Site) and the SupportsMultilingualUI property of the SPWebTemplate class.
For the sake of simplicity, the console application does not surround the code that sets the IsMultilingual property with a try-catch block; however, it should. Trying to set the IsMultilingual property to true throws an SPException exception if the website has customized cascading style sheets (CSS). You cannot enable support for alternate languages on a site that uses customized CSS files.
A common task that is very similar to the one performed by the last example is to replicate a website's set of alternate languages on a subsite. This is necessary because each new website is created with a default language but no alternate languages. To replicate a website's alternate language support on a subsite, enumerate the collection that is returned by the parent website's SupportedUICultures property, and add support for each culture to the child website by calling the AddSupportedUICulture method of the child website.
Changing the Display Language
In SharePoint Foundation 2010, when someone navigates to a multilingual website, the website uses the Accept-Language header that the client browser sends with the HTTP request to determine the language in which to render the user interface. If the website does not support any of the languages specified by the browser, the default language is used as the display language.
A multilingual website also displays a drop-down menu in the upper-right corner of the page, next to the user's name, where users can select a display language. When someone selects a language that is different from the current display language, the website switches to the new language. The user's preference is persisted in a cookie that is dropped on the client computer. The website gets the user's language preference from the cookie on subsequent visits to the site.
The user interface for getting a user's language preference is implemented by a PersonalActions control at the top of most pages. This control calls the Page.RegisterStartupScript method to place the following markup in the HTML that is sent to the client browser.
<script type ="text/javascript">
// <![CDATA[
function OnSelectionChange(value)
{
var today = new Date();
var oneYear = new Date(today.getTime() + 365 * 24 * 60 * 60 * 1000);
var url = window.location.href;
document.cookie = "lcid=" + value + ";path=/;expires=" + oneYear.toGMTString();
window.location.href = url;
}
// ]]>
</script>
After a display language is determined, SharePoint Foundation starts a thread to handle the request and sets the thread's Thread.CurrentUICulture property to reflect the language selection. When you write code that executes on the server—in a Web Part, for example—you can get the display language for the current HTTP context by accessing the CultureInfo.CurrentUICulture static property.
The following example is a simple console application that demonstrates how changing the display language affects display text. The application enumerates the list of cultures that are supported by a website; sets the value of the current thread's CurrentUICulture property to each supported culture, in turn; and prints the website's title as it renders in the current display language.
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Threading;
using Microsoft.SharePoint;
namespace ConsoleApp
{
class Program
{
static void Main(string[] args)
{
using (SPSite site = new SPSite("https://localhost"))
{
using (SPWeb web = site.RootWeb)
{
if (web.IsMultilingual)
{
IEnumerable<CultureInfo> cultures = web.SupportedUICultures;
foreach (CultureInfo culture in cultures)
{
// Change the UI culture of the thread.
Thread.CurrentThread.CurrentUICulture = culture;
// Print the name of the current language and the web title in the current language.
Console.WriteLine("{0} {1}", CultureInfo.CurrentUICulture.Name, web.Title);
}
}
}
}
Console.WriteLine("\nPress ENTER to continue....");
Console.Read();
}
}
}
Imports System
Imports System.Collections.Generic
Imports System.Globalization
Imports System.Threading
Imports Microsoft.SharePoint
Module ConsoleApp
Sub Main()
Using site As New SPSite("https://localhost")
Using web As SPWeb = site.RootWeb
If web.IsMultilingual Then
Dim cultures As IEnumerable(Of CultureInfo) = web.SupportedUICultures
For Each culture As CultureInfo In cultures
' Change the UI culture of the thread.
Thread.CurrentThread.CurrentUICulture = culture
' Print the name of the current language and the web title in the current language.
Console.WriteLine("{0} {1}", CultureInfo.CurrentUICulture.Name, web.Title)
Next
End If
End Using
End Using
Console.Write(vbCrLf & "Press ENTER to continue....")
Console.Read()
End Sub
End Module
How Display Text Is Localized
Localized language resources for Microsoft-supplied user interface text are provided by a set of culture-specific resource files that are installed on every web server in the farm. When a new website is created, SharePoint Foundation opens a resource file for the site's default language, finds the required text, and stores it on the objects that represent display text for the user interface. As alternate languages are added to the site, the same process is used to acquire translations for Microsoft-supplied user interface text.
Any element of the user interface that users can customize is backed by a user resource, an SPUserResource object that can store user-supplied translations for each language that is supported by a website. For example, the Title property of an SPField object provides the display name for a column in a list. That property is closely related to TitleResource, a read-only property that returns an SPUserResource object. When you get the Title property, it returns TitleResource.Value. When you set the Title property, it sets TitleResource.Value. In other words, getting or setting the Title property of an SPField object is equivalent to getting or setting the Value property of an SPUserResource object.
The SPUserResource.Value property is very interesting. The source code for the property looks something like this:
public string Value
{
get
{
return GetValueForUICulture(Thread.CurrentThread.CurrentUICulture);
}
set
{
SetValueForUICulture(Thread.CurrentThread.CurrentUICulture, value);
}
}
Getting and setting the Value property invokes one of two public methods of the SPUserResource class, the GetValueForUICulture method or the SetValueForUICulture method. In each case, it passes a CultureInfo object that represents the culture of the current thread.
The SPUserResource class maintains a dictionary that maps a set of keys (languages) to a set of values (translations). The GetValueForUICulture method and the SetValueForUICulture method look up dictionary entries by language and either get or set the string value for that language.
Initial Values for User Resources
New SPUserResource objects are created with at least one value, the value for the default language of the website. In fact, the value that is used for the default language might not be in the default language. It is whatever string is used to create the display text that the user resource backs, in whatever language was used when the display text was created.
For example, when a user creates a new list, a string that contains the list title must be passed as an argument to the constructor for the SPList class. When the TitleResource property is initialized in the SPList object, that same title string is passed as an argument to the constructor for an SPUserResource object. Code in the SPUserResource constructor creates an initial entry in the object's dictionary of values, using the website's default language as the key for the entry and the title string as the initial value.
This initial value becomes especially important when it is the only value for the user resource. The GetValueForUICulture method returns the value for the default language when any call to the method specifies a language that does not exist in the resource's dictionary. As a result, the default language value is used for all untranslated text.
Objects that consume user resources can be initialized with values from language-specific resource (.resx) files if the objects are created by a Feature that also deploys the resource files. For more information, see Localizing SharePoint Solutions.
User Interface Elements That Consume User Resources
The SharePoint Foundation object model has six classes that have properties that return an SPUserResource object:
The following table lists the properties that return SPUserResource objects and describes where the resources are consumed.
Property |
Description |
|---|---|
The source for the string returned by the SPContentType.Description property, which provides text that describes the content type. |
|
The source for the string returned by the SPContentType.Name property, which provides the display name for a content type. |
|
The source for the string returned by the SPField.Description property, which provides text that describes the column. |
|
The source for the string returned by the SPField.Title property, which provides the display name of the column. |
|
The source for the string returned by the SPList.Description property, which provides text that describes the list. |
|
The source for the string returned by the SPList.Title property, which provides the display name of the list. |
|
The source for the string returned by the SPNavigationNode.Title property, which provides the display name of a navigation node. |
|
The source for the string returned by the SPUserCustomAction.CommandUIExtension property, which provides an XML representation of a custom action used on the ribbon. |
|
The source for the string returned by the SPUserCustomAction.Description property, which provides text that describes a site, web, or list-scoped custom control. |
|
The source for the string returned by the SPUserCustomAction.Title property, which provides display text that describes a site, web, or list-scoped custom control. |
|
The source for the string returned by the SPWeb.Description property, which provides the text that describes a website. |
|
The source for the string returned by the SPWeb.Title property, which provides the display name for a website. |
Two additional properties return collections of user resources in an SPUserResourceCollection object. The SPList class has a UserResources property that contains SPUserResource objects that have localizable resources that are used by the list and also by fields, content types, and user custom actions that are associated with the list. If none of the display text for these objects has been customized, the UserResources property returns an empty collection. Typically, display text for standard lists such as Announcements and Shared Documents is not customized, and so the UserResources properties for those lists often return empty collections.
The UserResources property of the SPWeb class performs a similar function by returning a collection of SPUserResource objects that have localizable resources that are used by the website and by site columns, content types, navigation nodes, and user custom actions that are associated with the website. The objects that are returned in the collection represent only the display text that has been customized by users (including developers and administrators) of the website.
Mixed Languages
Several circumstances can create a mixed-language experience on a website. The most obvious occurs when users of the site customize it by adding new elements, such as a new list or a new navigation node, without also providing translations for the user resources that are associated with those elements.
Another kind of mixed-language experience can occur with certain built-in elements of the user interface. Error messages, notifications, and some dialog boxes might not display in the current display language. This is because SharePoint Foundation relies on several supporting technologies—for example, the Microsoft .NET Framework, Windows Workflow Foundation, and Microsoft ASP.NET—some of which are localized into a limited number of languages. If a user interface element that is generated by any of the supporting technologies is not localized into the language that the site owner specified for the site, it appears in the language in which the supporting technology was installed (that is, its SKU language).
Finally, a mixed-language experience can occur with some elements of administrative user interface. In a few cases, user interface text might appear in the language in which SharePoint Foundation was installed. This kind of mixed-language experience is typically seen only by site owners or administrators and is not seen by site users.
Adding Translations to User Resources
The most straightforward way to add a translation to the user resource for custom user interface text is to have a dual-language speaker visit the website, switch to one of the alternate languages, and translate the text by editing it directly in the administrative user interface. For example, to translate the title and description of a list, click List Settings on the ribbon. Under General Settings, click Title, description and navigation, and then edit the text in the Name and Description boxes. Changes that you make in an alternate language are saved as the value for that language in the user resource that backs the text.
The owner of a website can also arrange for bulk translation of user resources by exporting untranslated strings to a resource (.resx) file for each alternate language that the site supports. The resource files can then be given to translators, who can do their work offline. When the work is complete, the owner can import the resource files. SharePoint Foundation adds the translations to the appropriate user resources.
You can do the export operation in the user interface on the Export Translations page (_layouts/exporttranslations.aspx). You can import completed translations on the Import Translations page (_layouts/importtranslations.aspx). Alternatively, you can write your own code for both operations. Your code can call the ExportUserResources method of the SPWeb class and save the result in a resource file. When the strings are translated, you can import them by calling the ImportUserResources method. The documentation for both methods includes example code.
A better solution, from a developer's point of view, is to do the translations in advance, before you deploy a new Feature to a multilingual website. You can create language-specific resource files, reference them in Collaborative Application Markup Language (CAML), package them in a SharePoint solution, and deploy them on a website or site collection. SharePoint Foundation can then use the resource files to populate the SPUserResource objects that your Feature creates. For more information, see Localizing SharePoint Solutions.
Allowing Changes to Overwrite Translations
The Language Settings page (_layouts/muisetng.aspx) offers site owners the option to overwrite existing translations to alternate languages when changes are made in the default language. The Yes and No radio buttons on the page set the OverwriteTranslationsOnChange property of the SPWeb class to either true or false. The default setting is false (No in the user interface).
If the OverwriteTranslationsOnChange property is set to true (Yes in the user interface) and, for example, a user who is working in the default language changes the heading text for a list column, all values of the TitleResource property that is the source for the column heading are automatically reset. Existing alternate-language translations are overwritten by the new default-language text. In other words, the text no longer has translations.
If the property returns false, alternate-language translations are preserved when the default language version changes. In this case, the alternate-language text might no longer be a valid translation of the default-language source.
So, the choice is really between whether text is easier to understand (choose No) or more accurate (choose Yes).
See Also
Tasks
Walkthrough: Localizing a Web Part
Walkthrough: Localizing Columns, Content Types, and Lists