How to localize the documentation of a .NET librar

问题:

Closed. This question is off-topic. It is not currently accepting answers.

---

Want to improve this question? Update the question so it's on-topic for Stack Overflow.

Closed 2 years ago.

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

回答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>

回答2:

We did that like this :

• We put a "<EN>" tag after all our documentation tag like this :

  /// <summary>
  /// Description du produit
  /// <EN>Product's description</EN>
  /// </summary>
  

• Then in the sandcastle xslt file (Development/presentaton/vs2005/transforms/main_sandcastle.xsl) we went to the template matching "param" (line 95 for us) and we added

  <span class="trad"> 
      <xsl:value-of select="msxsl:node-set(.)/EN"/>
  </span>
  

• And then you can change the css to display the translation in your favorite color.

回答3:

One possible strategy would be having a default language in code, and supply translations separately.

No matter which localized languages i would have finally, i'd prefer to choose English as the default/fallback language of the documentation.

Code structure provides indexing for your translation database, for example:

Type, NameWithNamespace, OptionalParameterName

"member", "MyProject.Core.Loader.FillSize", ...

You could have a tool that would allow for translation in a UI for each namespace/member.

You can have a separate team of translators looking through the items that have no translation yet, and supply translations.

And you can start shiping a translated documentation as your ship a release as soon as you get the amount of translated items above a threshold.

A changed default translation would indicate that you need a new translation for all other languages too.

Of course, if you do a major namespace-only changes, you can remap the namespaces as an ad-hoc remapping operation in database.

If you run opensource project, it makes sence to use a collaborative online translation tool.

One example of such collaborative translation strategy implemented in production is https://translations.atlassian.com/

Basically you could just step in and start contributing translations online.

It is set up to translate the products themselves, not the documentation, but the same practice apply.

回答4:

You have yourself a tricky one. There really isn't a "best practise" since most software is developed in English.

That being said, if you look at other multi lingual documentation, how do they handle this problem?

Take International Standards. Something like ISO 9001. You have the same document (ISO 9001:2008) available in English, French, Russian etc.

Or ISO 5247-2 has the one document in English+French+Russian.

How would you handle changes? Say I give you a patch, but my comments are only in English, what would your process be? What if you have patch A in English, patch B in Spanish and patch C in English + French?

Another option is to fork the project. Have the main branch be in French with the latest build, then bring the other languages up to date in their own time?

Separating the comments in your source code would get messy to maintain. You are then basically using a resource file in your build script.

Is this a solved problem already? If you think of any large, multi lingual, open source project, how do they handle it?

回答5:

Just in case anyone needs a solution there is nuget package called Surviveplus.XmlCommentLocalization. Stunning!