Comment traduire la documentation d'un .NET-library

Question

J'ai un projet open-source (ici) dont la documentation est actuellement en français. La documentation est générée à partir de XML commentaires dans le code, à l'aide de Châteaux de sable. Maintenant, je voudrais la traduction de la documentation de l'anglais et de fournir de la documentation dans les deux langues, mais je ne sais pas vraiment par où commencer...

• Dois-je extraire les commentaires XML à partir du code et de les mettre dans un fichier séparé? Si oui, existe-il des outils pour automatiser le processus?
• Je suis l'aide de Sandcastle Help File Builder pour construire la documentation; ai-je besoin de créer un projet de construction de la doc en anglais, ou peut-il être fait à partir du même projet?
• Existe-il des outils pour aider dans le processus de traduction? par exemple, afficher l'original et traduit doc côte à côte?

Je suis aussi intéressé par des liens sur comment produire des documents multilingues, comme je ne pouvais pas trouver quelque chose d'utile sur Google...

Answer 1

Une stratégie, qui aurait besoin d'un peu de coordination avec les Châteaux de sable de fichiers XSLT, serait d'utiliser l' xml:lang d'attribut sur votre documentation XML. Visual Studio 2010 permet à plusieurs balises de rester (bien que vous pouvez obtenir les plaintes à propos des balises en double).

/// <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;
}

Résultat:

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

Nous l'avons fait comme ceci :

• Nous avons mis un "<FR>" tag après tout notre documentation balise comme ceci :

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

• Ensuite, dans le château de sable fichier xslt (Développement/presentaton/vs2005/transformations/main_sandcastle.xsl) nous sommes allés à la template matching "param" (ligne 95 pour nous) et nous avons ajouté

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

• Et puis, vous pouvez modifier le css pour afficher la traduction dans votre couleur préférée.

Answer 3

Vous avez vous-même une question délicate. Il n'est pas vraiment une "meilleure pratique", car la plupart des logiciels sont développés en anglais.

Cela étant dit, si vous regardez les autres multilingue de la documentation, comment gèrent-ils ce problème?

Prenez Des Normes Internationales. Quelque chose comme la norme ISO 9001. Vous avez le même document (ISO 9001:2008) disponible en anglais, français, russe etc.

Ou ISO 5247-2 a l'un document en anglais+français+russe.

Comment géreriez-vous des changements? Dire que j'ai de vous donner un patch, mais mes commentaires sont en anglais seulement, quel serait votre processus? Que faire si vous avez Un patch en anglais, patch B en espagnol et en patch C en anglais + français?

Une autre option est de créer un fork. La principale branche de l'être en français avec la dernière version, puis mettez les autres langues jusqu'à ce jour dans leur propre temps?

Séparer les commentaires dans votre code source serait gênant pour maintenir. Vous êtes alors essentiellement à l'aide d'un fichier de ressources dans votre script de construction.

Est-ce un problème déjà? Si vous pensez que de toute grande, multilingue, projet open source, comment font-ils face?