SharePoint 2013 Apps: Lokalisierung bei Remote Apps

In diesem Beitrag soll gezeigt werden, wie cloud-basierte Apps (auto-hosted oder provider-hosted) lokalisiert werden, d.h. wie man die App für verschiedene Sprachen fit machen kann. Bei SharePoint-hosted Apps kann man dazu auf die von Farmlösungen bekannten Möglichkeiten zurückgreifen. Bei cloud-basierten Apps liegt aber die Verantwortung über das AppWeb beim Entwickler und man muß sich deshalb auch um die Lokalisierung selbst kümmern. Achtung: es geht hier wirklich nur um die Lokalisierung der Remote-Komponenten und nicht darum, wie man z.B. per App bereitgestellte Listen lokalisiert. Das werde ich eventuell in einem späteren Beitrag beschreiben.

Update 27.08.2013: hier habe ich in einem Beitrag die Lokalisierung von Hostweb-Komponenten beschrieben.

Ich gehe hier wieder davon aus, daß die App mit Visual Studio 2012 erstellt wird. Damit ist das AppWeb im Grunde eine ganz normale ASP.NET Anwendung und man kann zur Lokalisierung die dafür vorgesehenen Möglichkeiten verwenden. Die grundsätzliche Vorgehensweise ist hier beschrieben: ASP.NET Globalization and Localization. Ich werde hier nur das Wichtigste kurz zusammenfassen.

Ressourcendateien hinzufügen

Ressourcendateien *.resx werden zur Bereitstellung sprachabhängiger Elemente verwendet. Man legt dabei für jede Kultur, die man unterstützen möchte, eine Datei an. Es kann also eine app.de-DE.resx für Deutschland und eine app.de-CH.resx für die Schweiz geben. Man sollte außerdem immer eine neutrale app.resx bereitstellen, die immer dann verwendet wird, wenn es keine spezifische Datei für eine Kultur gibt.

In ASP.NET kann zwischen lokalen und globalen Ressourcen unterschieden werden. Lokale Ressourcen gelten immer nur für eine Seite *.aspx oder ein benutzerdefiniertes Control *.ascx. Diesen weg möchte ich hier nicht weiter verfolgen und empfehle stattdessen die Benutzung von globalen Ressourcen. Damit hat man alle sprachabhängigen Komponenten in einer Datei und man kann gleiche Elemente an unterschiedlichen Stellen wiederverwenden.

Globale Ressourcen werden in einem besonderen Ordner App_GlobalResources abgelegt. In Visual Studio erzeugt man ihn z.B. durch einen Rechtsklick auf das Projekt im Solution Explorerund dann Add -> Add ASP.NET Folder -> App_GloablResources. Dem Ordner kann man dann ebenfalls z.B. durch Rechtsklick und Add -> Resources File Ressourcendateien hinzufügen. Im Solution Explorer kann das dann so aussehen:

Kultur auswählen

Man muß sich entscheiden, wie die App auf verschiedene Kulturen reagieren soll, d.h. in welcher Sprache die App einem bestimmten Benutzer präsentiert wird.

Es gibt die Möglichkeit, daß die App einfach auf die im Browser eingestellte bevorzugte Sprache reagiert. Beim Internet Explorer ist diese Einstellung z.B. über die Internetoptionen und dann den Button Sprachen im Reiter Allgemein erreichbar. Damit diese Einstellung von der ASP.NET Webanwendung verwendet wird, genügt ein einfacher Eintrag in der web.config der Anwendung:

<configuration>
  <system.web>
    <globalization culture="auto:de-DE" uiCulture="auto:de-DE" />

Die dort angegebene Kultur (hier de-DE) wird als Standard verwendet, falls ein Browser keine bevorzugte Kultur liefert.

Es gibt aber auch die Möglichkeit, sich nach der in SharePoint verwendeten Kultur zu richten. Diese wird beim ersten Aufruf der App aus SharePoint über die {StandardTokens} als QueryString-Parameter SPLanguage übermittelt. Wenn sie verwendet werden soll, kann man den Parameter auslesen und damit die zu verwendende Kultur selbst setzen. Das sollte dann in einer Überschreibung der InitializeCulture-Methode der Startseite geschehen. Der Code dazu kann z.B. so aussehen:

protected override void InitializeCulture() {
  string selectedLanguage = Request.QueryString["SPLanguage"];
  if (selectedLanguage != null) {
    Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(selectedLanguage);
    Thread.CurrentThread.CurrentUICulture = new CultureInfo(selectedLanguage);
  }
  base.InitializeCulture();
}

Ressourcen verwenden

Ressourcen können auf zweierlei Art verwendet werden: deklarativ oder per Code. Beim deklarativen Ansatz wird z.B. einem Control direkt beim Erstellen in der aspx ein Wert aus den Ressourcen zugewiesen. Für den Text eines Buttons kann das z.B. so aussehen:

<asp:Button ID="Button1" runat="server" Text="<%$ Resources:AppRes, Button1_Text %>" OnClick="Button1_Click" />

Die Referenz auf ein Ressourcenelement beginnt dabei immer mit dem Schlüsselwort Resources gefolgt von einem Doppelpunkt. Danach kommt der Name der Ressourcendatei ohne Kultur und ohne die resx-Erweiterung. Durch ein Komma getrennt folgt dann der Schlüssel, unter dem das gewünschte Element in den Ressourcen abgelegt ist.

Wenn Ressourcen im Code verwendet werden sollen, z.B. um dynamische Meldungstexte auszugeben, verwendet man dazu die GetGlobalResourceObject-Methode. Zum Festlegen des Seitentitels kann das z.B. so aussehen:

this.Title = GetGlobalResourceObject("AppRes", "PageTitle").ToString();

Ähnlich wie oben steht hier der erste Parameter für den Namen der Ressourcendatei ohne Kultur und ohne die resx-Erweiterung. Der zweite Parameter bezeichnet den Schlüssel, unter dem das gewünschte Element in den Ressourcen abgelegt ist.