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!

---

Concept

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.

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 ".

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

The Solution Explorer gets an appropriate entry too.

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.

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

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.

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.

IntelliSense

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:

• If the attribute lang is used to identify the language, the displayed text is that having an attribute value of "en".
• If the attribute has a different name or none of the lang attributes have the expression "en", the first specified text is used.

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