Working with Language Pack Farm Solutions
Applies to: SharePoint Foundation 2010
This topic describes how to develop and install a localization of a Microsoft SharePoint Foundation farm solution by using solution packages that have been designated as language packs.
Note
The term language pack as used in this topic does not refer to the Microsoft-supplied SharePoint Foundation and Microsoft SharePoint Server 2010 Language Packs that provide localization of the built-in user interface (UI) of SharePoint Foundation and SharePoint Server 2010. The Microsoft-supplied language packs are .exe files that you can download from the Microsoft Download Center and install on each front-end web server. For more information, see Preparing to Create Localized SharePoint Solutions, Language Packs for SharePoint Foundation 2010, and 2010 Server Language Packs for SharePoint Server 2010, Project Server 2010, Search Server 2010, and Office Web Apps 2010.
What are Custom Language Packs?
A custom language pack is a solution package (.wsp file) that contains only resources that are used to add support for an additional language to an existing farm solution. It shares the same solution ID (a GUID) with the original solution. The language pack can be added and deployed to the farm long after the original solution is added and deployed. A custom language pack is not needed when localization resources, such as strings, are available before a solution package is distributed. Such resources can be included in the original package for the solution. The primary purpose of custom language packs is to enable developers to add localization for additional languages after the original solution package has already been distributed without having to upgrade the original solution package.
If you prefer, you can create language packs for a new solution and include them along with the original solution. However, for simplicity, this article assumes that language packs are distributed after the original solution.
Note
Custom language packs are not supported in sandboxed solutions. For information about localizing a sandboxed solution, see Localization of Sandboxed Solutions in SharePoint 2010.
There is nothing in the .wsp file itself that designates it as a language pack. The designation is in the configuration database entry for the language pack. This designation is recorded when the language pack solution is added to the farm's solution store and when it is deployed.
Important
It is the responsibility of the farm administrator to add and deploy the solution correctly, using SharePoint Management Shell or the object model, so that it is designated as a language pack. Details about how to do this are included later in this topic. We recommend that developers include the locale ID in the .wsp file name as a convenience to the administrators.
Consider the following points when you are developing a language pack, and be sure that farm administrators to whom you distribute the language packs are also aware of these points:
The original farm solution can contain localization resources for zero or more languages. Language packs add resources for additional languages.
A language pack can be bound to only one language.
A language pack can be associated with only one original solution.
A language pack cannot be added to the solution store unless the original solution that it localizes is also in the solution store.
A language pack cannot be deployed unless the original solution that it is associated with is deployed.
A solution cannot be retracted unless all the language packs associated with it are retracted first.
Creating a Language Pack
You create a language pack just like any other solution package (.wsp file).
To create a language pack
Create an Empty SharePoint Solution in Microsoft Visual Studio. Give the solution the same name as the original solution that is being localized, but add an LCID to the solution name to indicate the language that the new solution supports. (A custom language pack can support only one language.)
In Solution Explorer, double-click the .package file to open the Properties window.
Change the automatically generated solution ID to the same solution ID as the original solution.
Add localized files to the solution, remembering the following points:
Do not add code files or other non-localizable files to the package.
For the most part, the folder structure in Solution Explorer should match the folder structure in the original solution when it is opened as a Visual Studio project (except that you should not duplicate folders that contain only non-localizable files). For example, if the original solution had a SharePoint Mapped Folder to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\IMAGES, the language pack solution should too. (Feature-relative resources are an exception to this rule. See Feature-Relative Resources later in this topic.)
Any localizable resource can be included. Some of the most common are the following:
Resource (.resx) files, which can be deployed globally, just to a specific web application, just for a specific Feature, or just for a specific Web Part.
Satellite assemblies.
Language-specific site definition (webtemp*.xml) files. For more information about such files, see How to: Create Localized Versions of Custom Site Definitions.
Language-specific application pages.
Culture-specific image files, CSS files, and HTML files.
Build the Visual Studio solution, package it, and deploy it to your development environment for testing. The original solution that is being localized must already be deployed.
Repeat the procedure for every language. Each must be a separate solution package.
Feature-Relative Resources
If any of your localization files applies to just a specific Feature within the original solution, you must deviate from the usual rule of making the folder structure of your language pack solution match the folder structure of the original solution. This is because the resources for the additional language must be deployed to a subfolder of the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES\MyOriginalFeature folder. For example, a RESX file would typically be deployed to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES\MyOriginalFeature\Resources. However, you cannot reuse the Feature name and ID from the original solution. (Doing so would cause an error when the solution is deployed.) Instead, use a RootFile element in the manifest of your solution package to specify the deployment path for the file. The following is an example.
<Solution ... >
<RootFiles>
<RootFile Location="TEMPLATE\FEATURES\MyOriginalFeature\Resources\Resources.fr-ca.resx" />
</RootFiles>
</Solution>
Adding and Deploying a Language Pack
Farm administrators deploy language packs to the solution store of a farm and deploy them with SharePoint Management Shell (or by running custom deployment code using the SharePoint Foundation object model).
The Add-SPSolution command is used in SharePoint Management Shell to add the solution to the solution store of the farm. The -Language parameter must be used to designate the language. For example, the following command adds a language pack for Canadian French. Note that the LCID is also added to the solution file name as a convenience to administrators.
Add-SPSolution -LiteralPath C:\MySharePointSolutions\OriginalSolution_3084.wsp -Language 3084
To deploy the solution, use the Install-SPSolution command. Again, include the -Language parameter.
Install-SPSolution -Identity OriginalSolution_3084.wsp -Language 3084
Administrators must also use the -Language parameter when retracting and removing a language pack, as shown by the following two commands. This is important because the original solution package and all its language packs have the same solution ID.
Uninstall-SPSolution -Identity OriginalSolution_3084.wsp -Language 3084
Remove-SPSolution -Identity OriginalSolution_3084.wsp -Language 3084
To program custom installation and deployment, use the following classes.
SPSolution – Represents a solution on a server farm.
SPSolutionCollection – Represents a collection of SPSolution objects.
SPSolutionLanguagePack – Represents a solution that was designated as a language pack when installed.
SPSolutionLanguagePackCollection – Represents a collection of SPSolutionLanguagePack objects.