次の方法で共有


コンポーネント ライブラリのリソースのローカライズの概要

更新 : 2007 年 11 月

ローカリゼーションとは、特定の言語およびカルチャを対象にアプリケーションをカスタマイズするプロセスです。ASP.NET の AJAX 機能では、クライアント スクリプトを実行するための、以下のローカリゼーション モデルがサポートされています。

  • .NET Framework のリソース モデル。ECMAScript (JavaScript) コンポーネントに関連付けられたローカライズ済みリソースのサポートが拡張されています。このモデルでは、スクリプト ファイルとローカライズされたスクリプト リソースをアセンブリのハブ アンド スポーク編成 (つまりサテライト アセンブリ) に埋め込みます。これにより、特定の言語および地域に対して、埋め込まれたクライアント スクリプトとリソースを選択的に使用できます。このモデルにより、単一のコード ベースで複数のカルチャをサポートできます。

  • ディスク上の静的な (スタンドアロン) JavaScript ファイル。このモデルでは、ローカライズされたファイルはアセンブリに埋め込まれず、.js ファイルとして 1 つのディレクトリにグループ化されます。

  • 静的な JavaScript ファイルの使用による、アセンブリに埋め込まれたスクリプトおよびスクリプト リソースの更新。このモデルにより、オリジナルのアセンブリを変更することなく、埋め込まれたスクリプトおよびリソースに対するローカリゼーション サポートを追加できます。

このトピックは、次の内容で構成されています。

  • シナリオ

  • 背景

  • アセンブリ内のクライアント スクリプトおよびスクリプト リソースのローカライズ

  • 静的なスクリプト ファイルおよびそのリソースのローカライズ

  • ScriptManager を使用したスクリプトの中央管理

  • コード例

  • クラス リファレンス

シナリオ

ページ作成者とコンポーネント開発者の両者にとって、ASP.NET の AJAX 機能はクライアント スクリプトのローカライズに役立ちます。一般に、ページ作成者は以下のローカライズを行います。

  • ブラウザの言語設定に基づいて ASP.NET AJAX またはコンポーネント ライブラリから生成される例外メッセージ。

  • Button コントロールの Text プロパティの文字列など、コントロールの UI。

  • ASP.NET AJAX サーバー コントロールのパブリック プロパティの値。

  • 非ビジュアルのコンポーネント、動作、コントロールなど、クライアント スクリプトのオブジェクトおよびコンポーネントのプロパティの値

一般に、コンポーネント開発者はローカリゼーション機能を以下の目的で使用します。

  • JavaScript ライブラリ (.js ファイル) 内のコードで参照されるリソースのローカライズ。ローカライズされたリソースは、メイン アセンブリまたはスクリプト ライブラリをリビルドすることなく、個別のインストールに配置できます。

  • クライアント オブジェクトのプロパティにマップされる、サーバー コントロールのローカライズ可能なプロパティの公開。

背景

ASP.NET の AJAX 機能は、ASP.NET 2.0 ローカリゼーション モデルに基づいています。この機能により、アセンブリ内またはディスク上の静的な .js ファイル内に埋め込まれたローカライズ済みスクリプト ファイルのサポートが追加されます。

ASP.NET のローカリゼーション モデルに詳しくない場合は、次のトピックの情報を参考にしてください。

アセンブリ内のクライアント スクリプト ファイルおよびスクリプト リソースのローカライズ

ASP.NET の AJAX 機能は、ローカライズについて .NET Framework のリソース モデルを採用しています。このモデルでは、ハブ アンド スポーク方式を使用して、インクリメンタル更新が可能なローカライズされたリソースのパッケージ化と配置を行います。ハブは、ローカライズされていない実行可能コードを含むメイン アセンブリです。これには、.NET Framework サーバー コードと、アセンブリにリソースとして埋め込まれた .js ファイル内のすべての JavaScript コードの両方が含まれます。

メイン アセンブリには、単一のカルチャ用のリソースを含めることもできます。このようなリソースは、ニュートラル カルチャまたは既定のカルチャとして参照されます。ニュートラル カルチャは、アプリケーションで使用されるフォールバック カルチャです。これは、カルチャが指定されていない場合、または指定したカルチャのリソースが存在しない場合に使用されます。

通常、1 つのカルチャ用にローカライズされるリソースは、名前と値のペアとして .resx ファイルに作成されます (これらの .resx ファイルは、.resources ファイルにコンパイルできます)。名前を指定することで、コード内の情報へのアクセスが可能になります。値は、その名前で識別されるローカライズ (翻訳) された用語、イメージ、またはその他の要素です。アセンブリをビルドすると、.resx ファイルに対応する型が生成されます。各名前は、プログラムによる値へのアクセスを提供するフィールドとしてこの型で公開されます。生成される型の名前は、後で説明するように、アセンブリのプロパティの一部として指定します。

