元件庫資源當地語系化概觀

發行項
10/22/2014

更新：2007 年 11 月

當地語系化是為特定的語言與文化特性 (Culture) 自訂應用程式的過程。ASP.NET 的 AJAX 功能支援用戶端指令碼使用下列當地語系化模型：

.NET Framework 資源模型，可為 ECMAScript (JavaScript) 元件相關聯的當地語系化資源提供更多的支援。在此模型中，您可將指令碼檔案與當地語系化的指令碼資源內嵌在組件 (亦即使用附屬組件) 的集線器及網幅組織中。接著，您可以選擇性地使用這些特定語言與區域的內嵌用戶端指令碼與資源。這個模型會啟用單一程式碼基底 (Code Base) 來支援多重文化特性。
磁碟上的靜態 (獨立) JavaScript 檔案。在此模型中，當地語系化的檔案會歸類到單一目錄成為 .js 檔案，而不是內嵌到組件裡。
使用靜態 JavaScript 檔案來更新內嵌到組件的指令碼與指令碼資源。此模型可讓您針對內嵌指令碼與內嵌資源提供額外的當地語系化支援，無須對原始組件進行任何變更。

本主題包含下列資訊：

案例
背景
當地語系化組件中的用戶端指令碼和指令碼資源
當地語系化靜態指令碼檔案與其資源
使用 ScriptManager 來管理集中位置的指令碼
程式碼範例
類別參考

案例

ASP.NET 中的 AJAX 功能可同時協助網頁開發人員和電腦開發人員進行用戶端當地語系化作業。網頁開發人員通常會對下列項目進行當地語系化：

根據瀏覽器的語言設定，由 ASP.NET AJAX 或元件庫所產生的例外狀況訊息。
控制項所需的 UI，例如 Button 控制項之 Text 屬性的字串。
ASP.NET AJAX 伺服器控制項之公用屬性值。
用戶端指令碼物件與元件的屬性值，例如隱藏式 (Non-Visual) 元件、行為與控制項等。

元件開發人員通常會針對下列項目使用當地語系化功能：

當地語系化 JavaScript 程式庫 (.js 檔案) 中的程式碼參考資源。當地語系化的資源可以部署在不同的安裝項目中，而不用重新建置主要的組件或指令碼程式庫。
公開對應至用戶端物件屬性的可當地語系化之伺服器控制項屬性。

背景

ASP.NET 中的 AJAX 功能以 ASP.NET 2.0 當地語系化模型為基礎。它可對內嵌在組件或磁碟上靜態 .js 檔案的當地語系化指令碼檔案提供額外支援。

如果您不熟悉 ASP.NET 當地語系化模型，可以在下列主題中找到一些相關資訊：

當地語系化在組件中的用戶端指令碼檔案和指令碼資源

ASP.NET AJAX 功能會充分運用 .NET Framework 資源模型的優點來進行當地語系化。此模型透過集線器及網幅安排，針對能夠累加更新的當地語系化資源進行封裝與部署。集線器這個主要組件包含了非當地語系化的可執行程式碼，並將 .NET Framework 伺服端程式碼與任何 JavaScript 程式碼同時內嵌到 .js 檔案中做為組件中的資源。

此主要組件可同時包含單一文化特性的資源，稱為「中性」(Neutral) 或「預設」(Default) 文化特性。中性文化特性為應用程式的後援文化特性。如果未指定任何文化特性，或未在指定的文化特性中使用任何資源的話，就會使用此特性。

文化特性的當地語系化資源通常會在 .resx 檔案中以名稱/值組的方式建立 (這些 .resx 檔案可以編譯為 .resources 檔)。名稱可對程式碼中的資訊提供存取權，而值則是當地語系化 (翻譯過) 的詞彙、影像，或其他屬於該名稱的項目。建置組件時，會針對 .resx 檔案產生一種型別，並將其中的名稱公開為欄位，以便針對值提供程式設計存取 (您可以將產生的型別名稱指定為組件屬性的一部分，如稍後所述)。

在集線器與網輻模型中，每個網輻都連接至含有單一文化特性資源的附屬組件。附屬組件不包含伺服器能夠執行的任何程式碼。它只包含產生的型別，以針對該文化特性以程式設計方式提供資源值的存取。

此模型提供下列功能：

在您部署組件之後，可以部署新的附屬組件，為新的文化特性加入更多資源。開發文化特性專屬的資源需要額外的時間。因此，此模型能夠讓您先釋放主應用程式，以便稍後遞送額外的文化特性專屬資源。
您可以更新應用程式的附屬組件，而不需重新主要組件。
應用程式只需針對特定文化特性載入附屬組件，不用卸載並重新載入主要組件。這大幅降低系統資源的使用。

