NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Localization

The primary goal of the NGWS runtime resource model is to facilitate the development of localizable applications. The resource model allows a resource to be retrieved based on its name and culture.

Localization Requirements

The localization design must satisfy the following requirements:

Localization and Assemblies

Cultures and Assembly Identity

Assemblies have culture information as part of their identity. As a result, a culture affects the process of binding to an assembly. The culture of an assembly is included in the assembly’s manifest and can be one of the following values:

The culture independent value should be specified for an assembly that packages resources for different cultures. Since the resource table does not associate a culture with a resource, some other means should be used to infer the culture for a resource. One possible scheme is to embed information about the culture name in the resource name. For example, resource names for resources of the French culture could use the suffix “.fr”.

Cultures and Assembly Binding

Culture is part of the assembly identity and plays a part in the binding process. The runtime must always provide culture information as part of each bind request. The assembly cache manager never assumes or derives any culture information based on the current thread or environment.

A client retrieves resources for a specific culture by first retrieving the assembly for that culture. For the neutral culture, this is the main assembly of the application. For other cultures, the client retrieves the satellite assembly by passing the culture to Assembly.GetSatelliteAssembly(CultureInfo). Once the assembly is retrieved, a client can retrieve resources from the assembly by calling one of the Assembly.GetResource methods. The runtime looksup the specified resource in the resource table of the assembly’s manifest and returns the resource data as a managed stream.

The rules followed to bind to a satellite assembly are as follows:

  1. Satellite assemblies may be either simply named or strongly named subject to the constraint that if the main assembly is strongly named, all its satellite assemblies must also be strongly named.
  2. As with all assembly binds, the assembly cache manager will not honor version numbers for binds to simply named assemblies but will honor version numbers for binds to strongly named assemblies.
  3. As with all assembly binds, any appropriate policy will be applied to all binds to satellite assemblies.
  4. When binding to a strongly named satellite assembly, a resource manager should take the version number of the main assembly and request that version of a satellite assembly. The request should ignore the revision and build numbers of the version. To support the scenario where a QFE update is made to the main assembly, i.e., a change in revision and build numbers only, but the version of the satellite assembly remains unchanged, the assembly cache manager will allow binding to a revision+build that is older than the one requested.

If the main assembly’s simple name is “MyProject”, the runtime assumes that the satellite assembly’s simple name is “MyProject.resources”.

Naming Conventions

The NGWS runtime assumes that satellite assembies will have the file type “.mcl”. Resource names are assumed to be of the form:

typeNameSpace + Type.Delimiter + baseName + “.” + cultureName [+ “-” + subCultureName] + “.resources”

The culture specification is dropped when the resource is in a main assembly. Loose resource files in formats such as .GIF, .WAV, etc. follow a similar naming convention with the difference that they use the appropriate file type.

For example, a German resource with base name “MyResource” in namespace “MyNamespace” that is packaged in a satellite assembly would be named “MyNamespace.MyResource.de.resources”. The same resource packaged in a main assembly would be named “MyNamespace.MyResource.resources”. A .GIF localized for the German culture that is packaged in the satellite assembly would be named “MyNamespace.MyGif.de.resources”. A French (Belgium) resource would be named “MyNamespace.MyResource.fr-be.resources”.

The following example illustrates how resources and assemblies can be named in a project:

Project system:
Project1
Form1.cs
   Form1.resx
   Form1.de.resx
Intermediary files:
obj\form1.msil
obj\project1.form1.resources
obj\project1.form1.de.resources
Assembly outputs:
Main assembly:
simple name = project1
file name = project1.mcl
Manifest:
   name = project1
   culture = neutral
Resource table:
   project1.form1.resources
Satellite assembly:
simple name = project1.resources
file name = de\project1.resources.mcl
Manifest:
   name = project1.resources
   culture = de
Resource table:
   project1.form1.de.resources