Información general sobre la localización de recursos para bibliotecas de componentes

Actualización: noviembre 2007

La localización es el proceso mediante el cual se adapta una aplicación para un idioma y una referencia cultural determinados. La funcionalidad de AJAX en ASP.NET admite los siguientes modelos de localización para trabajar con script de cliente:

• El modelo de recursos de .NET Framework, con compatibilidad expandida para los recursos traducidos asociados a los componentes ECMAScript (JavaScript). En este modelo, los archivos de script y los recursos de script traducidos se incrustan en una organización de ensamblados (ensamblados satélite) de tipo concentrador y radio. A continuación, puede utilizar selectivamente estos scripts de cliente y recursos incrustados para idiomas y regiones específicos. Este modelo permite a una sola base de código admitir varias referencias culturales.

• Archivos JavaScript estáticos (independiente) en disco. En este modelo, los archivos traducidos se agrupan en un único directorio como archivos .js, en lugar de incrustarse en un ensamblado.

• Actualización de scripts y recursos de script incrustados en un ensamblado mediante archivos JavaScript estáticos. Este modelo permite proporcionar compatibilidad adicional de localización en scripts y recursos incrustados sin necesidad de cambios en el ensamblado original.

Este tema contiene la siguiente información:

• Escenarios

• Background

• Adaptar scripts de cliente y recursos de script en ensamblados

• Adaptar archivos de script estáticos y sus recursos

• Utilizar ScriptManager para administrar scripts en una ubicación central

• Ejemplos de código

• Referencia de clase

Escenarios

Las características de AJAX en ASP.NET ayudan a los programadores de páginas y de componentes a realizar la localización del cliente. Generalmente, los programadores de páginas adaptan los siguientes elementos:

• Mensajes de excepción que se generan en AJAX de ASP.NET o en bibliotecas de componentes, basados en la configuración de idioma del explorador.

• Interfaz de usuario para los controles, como cadenas para la propiedad Text de un control Button.

• Valores para las propiedades públicas de controles de servidor de ASP.NET AJAX.

• Valores para las propiedades de objetos de script de cliente y componentes, como componentes no visuales, comportamientos y controles.

Generalmente, los desarrolladores de componentes utilizan las características de localización en las siguientes actividades:

• Adaptar recursos a los que se hace referencia en código de bibliotecas JavaScript (archivos .js). Los recursos traducidos se pueden implementar en instalaciones independientes, sin volver a generar el ensamblado principal ni la biblioteca de scripts.

• Exponer propiedades que se pueden adaptar de controles de servidor asignados a propiedades de objetos de cliente.

Background

La funcionalidad de AJAX en ASP.NET se genera sobre la base del modelo de localización de ASP.NET 2.0. Proporciona compatibilidad adicional para los archivos de script traducidos, ya sean archivos incrustados en un ensamblado o archivos .js estáticos en disco.

Si no está familiarizado con el modelo de localización de ASP.NET, puede encontrar información sobre él en los temas siguientes:

• Localizar páginas web ASP.NET mediante el uso de recursos

• Cómo: Crear archivos de recursos para sitios Web ASP.NET (Visual Studio)

• Generador de archivos de recursos (Resgen.exe)

Adaptar archivos de script de cliente y recursos de script en ensamblados

La funcionalidad de AJAX en ASP.NET utiliza el modelo de recursos de .NET Framework para la localización. Este modelo utiliza una organización de concentrador y radio para empaquetar e implementar recursos traducidos que se pueden actualizar de forma incremental. El concentrador es el ensamblado principal que contiene el código ejecutable no traducido. Incluye código de servidor de .NET Framework y cualquier código JavaScript en archivos .js que se incrustan como un recurso en el ensamblado.

El ensamblado principal también puede contener recursos para una referencia cultural única, que se denomina referencia cultural neutra o predeterminada. La referencia cultural neutra es la referencia cultural de reserva de la aplicación. Se utiliza si no se especifica ninguna referencia cultural o si no hay ningún recurso para la referencia cultural especificada.

