LocalizedHelloWorld Sample: Demonstrates Satellite Assemblies for Console Applications
The document is archived and information here might be outdated

LocalizedHelloWorld Sample: Demonstrates Satellite Assemblies for Console Applications

Visual Studio .NET 2003

The LocalizedHelloWorld sample demonstrates creating and using satellite assemblies for console applications. It shows how to create resources for C# console applications, localize the resources, and build localized satellite assemblies.

Although this sample was written using C#, the sample principles and techniques can be used to localize any managed application written in any language.

Building and Running the Sample

To build and run this sample

  1. Open the solution LocalizedHelloWorld.sln.
  2. From the Build menu, click Build Solution.
  3. From the Debug menu, click Start Without Debugging.
  4. Type in a culture supported by the application to see the resources in that culture (the sample ships with en, en-US, ko-KR, and default resources which are in English).

To add a new culture

The following procedure adds resources for English (United Kingdom):

  1. Add a new text file named "MyResources.en-GB.txt" to the Resources C++ utility project.
  2. Add the appropriate <name>=<value> lines to the new text file along with any desired comments.
  3. Add a custom build step for the new file (this should be the same as for the other resource files in the project):

    ResGen.exe "$(InputPath)"

  4. Set the output of the custom build step to "$(InputName).resources."
  5. Build this project (no need to rebuild the main assembly).
  6. Add an existing file named "..\Resources\MyResources.en-GB.resources" to the SatelliteAssemblies C++ utility project.
  7. Add a custom build step for this file (this should be similar to the other files' custom builds steps):

    mkdir $(ProjectDir)..\bin\$(OutDir)\en-GB

    al.exe /culture:en-GB /out:"$(ProjectDir)..\bin\$(OutDir)\en-GB\HelloWorld.resources.dll" /embed:"$(InputPath)","HelloWorld.Resources.$(InputFileName)" /template:"$(ProjectDir)..\obj\$(IntDir)\HelloWorld.exe"

  8. Set the output of the custom build step to "$(ProjectDir)..\bin\$(OutDir)\en-GB\HelloWorld.resources.dll"
  9. Build this project (no need to rebuild the main assembly).
  10. Run the sample and try your new resource.

To build the sample from the command line

Note   You can add options to the C# command-line for debugging or other reasons.
  1. Compile the resource for all cultures (from the Resources subdirectory):

    ResGen.exe MyResources.txt

    ResGen.exe MyResources.en-US.txt

    ResGen.exe MyResources.ko-KR.txt

  2. Create the output directory "bin\Debug" or use a different directory in the following steps.
  3. Compile the main assembly and embed the default resources (from the root project directory):

    csc.exe /out:bin\Debug\HelloWorld.exe /res:Resources\MyResources.resources,HelloWorld.Resources.MyResources.resources Class1.cs AssemblyInfo.cs

  4. Build the satellite assemblies (from the root project directory):

    mkdir bin\Debug\en-US

    mkdir bin\Debug\ko-KR

    al.exe /culture:en-US /out:bin\Debug\en-US\HelloWorld.resources.dll /embed:Resources\MyResources.en-US.resources,HelloWorld.Resources.MyResources.en-US.resources /template:bin\Debug\HelloWorld.exe

    al.exe /culture:ko-KR /out:bin\Debug\ko-KR\HelloWorld.resources.dll /embed:Resources\MyResources.ko-KR.resources,HelloWorld.Resources.MyResources.ko-KR.resources /template:bin\Debug\HelloWorld.exe

Projects in the Sample

This sample contains three projects and produces three assemblies.

Resources C++ Utility Project

This is the first project. It builds the managed resources with a custom build step that calls ResGen.exe to compile the .txt files into .resources files. The resource text file contains lines of <name>=<value> statements and comment lines that begin with a pound sign (#). In code, the strings will be loaded using the name given in this file.

Notice that for the Korean resources the file must be saved as UTF-8 to preserve the non-ASCII characters. Also note that individual cultures are not required to have a value for every name.

If a value doesn't exist for the proper culture, the resource manager automatically falls back to the parent cultures. For example, if the current culture is ko-KR, the resource manager will first look for the name in the "ko-KR" resources, then in the "ko" resource, and then finally in the default resources. Technically these resource files can be named anything, but typically they are named with the following convention:

<basename>[.<culture>].resources

If the culture is empty, it is assumed to be the default culture.

HelloWorld C# Console Project

This is the second project. It builds the main C# application and embeds the default resources (MyResources.resources built from MyResources.txt by the first project).

SatelliteAssemblies C++ Utility Project

This is the third project. It builds the two satellite assemblies that contain the localized resources with custom build steps. It calls Al.exe to create the satellite assembly, passing in the resource file with the "/embed" option, setting the culture with the "/culture" option, and copying the assembly information (title, version, and so on) from the main assembly with the "/template" option.

Note that the satellite assemblies must be in a subdirectory named after their culture of the main assembly, and the satellite assembly's file name is the same as the main assembly, but with ".resources" inserted before the file extension. For example, if the main assembly was "c:\bin\a.dll", the en-US satellite assembly would be "c:\bin\en-US\a.resources.dll".

Also note the second argument to the "/embed" option, the resources name. This name is the name that the resource manager will use to find the given resource group, and the name must include the proper culture string (case-sensitive) after the name and before ".resources". Because Al.exe gets most of the information from the main assembly, this third project must be built after the second one.

Classes and Keywords

This sample demonstrates the following classes:

System.Resources.ResourceManager

This sample demonstrates the following keywords:

managed resources, satellite assembly, localized resources, ResGen.exe, al.exe, /embed, /res, /template, /culture, System.Resources, System.Resources.ResourceManager, System.Resources.ResourceManager.GetString

See Also

Visual C# Samples | General Samples | Console: Localized Hello World Sample (Visual Basic)

Show:
© 2016 Microsoft