通过

组件库资源本地化概述

  • 项目

更新：2007 年 11 月

本地化是指针对特定的语言和区域性自定义应用程序的过程。ASP.NET 中的 AJAX 功能支持使用下列本地化模型来处理客户端脚本：

  • .NET Framework 资源模型，可为与 ECMAScript (JavaScript) 组件关联的本地化资源提供扩展的支持。在此模型中，脚本文件和本地化的脚本资源都嵌入在采用轮辐式组织结构的程序集中（即使用附属程序集）。这样，您可以针对特定的语言和区域，有选择性地使用这些嵌入式客户端脚本和资源。利用此模型可通过一个基本代码支持多种区域性。

  • 磁盘上的静态（独立）JavaScript 文件。在此模型中，本地化文件都作为 .js 文件组织在单个目录中，而不是嵌入在程序集中。

  • 通过静态 JavaScript 文件更新嵌入在程序集中的脚本和脚本资源。利用此模型，可为嵌入式脚本和嵌入式资源提供附加的本地化支持，而不需要对原始程序集进行任何更改。

本主题包含以下信息：

  • 方案

  • 背景

  • 本地化程序集中的客户端脚本和脚本资源

  • 本地化静态脚本文件及其资源

  • 使用 ScriptManager 在中心位置管理脚本

  • 代码示例

  • 类参考

方案

ASP.NET 中的 AJAX 功能可为页面开发人员和组件开发人员提供客户端本地化帮助。页面开发人员通常本地化下列内容：

  • ASP.NET AJAX 或组件库基于浏览器的语言设置而生成的异常消息。

  • 控件用户界面，例如 Button 控件的 Text 属性的字符串。

  • ASP.NET AJAX 服务器控件的公共属性值。

  • 客户端脚本对象和组件（例如非可视组件、行为和控件）的属性值。

组件开发人员通常在下列方面应用本地化功能：

  • 本地化 JavaScript 库（.js 文件）的代码中引用的资源。已本地化的资源可部署在单独的安装中，而无需重新生成主程序集或脚本库。

  • 公开服务器控件中映射到客户端对象属性的可本地化属性。

背景

ASP.NET 中的 AJAX 功能是在 ASP.NET 2.0 本地化模型的基础上构建而成的。它可以为嵌入在程序集中或作为静态 .js 文件存在于磁盘上的已本地化脚本文件提供附加支持。

如果您尚不熟悉 ASP.NET 本地化模型，可以参见下列主题了解相关信息：

本地化程序集中的客户端脚本文件和脚本资源

ASP.NET AJAX 功能利用 .NET Framework 资源模型来进行本地化处理。此模型采用轮辐式布局来打包和部署可增量更新的已本地化资源。其“轮毂”是包含非本地化可执行代码的主程序集。它包含 .NET Framework 服务器代码，以及作为资源嵌入在程序集中的 .js 文件中的所有 JavaScript 代码。

主程序集还可以包含单个区域性的资源，该区域性称为“非特定区域性”或“默认区域性”。非特定区域性是应用程序的回退区域性。如果未指定区域性或不存在指定区域性的资源，则使用非特定区域性。

针对各种区域性的已本地化资源通常创建为名称/值对的形式，并保存在 .resx 文件中（这些 .resx 文件可编译为 .resources 文件）。其中，名称用于提供对代码信息的访问，值则是该名称经本地化（转换）后的术语、图像或其他元素。生成程序集时，将为 .resx 文件生成一个类型，并在其中将名称公开为对值提供编程访问的字段（应将此生成的类型的名称指定为程序集属性的一部分，如下文所述）。

在轮辐式模型中，每个“辐条”均连接至一个包含单个区域性的资源的附属程序集。附属程序集不包含任何将由服务器执行的代码。它只包含对该区域性的资源值提供编程访问的已生成类型。