Los recursos traducidos a una referencia cultural se crean normalmente como pares de nombre/valor en archivos .resx. (Estos archivos .resx se pueden compilar en archivos .resources.) El nombre proporciona acceso a la información en código y el valor es el término, imagen u otro elemento adaptado (traducido) para dicho nombre. Cuando se genera un ensamblado, se genera un tipo para el archivo .resx en el que los nombres se exponen como campos que proporcionan acceso mediante programación a los valores. (El nombre de este tipo generado se especifica como parte de las propiedades de ensamblado, como se describe más adelante.)

En el modelo de concentrador y radio, cada radio se conecta a un ensamblado satélite que contiene los recursos de una única referencia cultural. El ensamblado satélite no contiene ningún código que ejecute el servidor. Sólo contiene el tipo generado que proporciona acceso mediante programación a los valores de recurso de la referencia cultural correspondiente.

Este modelo proporciona las características siguientes:

• Puede agregar recursos para nuevas referencias culturales mediante la implementación de nuevos ensamblados satélite después de haber implementado un ensamblado. El desarrollo de recursos específicos de la referencia cultural puede precisar tiempo adicional. Por tanto, este modelo permite lanzar la aplicación principal en primer lugar y proporcionar más adelante recursos adicionales específicos de la referencia cultural.

• Puede actualizar los ensamblados satélite de una aplicación sin volver a compilar el ensamblado principal.

• Una aplicación sólo debe cargar el ensamblado satélite de una referencia cultural determinada, en lugar de descargar y volver a cargar el ensamblado principal. De este modo, se puede reducir en gran medida el uso de los recursos del sistema.

Para obtener información sobre cómo crear archivos de recursos para ASP.NET, vea Cómo: Crear archivos de recursos para sitios Web ASP.NET (Visual Studio) y Localizar páginas web ASP.NET mediante el uso de recursos.

Para obtener información sobre cómo utilizar la herramienta de generación de archivos de recursos de .NET Framework (Resgen.exe), vea Generador de archivos de recursos (Resgen.exe). Esta herramienta convierte archivos .resx o .txt en archivos .resources binarios que se pueden vincular a ensamblados.

Organizar ensamblados principales y satélite traducidos

Puede utilizar el modelo de concentrador y radio si desea adaptar una aplicación que incluye archivos JavaScript (.js). En general, el ensamblado se organiza de la misma forma que en cualquier aplicación ASP.NET que se adapta.

Para administrar los archivos JavaScript de una aplicación web ASP.NET habilitada para AJAX, debe escribir el código JavaScript de forma que no asigne cadenas u otros elementos que se deberían adaptar. Así, en cualquier lugar donde el código JavaScript deba utilizar valores traducidos, debe obtener un campo del tipo que se genera a partir del archivo de recursos.

Generalmente el ensamblado principal incluye los elementos siguientes:

• Los archivos JavaScript que realizan las tareas de aplicación y que se escriben para utilizar recursos traducidos en lugar de recursos codificados de forma rígida. El ensamblado puede incluir versiones de depuración de estos archivos JavaScript.

• Opcionalmente, los recursos (archivos .resx o .resources) de una referencia cultural neutra única, que actúa como referencia cultural de reserva de la aplicación.

• Opcionalmente, cualquier versión de depuración de recursos de la referencia cultural neutra. La versión de depuración de un archivo de recursos incluye cualquier par de nombre/valor adicional necesario para las versiones de depuración de los archivos JavaScript.

Por regla genera, un ensamblado satélite incluye recursos traducidos para una única referencia cultural de la aplicación ASP.NET. (No se necesita ningún ensamblado satélite para la referencia cultural de reserva.) Los recursos para una referencia cultural única se crean en un archivo de recursos independiente (archivo .resx o .resources) y, a continuación, se compilan en un ensamblado satélite único.

Nota:

ASP.NET permite crear una referencia cultural personalizada de la interfaz de usuario y un nombre de referencia cultural personalizado. Sin embargo, normalmente los nombres de referencia cultural se basan en código de idioma ISO que está compuesto de dos letras para el idioma y dos letras en mayúscula para el país o la región. Ejemplos de ello son es-MX (español de México), es-CO (español de Colombia) o fr-CA (francés de Canadá). Para obtener una lista completa de los nombres de referencias culturales, vea la información general de la clase System.Globalization.CultureInfo.

