Localizing the SharePoint User Interface by Using Resource Files (Sanjay Arora)

Article
07/01/2011

SharePoint localization consists primarily of translating the text in the user interface based on a given culture or language. This translation relies on resource files available to the system. To localize a solution, you remove hard-coded strings from the code and abstract them into resource files.

Type of Resource Files

In SharePoint, there are two types of resource file: provisioning resources, used during provisioning of sites and features, and runtime resources, used by the ASP.Net framework during runtime.

The first type of resource files, leveraged by SharePoint during provisioning, resides at either of the following locations:

· $SharePointRoot$\TEMPLATE\FEATURES\<FeatureName>\Resources\

· $SharePointRoot$\Resources\

Note

The use of these locations for resource files depends on the level of sharing required in your solution. If the resource files are specific to a feature, they will reside under the specific feature directory. If the resource files are shared across features, list definitions, site definitions, custom actions, content types, and so forth, these files will reside under the resources folder of SharePoint root directory.

The second type of resource files, leveraged by ASP.Net during runtime (aspx/ascx), reside in following location:

· $SharePointRoot$\Config\Resources

Important

The ASP.Net runtime is unaware of SharePoint. So that these file can be consumed during runtime, they should be available under the App_GlobalResources path of the virtual directory of the respective web application.

Adding Resource files to a Solution

Provisioning resource files get copied to respective locations during the deployment of SharePoint solution. So how does the SharePoint solution determine the target location for the resource files during deployment? The solution manifest file (manifest.xml), defined in the root folder of the solution file, defines the target location of these resource files. The manifest.xml file references all the components of the solution and defines their locations on the target machine. If you are using Visual Studio 2010, you can preview the manifest file by navigating to the package folder under your solution by right-clicking, choosing View Designer, and then selecting the Manifest tab.

Feature Specific resource file

The provisioning of resource files in a feature-specific resource folder is defined in the manifest.xml file as follows:

 <Solution>

   <Resources>

     <Resource Location="NewFeature\NewResources.resx"/>

   </Resources>

 </Solution>

In Visual Studio 2010, you can add this resource file by right-clicking the respective feature and then selecting Add Feature Resource.

Shared resource file

The provisioning of resource files under the resource folder in the SharePoint root directory is defined in the manifest.xml file as follows:

 <Solution>

    <RootFiles>

      <RootFile Location="Resources\NewResources.resx"/>

    </RootFiles>

 <Solution>

In Visual Studio 2010, you can add this resource file to the SharePoint root mapped folder under SharePoint root directory by right-clicking your solution project, selecting Add, and then SharePoint Mapped Folder. Then, add the resource file to the newly created resource folder.

Alternatively, you can add an empty element, and a resource file under that with the deployment type of “RootFile”. The difference between the previous approach and this approach is flexibility of changing the deployment type.

For further details on deployment type, please see Deployment Type Enumeration.

Runtime Resource Files

The provisioning of resource file for the web application will copy your resource file to the Web Application’s IIS directory\App_GlobalResources during the deployment process. It is defined as follows:

 <Solution>

   <ApplicationResourceFiles>

     <App_GlobalResourceFile Location="NewResource.resx"/>

   </ApplicationResourceFiles>

 </Solution>

In Visual Studio 2010, you can add this resource file under an empty element. When the resource file is added, the Deployment type of the file should be set as AppGlobalResource.

Note

If you add a resource file under a SharePoint mapped folder Resources, the deployment type will not be editable. To change deployment type, you must add an empty Element SharePoint Project item to your project and then underneath it, add your resource file.

Important

There are additional resource file locations that are not mentioned in this article: virtual _wpresources or $SharePointRoot$\CONFIG\AdminResources

_wpResources : This is the location for Web Part resources for the Global Assembly Cache (GAC).

AdminResources: This location has localization resources used by extensions to the Central Administration user interface.

Retrieving Localized Strings

Provisioning Resources

Using SPUtility.GetLocalizedString

This method can retrieve a string value from a resource file located in the Resources folder that is just below the SharePoint root or in the respective feature directory. The method signature is as defined here.

When you define a feature, you can set the DefaultResourceFile attribute to specify a shared file with the localized resources used by all of the features in your application. If the DefaultResourceFile attribute is set, then SharePoint looks for a culture-specific resource file on the path $SharePointRoot$\Resources. SharePoint expects the file to be named with the pattern <DefaultResourceFile> . <CultureName> .resx, where DefaultResourceFile is the value of the DefaultResourceFile attribute and CultureName is in the format used by the CultureInfo.Name property. The string returned by the DefaultResourceFile property is the first part of the file name.

If the DefaultResourceFile attribute is omitted from the feature definition, the DefaultResourceFile property returns an empty string. In this case, SharePoint retrieves resources for the feature from a resource file in a subfolder named Resources under the feature's folder on the file system--that is, on the path $SharePointRoot$\TEMPLATES\FEATURES\ <FeatureName> \Resources. SharePoint expects the resource file to be named with the pattern Resources. <CultureName> .resx

Important

When SharePoint retrieves a resource value, it looks for a resource file that has the base file name followed by a language identifier that corresponds to the value of the CurrentUICulture property of the currently executing thread. SharePoint expects to find an exact match. If an exact match for language identifier is not found, it defaults to the default language for the site found using SPWeb.Language. This behavior is unlike ASP.Net where fallback is initially to the base language and thereafter the ultimate fallback is to language neutral culture.

Using Expression Builder Syntax

In the XML markup or Collaborative Application Markup Language (CAML), replace the hard-coded strings with values that use the following format:

<%$Resources:Resource File Name, String ID%>

To use feature-specific provisioning resource files, inside of the feature's folder, remember to omit the resource file name in the string expression ( <%$Resources:String ID%> ).

Runtime Resources

Using HttpContext.GetGlobalResourceObject:

This method can retrieve a string value from a resource file located in the Resources folder that is in the App_GlobalResouces folder of the Web application’s virtual directory. The method signature is as defined here.

If you are using the resources to localize code in addition to ASPX markup, leave the Build Action property setting of each file as Embedded Resource to cause the resource to compile into a satellite assembly. However, if you are using the resource files only to localize the markup, you can optionally change Build Action to Content to prevent the file from being compiled into the main application assembly.

Using Expression Builder Syntax

In the XML markup for the ASPX page or control (ascx), replace the hard-coded strings with values that use the following format:

<%$Resources:Resource File Name, String ID%>