如需如何建立 ASP.NET 資源檔的詳細資訊，請參閱 HOW TO：建立 ASP.NET Web 網頁的資源檔 (Visual Studio)和使用資源將 ASP.NET 網頁當地語系化。

如需如何使用 .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 檔) 中，然後編譯為單一附屬組件。

注意事項：
ASP.NET 可讓您建立自訂 UI 文化特性與自訂文化特性名稱。然而，文化特性名稱通常是以 ISO 語言代碼為基礎，此代碼由代表語言的兩個字母，以及代表國家或地區的兩個大寫字母所組成。範例包括了 es-MX (墨西哥西班牙文)、es-CO (哥倫比亞西班牙文) 及 fr-CA (加拿大法文)。如需完整的文化特性名稱清單，請參閱 System.Globalization.CultureInfo 類別概觀。

ASP.NET 可讓您建立自訂 UI 文化特性與自訂文化特性名稱。然而，文化特性名稱通常是以 ISO 語言代碼為基礎，此代碼由代表語言的兩個字母，以及代表國家或地區的兩個大寫字母所組成。範例包括了 es-MX (墨西哥西班牙文)、es-CO (哥倫比亞西班牙文) 及 fr-CA (加拿大法文)。如需完整的文化特性名稱清單，請參閱 System.Globalization.CultureInfo 類別概觀。

當地語系化的內嵌指令碼檔案名稱

建議您遵守下列命名規範，來處理內嵌為資源的當地語系化指令碼檔案：

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

檔案名稱的偵錯版本會在名稱裡包含 ".debug"。發行版本 (Release Version) 則不會這麼做。

下表列出此命名規範的一些範例。這些範例說明了內嵌指令碼檔案的發行版本與偵錯版本，並同時針對這些指令碼檔案資源說明其相關的正式與偵錯版本。

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 檔)。

注意事項：
在 Visual Studio 中，如果是以 Visual Basic 撰寫的專案，則其 AssemblyInfo.vb 檔案位於 [方案總管] 的 [我的專案] 節點中。如果您沒有在 [我的專案] 節點內看到任何檔案，請按一下 [專案] 功能表上的 [顯示所有檔案]。如果是以 C# 撰寫的專案，則其 AssemblyInfo.cs 檔案位於 [方案總管] 的 [屬性] 節點中。

在 Visual Studio 中，如果是以 Visual Basic 撰寫的專案，則其 AssemblyInfo.vb 檔案位於 [方案總管] 的 [我的專案] 節點中。如果您沒有在 [我的專案] 節點內看到任何檔案，請按一下 [專案] 功能表上的 [顯示所有檔案]。如果是以 C# 撰寫的專案，則其 AssemblyInfo.cs 檔案位於 [方案總管] 的 [屬性] 節點中。

在 ASP.NET 中，您可以使用 WebResourceAttribute 類別來標記應用程式的資源。若要將 JavaScript 檔案內嵌在組件中，您可以使用此屬性將 .js 檔案指定為 Web 資源。

若要將資源檔包含在內嵌的 JavaScript 檔案中，可以使用 ScriptResourceAttribute 類別。此屬性會將文字基礎的資源特別識別為 JavaScript 檔案的資源。

注意事項：
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")]

在此範例中，名為 MainAssembly 的主要組件包含名為 Sample.js 之用戶端指令碼檔案的內嵌發行版本。此組件同時包含名為 Sample.debug.js 的對應偵錯版本。WebResourceAttribute 屬性會將此 .js 檔案識別為資源。

NeutralResourcesLanguageAttribute 組件屬性可用來指定主要組件做為後援文化特性。如需詳細資訊，請參閱當地語系化的中性資源語言與 System.Resources.NeutralResourcesLanguageAttribute 類別概觀。

指令碼檔案所使用的資源可透過 ScriptResourceAttribute 屬性加以定義。Sample.resources 和 Sample.debug.resources 檔分別包含 Sample.js 和 Sample.debug.js 檔的資源值。

指令碼資源的發行與偵錯版本會同時產生名為 Sample.Res 的型別，以供 JavaScript 程式碼用來存取當地語系化值。在發行模式與偵錯模式中，建置處理序都只會建立單一型別。在偵錯模式中，發行版本的資源會與偵錯版本的額外資源結合起來。

如需如何建立組件資訊檔與指定組件版本所需組件中繼資料的詳細資訊，請參閱 HOW TO：建立先行編譯網站的建立版本組件。