ハブ アンド スポーク モデルでは、各スポークは、単一のカルチャ用のリソースを含むサテライト アセンブリにつながります。サテライト アセンブリには、サーバーで実行されるコードは含まれません。含まれるのは、カルチャのリソース値へのプログラムによるアクセスを提供する、生成された型だけです。

このモデルは、次の機能を提供します。

  • アセンブリを配置した後、新しいサテライト アセンブリを配置することにより、新しいカルチャ用のリソースを追加できます。カルチャ固有のリソースの開発には、余分な時間を要する場合があります。このモデルでは、まずメイン アプリケーションをリリースでき、その後でカルチャ固有のリソースを配信します。

  • メイン アプリケーションを再コンパイルしなくても、アプリケーションのサテライト アセンブリを更新できます。

  • アプリケーションは、メイン アプリケーションをアンロードおよび再読み込みする必要はなく、特定のカルチャのサテライト アセンブリだけを読み込みます。このため、システム リソースの使用率を大幅に下げることができます。

ASP.NET 用のリソース ファイルを作成する方法の詳細については、「方法 : ASP.NET Web サイトに対してリソース ファイルを作成する (Visual Studio)」および「リソースを使用した ASP.NET Web ページのローカライズ」を参照してください。

.NET Framework のリソース ファイル ジェネレータ (Resgen.exe) ツールの使用方法の詳細については、「リソース ファイル ジェネレータ (Resgen.exe)」を参照してください。このツールは、.resx ファイルまたは .txt ファイルを、アセンブリにリンクできるバイナリの .resources ファイルに変換します。

ローカライズされたメイン アセンブリとサテライト アセンブリの編成

JavaScript (.js) ファイルを含むアプリケーションをローカライズする場合は、ハブ アンド スポーク モデルを使用できます。一般に、アセンブリはローカライズされた ASP.NET アプリケーションと同じように編成されます。

AJAX 対応の ASP.NET Web アプリケーション用の JavaScript ファイルを管理するには、ローカライズが必要な文字列またはその他の要素をハードコーディングしないように JavaScript コードを記述します。代わりに、JavaScript コードでローカライズされた値を使用する必要がある場所では、リソース ファイルから生成される型からフィールドを取得します。

通常、メイン アセンブリには以下の要素が含まれます。

  • アプリケーション タスクを実行する JavaScript ファイル。ハードコーディングされたリソースではなく、ローカライズされたリソースを使用するように記述されています。アセンブリには、これらの JavaScript ファイルのデバッグ バージョンをオプションとして含めることもできます。

  • オプションで、単一のニュートラル カルチャ用のリソース (.resx ファイルまたは .resources ファイル)。これらのリソースは、アプリケーションのフォールバック カルチャとしてとして機能します。

  • オプションで、ニュートラル カルチャ用のリソースのデバッグ バージョン。デバッグ バージョンのリソース ファイルには、デバッグ バージョンの JavaScript ファイルで必要となる追加の名前と値のペアが含まれます。

通常、サテライト アセンブリには、ASP.NET アプリケーション用の単一カルチャ用にローカライズされたリソースが含まれます。フォールバック カルチャにはサテライト アセンブリは不要です。単一カルチャ用のリソースは、個別のリソース ファイル (.resx ファイルまたは .resources ファイル) に作成された後、単一のサテライト アセンブリにコンパイルされます。

Bb398937.alert_note(ja-jp,VS.90).gifメモ :

ASP.NET を使用すると、カスタム UI カルチャおよびカスタム カルチャ名を作成できます。ただし、カルチャ名は通常、言語を表す 2 桁の文字と国または地域を表す 2 桁の大文字で構成される ISO 言語コードによって決まります。たとえば、es-MX (スペイン語、メキシコ)、es-CO (スペイン語、コロンビア)、fr-CA (フランス語、カナダ) などがその例です。すべてのカルチャ名の一覧については、System.Globalization.CultureInfo クラスの概要を参照してください。

ローカライズされて埋め込まれたスクリプト ファイルの名前

ローカライズされ、リソースとして埋め込まれるスクリプト ファイルには、次の名前付け規則を適用することをお勧めします。

scriptname_noextension.[debug].[UI culture identifier].[resources|resx]

デバッグ バージョンのファイル名は、".debug" を含みます。リリース バージョンは含みません。

