How to: Deploy Localized Sandboxed Solutions by Using Satellite Assemblies

This topic explains how you can create localized versions of sandboxed solutions that contain one or more assemblies.

Applies to: SharePoint Foundation 2010

The process of deploying localized sandboxed solutions differs in some ways from deploying localized farm solutions.

Deploying Localized Sandboxed Solutions

The continuing example in this topic is a sandboxed solution that contains a simple Web Part. However, the technique that is described—creating satellite assemblies—applies to any sandboxed solution that includes one or more assemblies. Only resources in assemblies are localized by the technique described in this topic. For information about how to localize the name and description of a Feature as it appears in a Feature gallery, see How to: Localize Feature Attributes in Sandboxed Solutions.

To create the localized resource files

1. In Microsoft Visual Studio, start an Empty SharePoint Project. Make it a sandboxed project. In the continuing example, the project is called LocalizedWebPart.

2. In Solution Explorer, right-click the project name, and select Properties.

3. In the Properties window, open the Resources tab.

4. Click the This project does not link in the middle of the window. A Resources.resx file is created in the Properties folder of Solution Explorer, and the file is opened the resource editor of Visual Studio. When completed, this default resource file will contain the strings that are used on all sites in languages for which you are not going to be providing a localized version of strings. So the language used for the strings in this file should be the language that is most likely to be a second language of people using SharePoint in a language for which you are not providing a translation of your strings. Traditionally, English is used for this purpose, but there may be exceptions. For example, if your Feature will be used primarily in countries that were formerly French colonies, French may be a more common second language of your users than English. The continuing example in this topic uses English as the default language.

5. The Web Part that will be in the project needs four strings:

   • Text for a button

   • Default text for a label

   • Text for the label when the button has been clicked an even number of times

   • Text for the label when the button has been clicked an odd number of times

   Add strings with the following names and values to the resource file.

   Name	Value
   ButtonText	Click this button!
   EvenLabelText	The button has been clicked an even number of times. Click it again.
   InitialLabelText	The button has never been clicked.
   OddLabelText	The button has been clicked an odd number of times. Click it again.

   You now must create separate resource files for each foreign language for which you are providing localized strings and add them to the Properties folder of Solution Explorer. The remaining steps of this procedure are one way of accomplishing this task.

6. In Solution Explorer, right-click the project name, and select Open Folder in Windows Explorer.

7. Open the Properties folder.

8. For each foreign language for which you are providing localized strings, create a copy of the Resources.aspx file in the same folder. Each file should be named on the pattern Resources.LCID.resx, where LCID is a language-culture code. For the continuing example, create two files: Resources.en-us.resx for English and Resources.es-es.resx for Spanish.

9. In Solution Explorer, right-click the project name, select Add, and then select Existing Item. A browse dialog box opens with the project folder as the current folder.

10. Open the Properties folder.

11. Select all of the language-specific resource files that you created (but not the default Resources.resx file), and then click Add. The files are added to the root of the project in Solution Explorer.

12. Select all of the new language-specific files in Solution Explorer and drag them to the Properties folder. You are prompted to indicate whether to overwrite the files. Click Yes.

13. Double-click one of the foreign language files to open it in the resource editor.

14. Replace the Value in each row with its translation. Do not change anything in the Name column. For the Resources.es-es.resx file in the continuing example, use the following Spanish strings.

    Name	Value
    ButtonText	¡Presiona este botón!
    EvenLabelText	El botón ha sido presionado un número de veces par. Presiónalo nuevamente
    InitialLabelText	El botón nunca ha sido presionado.
    OddLabelText	El botón ha sido presionado un número de veces impar. Presiónalo nuevamente.

15. Repeat the last two steps for each language-specific resource file.

    Note

    When the language-specific resource file is for the same language that you are using as your default language (as is the case for the Resources.en-us.resx file in the continuing example), you do not, of course, need to change the file at all. In many situations, it is not necessary to have a language-specific file for the same language that is used in the resource file for the default language, especially when the only resources in the files are strings. But resource files can contain images, icons, files and other kinds of resources too. Sometimes, you need the default resource file to use an image or other resource that is different from the corresponding resource in any of the language-specific files.

To create a Resources class and the satellite assemblies and add them to the solution package