Nombres de los archivos de script incrustados traducidos

Se recomienda seguir la convención de nomenclatura que se indica a continuación en los archivos de script traducidos que se incrustan como recursos:

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

La versión de depuración de un nombre de archivo incluye ".debug" en el nombre. La versión de lanzamiento no lo hace.

La tabla siguiente muestra ejemplos de esta convención de nomenclatura. Los ejemplos muestran las versiones de lanzamiento y depuración de un archivo de script incrustado. También muestran las versiones de lanzamiento y depuración asociadas de los recursos para estos archivos de script.

• Sample.js
  Una versión de lanzamiento de un archivo de script de referencia cultural neutra, que se incrusta en el ensamblado principal.

• Sample.debug.js
  Una versión de depuración de un archivo de script de referencia cultural neutra, que también se incrusta en el ensamblado principal.

• Sample.fr-FR.resources
  Una versión de lanzamiento de recursos asociados con el archivo de script Sample.js y traducidos para una referencia cultural concreta de la interfaz de usuario. Estos recursos pasan a formar parte del ensamblado satélite.

• Sample.debug.fr-FR.resources
  Recursos específicos de depuración asociados al archivo de script Sample.debug.js, traducidos para una referencia cultural concreta de la interfaz de usuario. Estos recursos pasan a formar parte del ensamblado satélite, que también incluye el archivo Sample.fr-FR.resources.

Esta convención de nomenclatura no es estrictamente necesaria en los archivos de script que se incrustan en los ensamblados ni en los archivos de recursos. Esto se debe a que la asignación entre el tipo generado para el recurso y el nombre del recurso se logra mediante un atributo de ensamblado.

Adaptar recursos del script de depuración

Si trabaja en modo de depuración, en tiempo de ejecución ASP.NET combina la versión de lanzamiento de los recursos correspondientes a los archivos de script con cualquier recurso de depuración adicional. A continuación, envía la combinación resultante al explorador. Por tanto, al crear archivos de recursos para las versiones de depuración de los scripts, sólo debe definir los pares de nombre/valor que no están ya incluidos en los archivos de recursos del script de lanzamiento. Por convención, las versiones de depuración de los scripts y recursos de script utilizan el mismo nombre que su homólogo de lanzamiento pero incluyen ".debug" tras el nombre de archivo del script.

Especificar atributos de ensamblado para scripts traducidos y recursos traducidos asociados a scripts

Para especificar cómo se administran los archivos de recursos al generar un ensamblado, debe incluir atributos en el archivo AssemblyInfo (AssemblyInfo.vb o AssemblyInfo.cs).

Nota:
En Visual Studio, para los proyectos escritos en Visual Basic, el archivo AssemblyInfo.vb se encuentra en el nodo My Project del Explorador de soluciones. Si no ve ningún archivo en el nodo My Project, en el menú Proyecto, haga clic en Mostrar todos los archivos. En los proyectos escritos en C#, el archivo AssemblyInfo.cs se encuentra en el nodo Propiedades del Explorador de soluciones.

En ASP.NET, marca los recursos para la aplicación utilizando la clase WebResourceAttribute. Para incrustar los archivos JavaScript en un ensamblado, utiliza este atributo para especificar los archivos .js como un recurso web.

Para incluir los archivos de recursos de los archivos JavaScript incrustados, utiliza la clase ScriptResourceAttribute. Este atributo identifica los recursos basados en texto específicamente como recursos para archivos JavaScript.

Nota:
Para identificar recursos basados en texto de archivos JavaScript, se puede utilizar la clase ScriptResourceAttribute. Para asociar un archivo de imagen traducido (binario) a una referencia cultural, almacene su dirección URL como un recurso traducido que el script pueda resolver y cargar.

En el ejemplo siguiente se muestra cómo utilizar atributos de ensamblado para identificar scripts incrustados y sus recursos de script asociados.

' 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")]