この名前付け規則の例を次の表に示します。これらの例は、埋め込まれるスクリプト ファイルのリリース バージョンとデバッグ バージョンを示しています。また、それらのスクリプト ファイルに関連付けられているリソースのリリース バージョンとデバッグ バージョンも示しています。

  • Sample.js
    ニュートラル カルチャのスクリプト ファイルのリリース バージョンです。これはメイン アセンブリに埋め込まれます。

  • Sample.debug.js
    ニュートラル カルチャのスクリプト ファイルのデバッグ バージョンです。これもメイン アセンブリに埋め込まれます。

  • Sample.fr-FR.resources
    スクリプト ファイル Sample.js に関連付けられているリソースのリリース バージョンです。特定の UI カルチャ用にローカライズされています。これらのリソースは、サテライト アセンブリの一部になります。

  • Sample.debug.fr-FR.resources
    スクリプト ファイル Sample.debug.js に関連付けられているデバッグ固有のリソースです。特定の UI カルチャ用にローカライズされています。これらのリソースは、Sample.fr-FR.resources ファイルを含むサテライト アセンブリの一部になります。

この名前付け規則は、アセンブリに埋め込まれているスクリプト ファイルまたはリソース ファイルに対して厳密に要求されるわけではありません。これは、リソース用に生成された型とリソース名との対応付けが、アセンブリ属性の使用によって完了するためです。

デバッグ スクリプト リソースのローカライズ

デバッグ モードで作業している場合、ASP.NET は実行時に、スクリプト ファイルのリリース バージョンのリソースを追加のデバッグ リソースと結合します。次に、結合された組み合わせをブラウザに送信します。したがって、デバッグ バージョンのスクリプト用にリソース ファイルを作成する場合、定義する必要のあるリソースは、リリース バージョンのスクリプト リソース ファイルに含まれていない名前と値のペアだけです。名前付け規則により、デバッグ バージョンのスクリプトおよびスクリプト リソースでは、対応するリリース バージョンと同じ名前が使用されますが、スクリプト ファイル名の後に ".debug" が付きます。

スクリプトに関連付けられたローカライズ済みのスクリプトおよびリソースのアセンブリ属性の指定

アセンブリのビルド時にリソース ファイルがどのように管理されるかを指定するには、AssemblyInfo ファイル (AssemblyInfo.vb ファイルまたは AssemblyInfo.cs ファイル) に属性を含めます。

Bb398937.alert_note(ja-jp,VS.90).gifメモ :

Visual Studio では、Visual Basic で記述されたプロジェクトの AssemblyInfo.vb ファイルは、ソリューション エクスプローラ[My Project] ノードにあります。[My Project] ノードにファイルが表示されない場合は、[プロジェクト] メニューの [すべてのファイルを表示] をクリックします。C# で記述されたプロジェクトの AssemblyInfo.cs ファイルは、ソリューション エクスプローラ[プロパティ] ノードにあります。

ASP.NET では、WebResourceAttribute クラスを使用してアプリケーションのリソースをマークします。JavaScript ファイルをアセンブリに埋め込むには、この属性を使用して .js ファイルを Web リソースとして指定します。

埋め込まれた JavaScript ファイルのリソース ファイルを含めるには、ScriptResourceAttribute クラスを使用します。この属性は、テキスト ベースのリソースを JavaScript ファイル用のリソースとして識別します。

Bb398937.alert_note(ja-jp,VS.90).gifメモ :

ScriptResourceAttribute クラスは、テキスト ベースのリソースのみを JavaScript ファイル用のリソースとして識別する場合に使用できます。ローカライズされたイメージ (バイナリ) ファイルをカルチャに関連付けるには、スクリプトが解決および読み込み可能なローカライズされたリソースとしてファイルの URL を格納します。

アセンブリ属性を使用して、埋め込みスクリプトとそれに関連付けられたスクリプト リソースを識別する方法を次の例に示します。

' Indicates that neutral fallback resources are retrieved from 
' the main assembly named MainAssembly.
<assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)>

' Defines embedded scripts as Web resources.
<assembly:WebResource("Sample.js", "text/javascript")>
<assembly:WebResource("Sample.debug.js", "text/javascript")>

' Defines the script resources for the scripts and their types.
<assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")>
<assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")>
// Indicates that neutral fallback resources are retrieved from 
// the main assembly named MainAssembly.

[assembly: NeutralResourcesLanguageAttribute("en-US",
  UltimateResourceFallbackLocation.MainAssembly)]

// Defines embedded scripts as Web resources.
[assembly:WebResource("Sample.js", "text/javascript")]
[assembly:WebResource("Sample.debug.js", "text/javascript")]

// Defines the script resources for the scripts and their types.
[assembly:ScriptResource("Sample.js", "Sample.resources", 
  "Sample.Res")]
