English version Zur deutschen Version wechseln

With Eric Woodruffs Sandcastle Help File Builder it is quite simple to generate a fine help file documentation from program code. Unfortunately, this software does not support localization. With a few tricks, it is still possible!



Preparation / Installation

Configure the build events

Comment Program Code

Create the SHFB-Project


Note: Some of the pictures were taken from the German version of Visual Studio.

Note: Because the Prebuild event is exploited, it works only when the help file is generated using the Visual Studio build process.

       SHFB Note
        Menu 'Build''


The XML comment elements are duplicated. Each item is provides with an attribute that defines the associated language. This attribute is used during the prebuild event to filter the compiler generated XML file using XPath. This preprared file is then exposed to the further process that generates the help file.

Preparation / Installation

The SHFB (Sandcastle Help File Builder) is obtained via GitHub: EWSoftware/SHFB. Here to best use the installation wizard. The ensures that Visual Studio accepts the SHFB projects.

Filtering via XPath was done by XMLStarlet Command Line XML Toolkit.

Visual Studio must be configured that a XML documentation file is created. This is done via the property page of the project.

Generate XML documentations file

Code kommentieren

The following description applies to a Visual Basic project. For a c# project appropriate adjustments must be made. The examples are taken my project UrsLibrary.

The commentary of the code is as usual. However, each item that should be documented in several languages, has a duplicated entry for each language. Each entry has an additionally lang attribute with the regarding language shortcut. The following example demonstrates this:

   ''' <summary lang="en">
   '''    Initializes a new instance of the <see cref="System.Random"/> class, using the specified seed value.
   ''' </summary>
   ''' <summary lang="de">
   '''    Initialisiert eine neue Instanz der <see cref="UrsRandom"/>-Klasse unter Verwendung des angegebenen Startwerts.
   ''' </summary>
   ''' <param  name="Seed" lang="en">
   '''    A number used to calculate a starting value for the pseudo-random number sequence.
   '''    If a negative number is specified, the absolute value of the number is used.
   ''' </param>
   ''' <param name="Seed" lang="de">
   '''    Eine Zahl, mit der ein Startwert für Folgen von Pseudozufallszahlen berechnet wird.
   '''    Wenn eine negative Zahl angegeben wird, wird der absolute Wert der Zahl verwendet.
   ''' </param>
Sub New(Seed As Integer)

Configure the build events

The following post build events are added to the projects to be included in the documentation. This will create the language specific XML files.

"C:\Program Files (x86)\xmlstarlet\xml" ed -d "//*[@lang != 'de']" "$(TargetDir)$(TargetName).xml" >"$(TargetDir)$(TargetName)-DE.xml"
"C:\Program Files (x86)\xmlstarlet\xml" ed -d "//*[@lang != 'en']" "$(TargetDir)$(TargetName).xml" >"$(TargetDir)$(TargetName)-EN.xml"

What's happening? The compiler-generated XML documentation file UrsLibrary.xml in the output folder  (...\bin\Release\)is copied by program xml (XMLStarlet, see: Preparation/Installation) to file UrsLibrary-de.xml . All entries having a lang attribute (option ed -d) that is different from the specified language symbol (option "//*[@lang != 'de']") are filtered.

Create the SHFB-Project

Before the SHFB project cann be created, you have to create the affected code projects once. This will create the language-specific XML files to includes to the SHFB project.

This begins with addding a new SFHB project to the solution. The SHFB project template can be found under Solution → Add → New Project ... → installed → Documentation. Conveniently, choose a project name containing a language tag. For example use: "UrsLibraryDoc-DE ".

SHFB im Projektmappen-Explorer

A new folder is added to the solution with the selected name and a default content.

SHFB project folder

The Solution Explorer gets an appropriate entry too.

Solution Explorer

The properties of the project now can be fitted the to requirements and additional content in the chosen language added. Further help can be required from the help file accompanying the SHFB.

Documentation Sources are still missing. Normally the XML documentation file UrsLibrary.xml will be used. However, this still contains entries for all documented languages. One should select UrsLibrary-de.xml. But SFHB does not allow that any arbitrary name is specified. The file must exist! Therefore, it is first necessary to create a file with the name you want to start with. The file can have any random content, it will be overwritten execuiting the prebuild command anyway.

Using Add Documentation Source the .DLL and the newly created file have to be selected.

Add Documentation Source

Unfortunately, the standard XML file is added to the list too. It must be deleted manually.

Standard-XML-Datei löschen

Recently, one should make sure that the dependencies between the individual projects are set correctly. Oherwise it is possible that the build process does not update all files SFHB project depends on.

Project dependencies settigns

That's it. If now the SHFB project or the entire solution is build, a help file is created that only includes those components containing lang attribute, whose contents is "de".

To generate help files in other languages ​​repeat this process or copy the existing project, replacing the language token accordingly.

Who wants a Visual Studio look up example might download the VS Solution of UrsLibrary. However there are currently only a few multiple language code comments. Currently this is the case with class UrsRandom in namespace UrsUtilities.


The behavior of IntelliSense, which displays the possible summary tags is still a bit vague. Neither MSDN nor Google could help. Following rule appears in (the German variant of) VS to be implemented:

 Depending on the intended purpose consider how the language is defined and in what order the help texts are specified.