Localizing host web features in apps for SharePoint

Visual Studio 2012 can’t localize host web features by itself. Learn about a tool that you can use to localize your host web features, such as app parts and custom actions.

SharePoint is used in many countries, regions, and languages. Because of this, you may want to maximize your reach to potential customers by localizing your apps. There are resources out there that can help you localize your app, like How to: Localize apps for SharePoint and Localize the app web, host web, and remote components of an app.

In this post, I want to focus in some components that provide an important link from the host web to the app itself. Host web features, such as app parts and custom actions, are vital in connecting experiences in SharePoint to your app. Localizing host web features is of the utmost importance.

Localizing app parts and custom actions can be a little difficult because Visual Studio 2012 does not properly package resource files for these features. If you try to use a resource string in an app part, the app part displays the resource string name, and not the value as expected. The following image shows the result of trying to localize an app part by using the strings in the host web resource file.

Figure 1. Failed attempt to localize an app part with strings in the host web resource file

However, the workaround is not too complicated. Resource files are actually included in the app package. The only missing parts are the OPC (Open Packaging Conventions) relationships to resource files in the app package. OPC relationships define an association between two items—in this case, the resource file and the package.

You can manually add the relationships to the app package, as explained in How to: Localize apps for SharePoint. But manually adding the relationships prevents you from using F5 to automatically build, deploy, and debug your app. To be able to use F5 to debug a localized app, you can use a program or script in the pre-deployment event of the app project in Visual Studio. The sample project in this article is a Visual Studio solution that does exactly what we need: it adds the missing relationships to resource files in the app package.

You can build the AddRelsToAppPackage project and use the compiled executable in the pre-deployment event of your app for SharePoint project. Just follow these steps:

1. Build the AddRelsToAppPackage project.
2. Copy the executable file to the root folder of your app for SharePoint project.
3. Right-click your app for SharePoint project, and click Properties.
4. Click the SharePoint property page.
5. Type the following command in the pre-deployment command line:
   "$(ProjectDir)\AddRelsToAppPackage.exe" "$(TargetDir) "
   Important: The trailing space after $(TargetDir) is required.

Now you can debug your app for SharePoint by using F5. The following image shows a localized app part that uses the workaround.

Figure 2. Successfully localized app part using the AddRelsToAppPackage tool

The AddRelsToAppPackage project should meet the basic requirements to localize host web features in apps for SharePoint. Feel free to edit the Visual Studio solution if your app has additional requirements. As a reference, here are the tasks performed by the AddRelsToAppPackage project:

1. Opens the folder provided as the first parameter
2. Retrieves the first file that matches the search pattern *.*app
3. Extracts the file that includes the OPC relationships for the host web features
4. Loads the contents of the file in an Xml object
5. Adds an OPC relationship to the Xml object for every resource file in the root folder of the app package
6. Writes the content back to the file

I hope you are successful in localizing your app for SharePoint. By localizing your app, you can provide a better experience and reach more customers.