[assembly:ScriptResource("Sample.debug.js", "Sample.debug.resources", 
  "Sample.Res")]

この例では、Sample.js という名前のクライアント スクリプト ファイルの埋め込まれたリリース バージョンが、MainAssembly という名前のメイン アセンブリに含まれています。このアセンブリには、Sample.debug.js という名前の対応するデバッグ バージョンも含まれています。.js ファイルは、WebResourceAttribute 属性によりリソースとして識別されます。

NeutralResourcesLanguageAttribute アセンブリ属性は、フォールバック カルチャとしてメイン アセンブリを指定する際に使用されます。詳細については、「ローカリゼーションのニュートラル リソース言語」および System.Resources.NeutralResourcesLanguageAttribute クラスの概要を参照してください。

スクリプト ファイルで使用されるリソースは、ScriptResourceAttribute 属性によって定義されます。Sample.resources ファイルおよび Sample.debug.resources ファイルには、それそれ Sample.js ファイルおよび Sample.debug.js ファイルのリソース値が含まれます。

リリース バージョンとデバッグ バージョンの両方のスクリプト リソースに対して、Sample.Res という名前の型が生成されます。これは、JavaScript コードがローカライズされた値にアクセスするときに使用する型です。ビルド処理では、リリース モードおよびデバック モードの両方に対して単一の型のみが作成されます。デバッグ モードでは、リリース バージョンのリソースが、デバッグ バージョンの追加のリソースと結合されます。

バージョン付きアセンブリに必要なアセンブリ情報ファイルおよびアセンブリ メタデータの作成方法の詳細については、「方法 : プリコンパイルされた Web サイトのバージョン付きアセンブリを作成する」を参照してください。

静的なスクリプト ファイルおよびそのリソースのローカライズ

スクリプト ライブラリをアセンブリに埋め込む代わりに、ディスク上のローカライズされた静的なスクリプト ファイル (.js ファイル) として編成することができます。ページの作成者は、ScriptReferenceCollection クラスを通じてスクリプト ファイルを参照できます。

静的なスクリプト ファイル モデルには、JavaScript ファイル用のリソースとして自動的に管理できる個別の .resx ファイルまたは .resources ファイルはありません。代わりに、すべての UI カルチャとロケールの組み合わせで使用できる .js ファイルがあります。実際には、各 .js ファイルは、JavaScript コード全体の中のロケール固有のバージョンを表します。このモデルでローカライズされたスクリプト ファイルを管理する一般的な方法は、各 .js ファイルで同じ JavaScript ロジックを使用する方法です。アセンブリへの埋め込みモデルと同様に、JavaScript コードでも、ローカライズされたリソース値を取得するために型を呼び出します。ただし、ローカライズされた値を格納する型を用意する必要があるという点が異なります。この型は自動的には生成されません。たとえば、各ロケール用の .js には、アプリケーション コードと、ローカライズされた値を保持するフィールドを定義するクラスの両方を含めることができます。それぞれの .js ファイルでは、このクラスに異なる言語の値が含まれることになります。

Bb398937.alert_note(ja-jp,VS.90).gifメモ :

静的なスクリプト ファイル モデルでは、.js ファイル内のアプリケーション JavaScript コードが、埋め込まれている JavaScript ファイルと同期されないことがあります。これは、各スクリプト ファイルにコードのコピーが含まれているためです。バージョン管理におけるコードの重複の問題を回避するには、JavaScript ソース ファイルのコピーを 1 つだけ保持するようにして、ローカライズしたリソースの型は別のファイルに作成します。アプリケーションのビルド処理で、最終的な結合ファイルを生成できます。

アセンブリ内の埋め込みリソースと同様に、ローカライズされた静的なスクリプト ファイルは、ファイル名の一部に UI カルチャ名を含めることで、その UI カルチャに対応付けることができます。たとえば、カルチャがニュートラルのフランス語の埋め込みクライアント スクリプト ファイルには Sample.fr.js という名前を付け、カルチャ固有のフランス語 (カナダ) の JavaScript リソースに Sample.fr-CA.js という名前を付けます。

静的なスクリプト ファイル モデルにおけるローカライズされたデバッグ スクリプト

静的なスクリプト ファイル モデルでは、スクリプトの参照先となるローカライズされたリソースは、通常は 1 つの .js ファイルで型として定義されます。デバッグ バージョンのスクリプト ファイルも同じように編成され、ローカライズされたリリース リソースと追加のデバック リソースの両方が、1 つのファイルで型として定義されます。デバッグバージョンのスクリプトでは、対応するリリースバージョンと同じ名前が使用されますが、ファイル名の後ろに ".debug" が付きます。

