This documentation is archived and is not being maintained.

Packaging Resources

.NET Framework 1.1

So far, this tutorial has assumed that you are using a single, default language for your resources. It is now time to consider a more complex scenario, where there are parallel sets of resources for multiple cultures. This allows you to construct a single application that runs in multiple cultures. In other words, by detecting the user's culture and loading the appropriate resources at run time, the application can be tailored to the individual. This approach also makes it possible to modify resources — perhaps updating a string or even adding a new culture — without requiring a new compilation and distribution of the entire application. This is particularly handy when the resources are located in a shared directory, and multiple users can automatically pick up the changes.

The two localized sample applications included with this tutorial (WorldCalc and Graphic) use private satellite assemblies. Private means that they are not placed into the global assembly cache (GAC); satellite refers to their being resource-only assemblies (or DLLs) that work in conjunction with another, main assembly where the application code is located. The main assembly also contains the default, or neutral, culture resources, which are used when a particular localized resource does not exist. The main assembly's resources are located in the application directory in .resources files and are embedded into the assembly by the compiler. They can also be subsequently embedded using the Assembly Generation Tool (AL).

Note   For more information on AL, see Appendix B: Resource Tools.

If the resource assemblies are to be shared, which means that they will be in the GAC and can be used by multiple applications, it is necessary to strongly name them by giving them additional key and version information. In addition, you might want to add the SatelliteContractVersionAttribute attribute, to allow you to create versions of the satellite resource assemblies — independent of the main assembly and without requiring the use of configuration policy files. For more information on strong-named assemblies, see Packaging and Deploying .NET Framework Applications.

If you examine each of these applications, note that there are a series of subdirectories beneath the application directory, that each subdirectory has a name corresponding to a culture tag, and that each subdirectory contains the raw resource information and, if built, the corresponding satellite assembly. This layout emphasizes two important points: a particular assembly can contain resources for only a single culture, and each culture's resources are stored in a separate subdirectory that is named after the culture's tag.

Strings — String localization is illustrated by the WorldCalc sample. The strings are stored in name-value pairs in files named MyStrings.txt in the application directory (for the default English) and the two localized cultures (de for German and de-CH for Swiss-German).

The build process (in Build.bat) for the WorldCalc sample application performs the following steps (shown here organized together more logically than in the actual Build.bat file).

  1. Build the math.dll and parser.dll components:
    csc ... math.cs
    csc ... parser.cs
    
  2. Build the default .resources file and all localized .resources files using Resgen.exe:
    resgen MyStrings.txt MyStrings.resources
    resgen MyStrings.de.txt MyStrings.de.resources
    resgen MyStrings.de-CH.txt MyStrings.de-CH.resources
    
  3. Use the AL to create the satellite assemblies, embed (or link) the resources, and set the culture:
    al /out:WorldCalc.Resources.Dll /v:1.0.0.0 /c:de /embed:MyStrings.de.resources,MyStrings.de.resources,Private
    al /out:WorldCalc.Resources.Dll /v:1.0.0.0 /c:de-CH /embed:MyStrings.de-CH.resources,MyStrings.de-CH.resources,Private
    
    Note   The culture strings are not case sensitive.
  4. Compile the application itself and link the default resources with the /res switch:
    csc ... /target:winexe ... /addmodule:parser.dll /r:System.Windows.Forms.dll /r:System.Drawing.dll /r:System.dll /r:math\math.dll /res:MyStrings.resources WorldCalc.cs
    

    Here is the Visual Basic equivalent:

    vbc ... /target:winexe ... /addmodule:parser.dll /r:System.Windows.Forms.dll /r:System.Drawing.dll /r:System.dll /r:math\math.dll /res:MyStrings.resources WorldCalc.vb
    

From this point, all that is required to add another culture is to create an appropriate text file containing the resources, and repeat steps 2 and 3.

Images — Image localization is demonstrated in the Graphic sample. The build process for this sample application is similar to the process for WorldCalc, but it adds a single step that converts the images to .resx files:

resxgen /i:un.jpg /o:Images.resx /n:flag
cd en
resxgen /i:en.jpg /o:Images.en.resx /n:flag
cd ..\en-au
...

See Also

Retrieving Resources Using Code | Resources Summary | Appendix A: Additional Resource Information | Appendix B: Resource Tools

Show: