Question

I have an open-source project (here) whose documentation is currently in French. The documentation is generated from XML comments in code, using Sandcastle. Now I would like to translate the documentation to English and provide documentation in both languages, but I don’t really know where to start…

• Do I need to extract the XML comments from the code and put them in a separate file? If yes, are there any tools to automate the process?
• I’m using Sandcastle Help File Builder to build the documentation; do I need to create a separate project to build the doc in English, or can it be done from the same project?
• Are there any tools to help in the translation process? e.g. display the original and translated doc side by side?

I’m also interested in links on how to produce multilingual documentation, as I couldn’t find anything useful on Google…

Answer 1

One strategy, which would require some coordination with the Sandcastle XSLT files, would be to use the xml:lang attribute on your XML documentation. Visual Studio 2010 allows multiple tags to remain (although you may get complaints about duplicate tags).

/// <summary>
/// Gets or sets the fill size of the load operation.
/// </summary>
/// <summary xml:lang="fr">
/// Obtient ou définit la taille de remplissage de l'opération de chargement.
/// </summary>
public int FillSize
{
    get;
    set;
}

Resulting output:

<member name="P:Namespace.MyAttribute.FillSize">
    <summary>
    Gets or sets the fill size of the load operation.
    </summary>
    <summary xml:lang="fr">
    Obtient ou définit la taille de remplissage de l'opération de chargement.
    </summary>
</member>