ScriptManager を使用したスクリプトの管理

ScriptManager コントロールを使用すると、ディスク上の中央ディレクトリに配置された静的なスクリプトを管理できます。このためには、スクリプト ファイルのすべてのバージョンを 1 つのフォルダに配置して、ローカライズされたすべてのファイルのリリース バージョンとデバッグバージョンをその中に含めます。静的なスクリプト ファイル ライブラリのディレクトリ構造のレイアウトを次の例に示します。

SampleNamespace/

1.0.0.0/

Sample.js

Sample.debug.js

Sample.de-DE.js

Sample.debug.de-DE.js

Sample.fr-FR.js

Sample.debug.fr-FR.js

この例では、すべてのスクリプト ファイルは、スクリプト ライブラリのバージョン (1.0.0.0) を名前とするフォルダに格納されています。このバージョン固有のフォルダは、ライブラリの名前空間に基づいた名前のフォルダに含まれています。スクリプト ライブラリを名前空間とバージョンに基づいてフォルダに編成することで、ライブラリのバージョンをある程度管理できます。これは、ライブラリ間のスクリプト名の衝突の回避にも役立ちます。また、ライブラリのコンシューマは、ファイルが属するライブラリおよびライブラリのバージョンを識別できるようになります。

ローカリゼーションにおける ScriptManager コントロールの役割の理解

ScriptManager コントロールには、ローカライズされたスクリプトおよびスクリプト リソースを使用するための次の機能が用意されています。

  • カスタム UI カルチャも含め、サポート対象の UI カルチャを定義できます。

  • カルチャ固有のアセンブリ属性を解釈し、ブラウザの UI カルチャ (ある場合) を自動的に検出します。次に、アセンブリからローカライズ済みまたはフォールバックのスクリプトとリソースを読み取ります。デバッグ モードでは、適切な UI カルチャ名およびファイル名の ".debug" 文字列 (Sample.debug.fr-FR.resources など) の両方を含むスクリプト リソースの読み込みを試みます。

  • 適切なスクリプトおよびそのローカライズされたリソースを指す URL を生成します。セキュリティを強化する場合には、URL を暗号化します。

  • 生成された URL のパラメータに基づき、スクリプトまたはスクリプト リソースを圧縮するかどうかを判断します。

  • ブラウザによってスクリプトが無制限にキャッシュされないように、埋め込みスクリプトを含むアセンブリにタイムスタンプを追加します。

詳細については、ScriptManager クラスの概要を参照してください。

次の例は、ScriptManager コントロールを使用して、アセンブリに配置されたクライアント コントロールを登録する Web ページの一部を示しています。埋め込みスクリプトは、Assembly プロパティおよび Name プロパティを使用して登録されます。

<%@ Register TagPrefix="Samples" Namespace="DemoControls" 
  Assembly=" SampleAssembly" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
  <title>ScriptReference</title>
</head>
<body>
  <form id="form1" runat="server">
    <div>
      <asp:ScriptManager ID="ScriptManager1" runat="server">
        <Scripts>
          <asp:ScriptReference Assembly="SampleAssembly"
              Name="DemoControls.SampleControl.js" />
        </Scripts>
      </asp:ScriptManager>

      <!-- Additional markup here. -->

    </div>
  </form>
</body>

コード例

次のセクションでは、JavaScript ファイルおよびリソースを操作するコード例を示します。

"方法" トピックと "チュートリアル" トピック

クラス リファレンス

コンポーネント ライブラリのローカライズに使用される主要なクラスの一覧を次の表に示します。

  • ScriptManager
    AJAX コンポーネント、部分ページ レンダリング、クライアント要求、および ASP.NET サーバー ページでのサーバー応答を管理します。

  • ScriptReference
    Web ページ内で使用する JavaScript ファイルを登録するための API を提供します。JavaScript ファイルは、アセンブリに埋め込まれたファイル、またはディスク上のファイルのどちらかになります。

  • ScriptReferenceCollection
    クライアント スクリプト ファイルを表す ScriptReference オブジェクトへのアクセスを提供します。

参照

処理手順

カスタムの非ビジュアル クライアント コンポーネントの作成

方法 : ASP.NET Web サイトに対してリソース ファイルを作成する (Visual Studio)

方法 : プリコンパイルされた Web サイトのバージョン付きアセンブリを作成する

スクリプト参照の動的な割り当て

概念

ASP.NET Web ページのリソースの概要

参照

リソース ファイル ジェネレータ (Resgen.exe)

その他の技術情報

リソースを使用した ASP.NET Web ページのローカライズ