此模型提供下列功能：

  • 在已经部署程序集后，通过部署新的附属程序集，可以添加新区域性的资源。开发区域性特定的资源可能需要额外的时间。因此，此模型允许先释放主应用程序，稍后再传递其他区域性特定的资源。

  • 无需编译主程序集即可更新应用程序的附属程序集。

  • 应用程序只需加载特定区域性的附属程序集，而不用先卸载再重新加载主程序集。这可以显著减少对系统资源的占用。

有关如何创建 ASP.NET 资源文件的信息，请参见如何：为 ASP.NET 网站创建资源文件 (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 文件）中创建其资源，然后再将这些资源编译成单个附属程序集。

Bb398937.alert_note(zh-cn,VS.90).gif说明：

ASP.NET 允许创建自定义用户界面区域性和自定义区域性名称。但是，区域性名称通常基于一种 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 关联的资源的发布版本，已针对特定用户界面区域性本地化。这些资源会变为附属程序集的一部分。

  • Sample.debug.fr-FR.resources
    与脚本文件 Sample.debug.js 关联的特定于调试的资源，已针对特定用户界面区域性本地化。这些资源会变为也包含 Sample.fr-FR.resources 文件的附属程序集的一部分。

对于资源文件或嵌入在程序集中的脚本文件，并不需要严格遵循此命名约定。这是因为，为资源生成的类型与资源名称之间的映射是通过程序集属性来完成的。

本地化调试脚本资源

如果在调试模式下工作，ASP.NET 会在运行时将脚本文件资源的发布版本与任何其他调试资源组合在一起。随后，它会将得到的组合发送至浏览器。因此，在为脚本的调试版本创建资源文件时，只需定义已发布的脚本资源文件中尚未包括的名称/值对即可。通过转换，脚本以及脚本资源的调试版本将使用与其发布版本相同的名称，只不过它们的脚本文件名后会包含“.debug”。

为本地化脚本以及与脚本关联的本地化资源指定程序集属性

若要指定生成程序集时的资源文件管理方式，请在 AssemblyInfo 文件（AssemblyInfo.vb 或 AssemblyInfo.cs 文件）中添加一些属性。

Bb398937.alert_note(zh-cn,VS.90).gif说明：

在 Visual Studio 中，对于用 Visual Basic 编写的项目，AssemblyInfo.vb 文件位于“解决方案资源管理器”的“我的项目”节点中。如果在“我的项目”节点中未看到任何文件，请在“项目”菜单中单击“显示所有文件”。对于用 C# 编写的项目，AssemblyInfo.cs 文件位于“解决方案资源管理器”的“属性”节点中。

在 ASP.NET 中，应用程序的资源用 WebResourceAttribute 类标记。若要将 JavaScript 文件嵌入在程序集中，请使用此属性将 .js 文件指定为 Web 资源。

若要将资源文件包括在嵌入式 JavaScript 文件中，请使用 ScriptResourceAttribute 类。此属性会将基于文本的资源专门标识为 JavaScript 文件的资源。

Bb398937.alert_note(zh-cn,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")]

在此示例中，主程序集 MainAssembly 包含客户端脚本文件 Sample.js 的嵌入式发布版本。此外，该程序集还包含与该发布版本相应的调试版本 Sample.debug.js。.js 文件由 WebResourceAttribute 属性标识为资源。

NeutralResourcesLanguageAttribute 程序集属性用于将主程序集指定为回退区域性。有关更多信息，请参见用于本地化的非特定资源语言和 System.Resources.NeutralResourcesLanguageAttribute 类概述。

脚本文件使用的资源由 ScriptResourceAttribute 属性定义。Sample.resources 和 Sample.debug.resources 文件分别包含 Sample.js 和 Sample.debug.js 文件的资源值。

此示例针对脚本文件的发布版本和调试版本生成了一个名为 Sample.Res 的类型。此类型就是 JavaScript 代码用于访问本地化值的类型。对于发布和调试这两种模式，生成过程只创建一个类型。在调试模式下，发布版本的资源将与调试版本的其他资源组合在一起。

有关如何创建程序集信息文件以及受版本控制的程序集所需的程序集元数据的更多信息，请参见如何：为预编译网站创建带有版本的程序集。

本地化静态脚本文件及其资源

您可以将脚本库组织成磁盘上的本地化静态脚本文件（.js 文件），而不是将脚本文件嵌入在程序集中。页面开发人员可通过 ScriptReferenceCollection 类引用这些脚本文件。

在静态脚本文件模型中，不存在可作为 JavaScript 文件资源进行自动管理的单独 .resx 或 .resources 文件。此模型中只有 .js 文件，且每个 .js 文件都针对一个用户界面区域性和区域设置的组合。实际上，每个 .js 文件都表示整个 JavaScript 代码的一个区域性特定的版本。若要在此模型中管理已本地化的脚本文件，一种典型的方法是在每个 .js 文件中应用相同的 JavaScript 逻辑。与程序集嵌入式模型相同，JavaScript 代码也通过调用类型来检索已本地化的资源值。与其不同的是，包含本地化值的类型需要您手动提供，而不是自动生成。例如，每个区域设置的 .js 可以既包含应用程序代码，也包含定义保存本地化值的字段的类。在每个 .js 文件中，此类将包含用不同语言表示的值。

Bb398937.alert_note(zh-cn,VS.90).gif说明：

在静态脚本文件模型中，.js 文件中的应用程序 JavaScript 代码可能会与嵌入式 JavaScript 文件中的代码出现不同步。这是因为，每个脚本文件都包含代码的一个副本。若要避免因代码重复而出现的版本控制问题，可以只保留 JavaScript 资源文件的一个副本，并在单独的文件中创建已本地化的资源类型。随后，您可以在应用程序的生成过程中再生成最终的组合文件。

与程序集中的嵌入式资源相同，已本地化的静态脚本文件也是将用户界面区域性包括在文件名中，以此来映射到它们的用户界面区域性。例如，非特定区域性的法语嵌入式客户端脚本文件将命名为 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 控件为使用本地化的脚本和脚本资源提供下列功能：

  • 允许定义受支持的用户界面区域性，其中包括自定义用户界面区域性。

  • 解释区域性特定的程序集属性，并自动检测浏览器的用户界面区域性（如果有）。随后，它将从程序集中读取本地化的或用作回退的脚本和资源。在调试模式下，它会尝试加载文件名中既包含相应的用户界面区域性名称，又包含字符串“.debug”的脚本资源，例如 Sample.debug.fr-FR.resources。

  • 生成指向适当脚本及其本地化资源的 URL。为增强安全性，它还会对 URL 进行加密。

  • 基于已生成 URL 中的参数确定是否压缩脚本或脚本资源。

  • 向包含嵌入式脚本的程序集添加时间戳，以免浏览器无限制地缓存脚本。

有关更多信息，请参见 ScriptManager 类概述。

下面的示例演示一个网页的部分内容，此内容使用 ScriptManager 控件注册位于程序集中的客户端控件。此嵌入式脚本通过 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
    管理 ASP.NET 服务器页上的 AJAX 组件、部分页呈现、客户端请求以及服务器响应。

  • ScriptReference
    提供注册 JavaScript 文件（嵌入在程序集中的文件或位于磁盘上的文件）以供网页使用的 API。

  • ScriptReferenceCollection
    提供对表示客户端脚本文件的 ScriptReference 对象的访问。

请参见

任务

创建自定义非可视客户端组件

如何：为 ASP.NET 网站创建资源文件 (Visual Studio)

如何：为预编译网站创建带有版本的程序集

动态分配脚本引用

概念

ASP.NET 网页资源概述

参考

资源文件生成器 (Resgen.exe)

其他资源

使用资源本地化 ASP.NET 网页