1. In Visual Studio, on the Build menu, select Build Solution. Visual Studio does two things:

   • MSIL (Microsoft intermediate language) code is generated and inserted into the main assembly of the project:

     • A new namespace is created named Project.Properties, where Project is the name of the Visual Studio project.

     • A class named Resources is declared in the namespace.

     • A static property is added to the new class for every string in the default language resource file.

   • For each foreign language, a subfolder is created under either the Debug or the Release folder in your project, depending on your target configuration, and named with the Locale ID (LCID) of the language. Within each of these folders is an assembly, named Project.resources.dll, that contains a compiled version of the strings for the language. These are called satellite assemblies.

2. The satellite assemblies must be added to the solution package. In Solution Explorer, double-click the *.package file to open it in the Package Designer.

3. Click the Advanced tab at the bottom of the designer.

4. Click Add, and then select Add Existing Assembly.

   Note

   Do not select Add Assembly from Project Output. For purposes of the Package Designer, the satellite assemblies do not count as project output.

5. In the Add Existing Assembly dialog box, click the ellipsis (...) button and navigate to one of the satellite assemblies in a language subfolder under Debug (or Release). Click Open.

6. Leave the Deployment Target as GlobalAssemblyCache. (This is a technicality. Assemblies in sandboxed solutions are not deployed to the global assembly cache. For more information, see Where are Assemblies in Sandboxed Solutions Deployed?.)

7. In the Location box, you must append the language subfolder to the satellite assembly name. For example, for the Spanish satellite assembly in the es-es subfolder, add "es-es\" in front of the assembly name. When you are finished, the Location value is LCID\Project.resources.dll; for example, es-es\LocalizedWebPart.resources.resx.

   Note

   When you are ready to change the target configuration from Debug to Release, you must remove all the satellite assemblies from the project, rebuild, and then add them again from the LCID subfolders of the Release folder in your project. If you must change target configurations frequently, create a folder as a peer of the Debug and Release folders. Create a post-build script that copies these LCID subfolders into your new folder. Then add the assemblies in the new location to the solution package. Only the script needs to be changed when you change target configurations.

8. Repeat the last four steps for every satellite assembly, and save all files.

To create the example Web Part and reference the localized strings

1. In Solution Explorer, add a SharePoint Web Part item to the project. In the continuing example, the Web Part is named OneButton.

2. In Solution Explorer, open the Web Part's code file. In the continuing example, C# is used, so the file is OneButton.cs.

3. Add two protected fields to the custom Web Part class, as shown in the following code.

   protected Button button1;
   protected Label label1;
   

4. Add the following code to the CreateChildControls method.

   button1 = new Button();
   label1 = new Label();
   
   button1.Text = Properties.Resources.ButtonLabel;    
   label1.Text = Properties.Resources.InitialLabelText;
   
   button1.Click += new EventHandler(button1_Click);
   
   Controls.Add(button1);
   Controls.Add(new LiteralControl("<br />"));
   Controls.Add(label1); 
   

   Note that two lines assign strings by referring to properties in the Resources class that Visual Studio generated and inserted into the main assembly. The get accessor of each of these properties returns a string from the satellite assembly associated with the language of the current website. If there is no satellite assembly for the language of the website, the string that you defined in the default resource file is returned.

5. Add the following event handler to the custom Web Part class.

   void button1_Click(object sender, EventArgs e)
   {           
       if ((label1.Text == Properties.Resources.InitialLabelText) 
            || (label1.Text == Properties.Resources.EvenLabelText))
       {
           label1.Text = Properties.Resources.OddLabelText;
       }
       else
       {
           label1.Text = Properties.Resources.EvenLabelText;
       }       
   }
   

6. Build and package the solution.

To test the localization

1. Deploy the solution package to the solution gallery of a site collection that was created in one of the foreign languages, and activate the solution.

2. Navigate to the Site Settings page, and open the Features gallery of either the site collection or the root website, depending on whether the scope of your Feature is Site or Web. (It must be Site in the continuing example because Features that contain Web Parts should only be deployed with Site scope.)

3. Activate the Feature.

4. Navigate to any Web Parts page, add the Web Part to the page, and use it. Its strings should be in the language of the website.

5. Repeat the last four steps for every foreign language for which you created a satellite assembly.

6. Repeat the deployment and activation on some foreign language site collection for which you did not create a language-specific resource file. The strings of the Web Part should be the strings you put in the default resource file.

See Also

Concepts

Preparing to Create Localized SharePoint Solutions

Where are Assemblies in Sandboxed Solutions Deployed?

Best Practices for Developing Sandboxed Solutions in SharePoint 2010

Other Resources

Localization of Sandboxed Solutions in SharePoint 2010

Sandboxed Solutions Resource Center | SharePoint 2010

SharePoint Developer Team Blog

SharePoint Developer Center