En este ejemplo, un ensamblado principal denominado MainAssembly contiene una versión de lanzamiento incrustada de un archivo de script de cliente que se denomina Sample.js. El ensamblado también contiene la versión de depuración correspondiente denominada Sample.debug.js. Los archivos .js se identifican como recursos mediante el atributo WebResourceAttribute.

Para especificar el ensamblado principal como referencia cultural de reserva, se utiliza el atributo de ensamblado NeutralResourcesLanguageAttribute. Para obtener más información, vea Idiomas de los recursos neutros para la localización y la información general de la clase System.Resources.NeutralResourcesLanguageAttribute.

Los recursos que utilizan los archivos de script se definen mediante el atributo ScriptResourceAttribute. Los archivos Sample.resources y Sample.debug.resources contienen los valores de recurso de los archivos Sample.js y Sample.debug.js, respectivamente.

Para las versiones de lanzamiento y depuración de los recursos de script se genera un tipo denominado Sample.Res. Éste es el tipo que el código JavaScript utiliza para tener acceso a los valores traducidos. El proceso de compilación crea un único tipo para los modos de lanzamiento y depuración. En el modo de depuración, los recursos de la versión de lanzamiento se combinan con los recursos adicionales para la versión de depuración.

Para obtener más información sobre cómo crear archivos de información de ensamblado y los metadatos del ensamblado necesarios para los ensamblados con control de versiones, vea Cómo: Crear ensamblados que tienen versión para sitios Web precompilados.

Adaptar archivos de script estáticos y sus recursos

Puede organizar una biblioteca de scripts como archivos de script estáticos traducidos (archivos .js) en disco en lugar de incrustar los archivos de script en ensamblados. Los programadores de páginas pueden hacer referencia a los archivos de script a través de la clase ScriptReferenceCollection.

En el modelo de archivos de script estáticos, no existen archivos .resx ni .resources independientes que se puedan administrar automáticamente como recursos para los archivos JavaScript. Sólo existen archivos. js, uno para cada combinación de configuración regional y referencia cultural de la interfaz de usuario. De hecho, cada archivo .js representa una versión específica de la configuración regional del código JavaScript completo. Una manera típica de administrar los archivos de script traducidos en este modelo consiste en utilizar la misma lógica de JavaScript en cada archivo .js. Como en el modelo incrustado en el ensamblado, el código JavaScript invoca un tipo para recuperar los valores de recurso traducidos. La diferencia es que debe proporcionar el tipo que contiene los valores traducidos, ya que no se genera automáticamente. Por ejemplo, el archivo .js de cada configuración regional puede incluir el código de aplicación y una clase que define los campos que contienen los valores traducidos. En cada archivo .js, esta clase contendría los valores en un idioma diferente.

Nota:

En el modelo de archivo de script estático, el código JavaScript de la aplicación en los archivos .js puede perder la sincronización con el código de un archivo JavaScript incrustado. Esto se debe a que cada archivo de script incluye una copia del código. Para evitar problemas relacionados con el control de versiones en el código duplicado, puede mantener una sola copia de los archivos de código fuente de JavaScript y crear los tipos de recursos traducidos en archivos independientes. A continuación, puede generar los archivos finales combinados durante el proceso de compilación de la aplicación.

Los archivos de script estáticos traducidos se asignan a la referencia cultural de interfaz de usuario correspondiente mediante la inclusión del nombre de la referencia cultural de interfaz de usuario como parte del nombre de archivo, al igual que los recursos incrustados en un ensamblado. Por ejemplo, un archivo de script de cliente incrustado con una referencia cultural neutra para francés se denominaría Sample.fr.js y un recurso JavaScript específico de referencia cultural para francés canadiense se denominaría Sample.fr-CA.js.

Scripts de depuración traducidos en el modelo de archivos de script estáticos

En el modelo de archivos de script estáticos, los recursos traducidos a los que hace referencia un script se definen normalmente como un tipo en un archivo .js único. La versión de depuración de un archivo de script se organiza de la misma manera, con los recursos de lanzamiento traducidos y los recursos de depuración adicionales definidos como un tipo en un archivo único. Las versiones de depuración de scripts utilizan el mismo nombre que la versión de lanzamiento correspondiente, pero incluyen ".debug" después del nombre.

