如何本地化 .NET 库的文档 [关闭]

Question

我有一个开源项目 (here)，其 documentation 目前是法语版本。该文档是使用 Sandcastle 从代码中的 XML cmets 生成的。现在我想将文档翻译成英文并提供两种语言的文档，但我真的不知道从哪里开始......

• 是否需要从代码中提取 XML cmets 并将它们放在单独的文件中？如果是，是否有任何工具可以自动化该过程？
• 我正在使用 Sandcastle Help File Builder 来构建文档；我需要创建一个单独的项目来构建英文文档，还是可以从同一个项目中完成？
• 是否有任何工具可以帮助翻译过程？例如并排显示原始文档和翻译文档？

我也对如何制作多语言文档的链接感兴趣，因为我在 Google 上找不到任何有用的东西...

Answer 1

需要与 Sandcastle XSLT 文件进行一些协调的一种策略是在 XML 文档中使用 xml:lang 属性。 Visual Studio 2010 允许保留多个标签（尽管您可能会收到有关重复标签的投诉）。

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

结果输出：

<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

我们是这样做的：

• 我们在所有文档标签之后添加了一个“”标签，如下所示：

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

• 然后在sandcastle xslt文件（Development/presentaton/vs2005/transforms/main_sandcastle.xsl）中，我们找到匹配“param”的模板（我们第95行）并添加了

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

• 然后您可以更改 css 以以您喜欢的颜色显示翻译。

Answer 3

一种可能的策略是在代码中使用默认语言，并单独提供翻译。

无论我最终会使用哪种本地化语言，我都更愿意选择英语作为文档的默认/备用语言。

代码结构为您的翻译数据库提供索引，例如：

Type, NameWithNamespace, OptionalParameterName

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

您可以拥有一个工具，允许在 UI 中为每个命名空间/成员进行翻译。

您可以让一个单独的翻译团队查看尚未翻译的项目，并提供翻译。

一旦您的翻译项目数量超过阈值，您就可以在发布版本时开始发布翻译文档。

更改的默认翻译表明您也需要所有其他语言的新翻译。

当然，如果您只对命名空间进行重大更改，您可以将命名空间重新映射为数据库中的临时重新映射操作。

如果您运行开源项目，使用协作在线翻译工具是有意义的。

在生产中实施的这种协作翻译策略的一个例子是 https://translations.atlassian.com/

基本上你可以介入并开始在线贡献翻译。

它被设置为翻译产品本身，而不是文档，但同样的做法适用。

Answer 4

你有一个棘手的问题。由于大多数软件都是用英语开发的，因此确实没有“最佳实践”。

话虽如此，如果您查看其他多语言文档，他们是如何处理这个问题的？

采用国际标准。像ISO 9001 这样的东西。您拥有相同的文档 (ISO 9001:2008)，提供英语、法语、俄语等版本。

或者ISO 5247-2有一份英文+法文+俄文的文档。

您将如何处理更改？假设我给你一个补丁，但我的 cmets 只有英文，你的流程是什么？如果您有英语补丁 A、西班牙语补丁 B 和英语 + 法语补丁 C，该怎么办？

另一种选择是分叉项目。主分支是否使用最新版本的法语版本，然后在自己的时间将其他语言更新到最新版本？

在源代码中分离 cmets 会导致维护起来很麻烦。然后，您基本上是在构建脚本中使用资源文件。

这是一个已经解决的问题吗？如果您想到任何大型、多语言、开源项目，他们是如何处理的？

Answer 5

以防万一有人需要解决方案，有一个名为 Surviveplus.XmlCommentLocalization 的 nuget 包。太棒了！