UI 要素をローカライズするサンプル SharePoint アドイン
Core.JavaScriptCustomization サンプル アドインは、JavaScript を使用して、SharePoint UI 要素のテキスト値を JavaScript リソース ファイルから読み込んだ翻訳済みのテキスト値に置き換える方法を示します。
注:
JavaScript リソース ファイル内の翻訳済みのテキスト値の保守を行う必要があります。
重要
JSLink ベースのカスタマイズ (クライアント側のレンダリング) は最新のエクスペリエンスではサポートされていません。 これには、最新のページのリスト ビュー Web パーツでの JSLink サポートなど、最新のリストとライブラリが含まれます。 クライアント側のレンダリングは、SharePoint Online またはオンプレミスの従来のエクスペリエンスではサポートされています。
このコード サンプルでは、プロバイダー ホスト型アドインを使用して以下の操作を実行します。
- 特定のテキスト値でサイト ページや [クイック起動] リンクのタイトルをローカライズします。
- 主言語でサイト ページと [クイック起動] リンクのタイトルを保存し、実行時に別の言語で翻訳されたバージョンのサイト ページと [クイック起動] リンクのタイトルを表示します。
- JavaScript リソース ファイルを使用してクライアント側をローカライズします。
- カスタム アクションを使用して JavaScript ファイルを SharePoint サイトにリンクします。
- サイトの UI カルチャを調べてから、カルチャ固有のテキスト値を JavaScript リソース ファイルから読み込みます。
- JQuery を使用して、カルチャ固有のテキスト値でサイト ページと [クイック起動] リンクのタイトルを上書きします。
はじめに
まず、Core.JavaScriptCustomization サンプル アドインを、GitHub 上の Office 365 Developer Patterns and Practices プロジェクトからダウンロードします。
このコード サンプルを実行する前に、以下の手順を完了してください。
サイトで言語設定を構成する
チーム サイトで、[設定]>[サイトの設定] を選択します。
[サイトの管理] で、[言語設定] を選択します。
[言語設定] ページの [第 2 言語] で、サイトでサポートする第 2 言語を選択します。 たとえば、次の図に示すように [フィンランド語] と [フランス語] を選択します。
[OK] をクリックします。
ユーザーのプロファイル ページで表示言語を設定する
Office 365 サイトの上部にある自分のプロファイル画像を選択して、[自己紹介] を選択します。
[自己紹介] ページで、[プロファイルの編集] を選択します。
追加オプションの省略記号 (...) を選択してから、[言語と地域] を選択します。
[表示言語] の [新しい言語の選択] リストで新しい言語を選択してから、[追加] を選択します。 たとえば、[フィンランド語] と [フランス語] を選択します。 上下の矢印ボタンを選択して、優先言語を上下に移動できます。
[すべて保存して閉じる] を選択します。
注:
選択した言語でサイトが表示されるまでに数分かかる場合があります。
重要
CSOM は新機能で定期的に更新されます。 サイト ページや [クイック起動] リンクのタイトルを更新する新機能が CSOM で提供されている場合は、ここで説明されているオプションではなく CSOM の新機能を使用することをお勧めします。
このコード サンプルのシナリオ 2 を実行する前に、以下のタスクを完了してください。
[クイック起動] リンクを作成する
ホスト Web で、[リンクの編集] を選択します。
[リンク] を選択します。
[表示するテキスト] に、My quicklaunch entry と入力します。
[アドレス] に、Web サイトの URL を入力します。
[OK]>[保存] を選択します。
サイト ページを作成する
- ホスト Web で、[サイト コンテンツ]>[サイト ページ]>[新規] を選択します。
- [新しいページ名] に、Hello SharePoint と入力します。
- [作成] を選択します。
- ページの本文に Test page と入力します。
- [保存] を選択します。
Core.JavaScriptCustomization サンプル アプリを実行する
このコード サンプルを実行すると、以下の図に示すプロバイダー ホスト型アプリケーションが表示されます。 この記事ではシナリオ 1 とシナリオ 2 について説明します。サイト ページや [クイック起動] リンクのタイトルのローカライズ版を提供するには、この 2 つのシナリオの手法を使用できます。
シナリオ 1
シナリオ 1 では、カスタム アクションを使用して、SharePoint サイトで JavaScript ファイルへの参照を追加する方法を示します。 [カスタマイズの 挿入 ] ボタンを選択すると、scenario1.aspx.cs で btnSubmit_Click メソッドが呼び出されます。 btnSubmit_Click メソッドは AddJsLink を呼び出して、ホスト Web 上のカスタム アクションを使用して JavaScript ファイルへの参照を追加します。
以下の図は、シナリオ 1 の開始ページを示しています。
注:
この記事で提供されるコードは、明示または黙示のいかなる種類の保証なしに現状のまま提供されるものであり、特定目的への適合性、商品性、権利侵害の不存在についての暗黙的な保証は一切ありません。
AddJSLink メソッドは、OfficeDevPnP.Core の JavaScriptExtensions.cs ファイルに含まれています。 AddJSLink を使用するには、カスタム アクションに割り当てる識別子を表す文字列と、ホスト Web に追加する JavaScript ファイルの URL をセミコロンで区切ったリストを含む文字列を指定する必要があります。 このコード サンプルでは、ホスト Web にステータス バーを追加する Scripts\scenario1.js への参照を追加します。
protected void btnSubmit_Click(object sender, EventArgs e)
{
var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
using (var cc = spContext.CreateUserClientContextForSPHost())
{
cc.Web.AddJsLink(Utilities.Scenario1Key, Utilities.BuildScenarioJavaScriptUrl(Utilities.Scenario1Key, this.Request));
}
}
注:
SharePoint はダウンロード最小化戦略を使って、ユーザーが SharePoint サイト上のページ間をナビゲートする際にブラウザーでダウンロードされるデータの量を減らします。 scenario1.js に含まれる次のコードは、SharePoint サイトでダウンロード最小化戦略が使用されているかどうかを確認します。ステータス バー メッセージをホスト Web に追加する JavaScript コードを実行するには、常に RemoteManager_Inject メソッドが呼び出されます。 詳細については、「ダウンロード最小化戦略の概要」を参照してください。
if ("undefined" != typeof g_MinimalDownload && g_MinimalDownload && (window.location.pathname.toLowerCase()).endsWith("/_layouts/15/start.aspx") && "undefined" != typeof asyncDeltaManager) {
// Register script for MDS if possible.
RegisterModuleInit("scenario1.js", RemoteManager_Inject); //MDS registration
RemoteManager_Inject(); //non MDS scenario
} else {
RemoteManager_Inject();
}
注:
一部の JavaScript ファイルが正常に実行されて完了するには、その前に他の JavaScript ファイルが既に読み込まれている必要がある場合があります。 RemoteManager_Inject に含まれる次のコード構成体は、scenario1.js の loadScript 関数を使用して最初に jQuery を読み込んでから、引き続き残りの JavaScript コードを実行します。
var jQuery = "https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.2.min.js";
// Load jQuery first, and then continue running the rest of the code.
loadScript(jQuery, function () {
// Add additional JavaScript code here to complete your task.
});
[サイトに戻る] を選択します。 以下の図に示されているように、scenario1.js によって追加されたステータス バー メッセージがホスト Web に表示されます。
シナリオ 2
シナリオ 2 ではシナリオ 1 の手法を使用し、UI テキストを、JavaScript リソース ファイルから読み取った翻訳済みテキストに置き換えます。 シナリオ 2 で置換されるのは、前に作成した [クイック起動] リンクのタイトル (My quicklaunch entry) とサイト ページのタイトル (Hello SharePoint) です。 シナリオ 2 では、カルチャ固有の JavaScript リソース ファイル内の変数から翻訳済みテキストの値を読み取る JavaScript ファイルをアタッチします。 その後、シナリオ 2 では UI を更新します。
以下の図は、シナリオ 2 の開始ページを示しています。
図に示されているように、[カスタマイズの挿入] を選択すると、以下の変更がサイトに適用されます。
[クイック起動] リンクのタイトル My quicklaunch entry が Contoso link に変更されます。
Hello SharePoint サイト ページのタイトルが Contoso ページ に変更されます。
注:
サイド リンク リンク タイトルとサイト ページ タイトルの値が前の図に示したものと異なる場合は、JavaScript リソース ファイルの quickLauch_Scenario2 変数と pageTitle_HelloSharePoint 変数を編集 scenario2.en-us.js または scenario2.nl-nl.js し、コード サンプルをもう一度実行します。
scenario2.en-us.js ファイルには、英語 (米国) カルチャ固有のリソースが格納されています。 scenario2.nl-nl.js ファイルには、オランダ語カルチャ固有のリソースが格納されています。 別の言語を使用してこのコード サンプルをテストする場合は、同じ命名規則に従う別の JavaScript リソース ファイルを作成することを検討してください。
シナリオ 1 と同様に、scenario2.aspx.cs の btnSubmit_Click は AddJsLink を呼び出して、Scripts\scenario2.js ファイルへの参照を追加します。 scenario2.js 内の RemoteManager_Inject 関数は、以下のタスクを実行する TranslateQuickLaunch 関数を呼び出します。
- _spPageContextInfo.currentUICultureName を使用してサイトのカルチャを決定します。
- サイトの UI カルチャに一致するカルチャ固有のリソースが格納された JavaScript リソース ファイルを読み込みます。 たとえば、サイトのカルチャが英語 (米国) の場合、scenario2.en-us.js ファイルが読み込まれます。
- クイック起動エントリを、JavaScript リソース ファイルから読み取ったquickLauch_Scenario2変数の値に置き換えます。
function RemoteManager_Inject() {
var jQuery = "https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.2.min.js";
loadScript(jQuery, function () {
SP.SOD.executeOrDelayUntilScriptLoaded(function () { TranslateQuickLaunch(); }, 'sp.js');
});
}
function TranslateQuickLaunch() {
// Load jQuery and if complete, load the JS resource file.
var scriptUrl = "";
var scriptRevision = "";
// Iterate over the scripts loaded on the page to find the scenario2 script. Then use the script URL to dynamically build the URL for the resource file to be loaded.
$('script').each(function (i, el) {
if (el.src.toLowerCase().indexOf('scenario2.js') > -1) {
scriptUrl = el.src;
scriptRevision = scriptUrl.substring(scriptUrl.indexOf('.js') + 3);
scriptUrl = scriptUrl.substring(0, scriptUrl.indexOf('.js'));
}
})
var resourcesFile = scriptUrl + "." + _spPageContextInfo.currentUICultureName.toLowerCase() + ".js" + scriptRevision;
// Load the JS resource file based on the user's language settings.
loadScript(resourcesFile, function () {
// General changes that apply to all loaded pages.
// ----------------------------------------------
// Update the Quick Launch labels.
// Note that you can use the jQuery function to iterate over all elements that match your jQuery selector.
$("span.ms-navedit-flyoutArrow").each(function () {
if (this.innerText.toLowerCase().indexOf('my quicklaunch entry') > -1) {
// Update the label.
$(this).find('.menu-item-text').text(quickLauch_Scenario2);
// Update the tooltip.
$(this).parent().attr("title", quickLauch_Scenario2);
}
});
// Page-specific changes require an IsOnPage call.
// ----------------------------------------------------------
// Change the title of the "Hello SharePoint" page.
if (IsOnPage("Hello%20SharePoint.aspx")) {
$("#DeltaPlaceHolderPageTitleInTitleArea").find("A").each(function () {
if ($(this).text().toLowerCase().indexOf("hello sharepoint") > -1) {
// Update the label.
$(this).text(pageTitle_HelloSharePoint);
// Update the tooltip.
$(this).attr("title", pageTitle_HelloSharePoint);
}
});
}
});
}