當地語系化靜態指令碼檔案與其資源

您可以將指令碼程式庫組織為磁碟上當地語系化的靜態指令碼檔案 (.js 檔案)，而不需將指令碼檔案內嵌在組件中。網頁開發人員可以透過 ScriptReferenceCollection 類別參考指令碼檔案。

在靜態指令碼檔案模型中，您無法將任何單一的 .resx 或 .resources 當成 JavaScript 檔案資源來自動管理。反之，這當中只存在 .js 檔案，以因應每個 UI 文化特性和地區設定組合的需要。事實上，每個 .js 檔案都代表完整 JavaScript 程式碼的特定地區設定版本。管理此模型中當地語系化指令碼檔案的傳統方式，就是在每個 .js 檔案中使用相同的 JavaScript 邏輯。就像在組件內嵌模型中一樣，JavaScript 程式碼會叫用型別以擷取當地語系化的資源值。不同的是，您必須提供包含當地語系化值的型別，而此型別並不會自動為您產生。例如，每個區域設定的 .js 檔可同時包含應用程式程式碼與類別 (此類別可定義欄位以保存當地語系化值)。在每個 .js 檔案中，此類別包含不同語言的值。

注意事項：
在靜態指令碼檔案模型中，.js 檔案中的應用程式 JavaScript 程式碼可能與內嵌 JavaScript 檔案的程式碼不同步。這是因為每個指令碼檔案都包含一個程式碼複本。為了避免出現程式碼重複的版本控管問題，您可以維護一份 JavaScript 原始程式檔複本，並在其他檔案中建立當地語系化的資源型別。接著您可以在應用程式的建置處理序其間產生最後組合的檔案。

在靜態指令碼檔案模型中，.js 檔案中的應用程式 JavaScript 程式碼可能與內嵌 JavaScript 檔案的程式碼不同步。這是因為每個指令碼檔案都包含一個程式碼複本。為了避免出現程式碼重複的版本控管問題，您可以維護一份 JavaScript 原始程式檔複本，並在其他檔案中建立當地語系化的資源型別。接著您可以在應用程式的建置處理序其間產生最後組合的檔案。

當地語系化的靜態指令碼檔案會對應至本身的 UI 文化特性中，方法是將 UI 文化特性名稱當成檔名的一部分納入，如同將資源內嵌在組件中一樣。例如，對於法文來說具有中性文化特性的內嵌用戶端指令碼檔案會稱為 Sample.fr.js，而對於法文 (加拿大) 具有專屬文化特性的 JavaScript 資源則稱為 Sample.fr-CA.js。

當地語系化靜態指令碼檔案模型中的偵錯指令碼

在靜態指令碼檔案模型中，指令碼所指的當地語系化資源一般會定義為單一 .js 檔案中的型別。指令碼檔案的偵錯版本會以相同方式來組織，並同時將當地語系化的發行資源與額外的偵錯資源定義為單一檔案中的型別。指令碼的偵錯版本會與對應發行版本使用相同的名稱，但會在名稱後面加上 ".debug"。

使用 ScriptManager 來管理指令碼

您可以使用 ScriptManager 控制項來管理位於磁碟中央目錄的靜態指令碼。若要這麼做，請將所有版本的指令碼檔案放在同一個資料夾，內含當地語系化檔案的所有發行與偵錯版本。下列範例說明靜態指令碼檔案程式庫的目錄結構配置：

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 >
  <title>ScriptReference</title>
</head>
<body>
  <form id="form1" >
    <div>
      <asp:ScriptManager ID="ScriptManager1" >
        <Scripts>
          <asp:ScriptReference Assembly="SampleAssembly"
              Name="DemoControls.SampleControl.js" />
        </Scripts>
      </asp:ScriptManager>

      <!-- Additional markup here. -->

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

程式碼範例

下列章節包含一些程式碼範例，說明如何使用 JavaScript 檔案和資源。

HOW TO 和逐步解說主題

類別參考

下表列出用於當地語系化元件程式庫的重要類別。

ScriptManager
管理 AJAX 元件、網頁局部呈現、用戶端要求，以及 ASP.NET 伺服器網頁上的伺服器回應。
ScriptReference
提供 API 以便註冊要用於 Web 網頁的 JavaScript 檔案，這些檔案可以是內嵌於組件中，或是位於磁碟上的檔案。
ScriptReferenceCollection
針對代表用戶端指令碼檔案的 ScriptReference 物件提供存取。

請參閱

共用方式為