Usar ScriptManager para administrar scripts

Puede utilizar el control ScriptManager para administrar scripts estáticos situados en un directorio central en el disco. Para ello, coloque todas las versiones de los archivos de script en una carpeta, que incluye también las versiones de lanzamiento y depuración de todos los archivos traducidos. En el ejemplo siguiente se muestra el diseño de una estructura de directorios para una biblioteca de archivos de script estáticos:

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

En este ejemplo, todos los archivos de script se encuentran en una carpeta cuyo nombre utiliza la versión de la biblioteca de scripts (1.0.0.0). Esta carpeta específica de versión se encuentra a su vez en una carpeta cuyo nombre se asigna en función del espacio de nombres de la biblioteca. La organización de una biblioteca de scripts dentro de carpetas por espacio de nombres y versión puede proporcionar algún control de versiones para la biblioteca. También puede ayudar a evitar conflictos de nombres de script entre las bibliotecas. Además, permite a los consumidores de la biblioteca identificar a qué biblioteca y versión de biblioteca pertenecen los archivos.

Descripción de la función del control ScriptManager en la localización

El control ScriptManager proporciona la siguiente funcionalidad para utilizar scripts y recursos de script traducidos:

• Permite definir las referencias culturales de la interfaz de usuario que se admiten, lo que incluye las referencias culturales de interfaz de usuario personalizadas.

• Interpreta el atributo de ensamblado específico de la referencia cultural y automáticamente detecta la referencia cultural de la interfaz de usuario del explorador (si existe). A continuación, lee los scripts y recursos traducidos o de reserva del ensamblado. En modo de depuración, intenta cargar un recurso de script que contiene el nombre de la referencia cultural de la interfaz de usuario adecuado y la cadena ".debug" en el nombre de archivo, como Sample.debug.fr-FR.resources.

• Genera direcciones URL que señalan a los scripts adecuados y a sus recursos traducidos. Para aumentar la seguridad, cifra las direcciones URL.

• Determina si un script o un recurso de script se comprimirá, basándose en un parámetro de la dirección URL generada.

• Agrega una marca de tiempo al ensamblado que contiene scripts incrustados, de forma que el explorador no almacene indefinidamente en caché los scripts.

Para obtener más información, vea la información general de la clase ScriptManager.

En el ejemplo siguiente se muestra parte de una página web que utiliza el control ScriptManager para registrar un control de cliente situado en un ensamblado. El script incrustado se registra mediante las propiedades Assembly y 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>

Ejemplos de código

En las secciones siguientes se incluyen ejemplos de código que muestran cómo trabajar con recursos y archivos JavaScript.

Temas "Cómo..." y tutoriales

• Tutorial: Incrustar un archivo JavaScript como recurso en un ensamblado

• Tutorial: Incrustar recursos localizados en un archivo JavaScript

• Tutorial: Agregar recursos localizados a un archivo JavaScript

Referencia de clase

La tabla siguiente contiene las clases clave que se utilizan para adaptar bibliotecas de componentes.

• ScriptManager
  Administra componentes AJAX, la representación parcial de páginas, las solicitudes de cliente y las respuestas del servidor en las páginas de servidor ASP.NET.

• ScriptReference
  Proporciona varias API para registrar archivos JavaScript para su uso en una página web, ya se trate de archivos incrustados en un ensamblado o de archivos en disco.

• ScriptReferenceCollection
  Proporciona acceso a los objetos ScriptReference que representan archivos de script de cliente.

Vea también

Tareas

Crear componentes de cliente no visuales personalizados

Cómo: Crear archivos de recursos para sitios Web ASP.NET (Visual Studio)

Cómo: Crear ensamblados que tienen versión para sitios Web precompilados

Asignar referencias de script de forma dinámica

Conceptos

Información general sobre los recursos de las páginas Web ASP.NET

Referencia

Generador de archivos de recursos (Resgen.exe)

Otros recursos

Localizar páginas web ASP.NET mediante el uso de recursos