How to localize the documentation of a .NET library [closed]

Answer 1

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

Answer 2

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>

Answer 3

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.

Answer 4

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.

Answer 5

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?