35

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

4

5 回答 5

21

一种需要与 Sandcastle XSLT 文件协调的策略是使用xml:langXML 文档中的属性。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>
于 2011-06-07T15:29:51.563 回答
6

我们这样做了：

  • 我们在所有文档标签之后放置了一个“<EN>”标签，如下所示：

    /// <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 以您喜欢的颜色显示翻译。

于 2011-06-07T15:01:43.450 回答
2

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

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

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

Type, NameWithNamespace, OptionalParameterName

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

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

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

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

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

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

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

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

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

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

于 2015-09-01T13:27:56.643 回答
1

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

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

采用国际标准。类似于ISO 9001的东西。您有相同的文件 ( ISO 9001:2008 )，有英文、法文、俄文等版本。

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

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

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

分离源代码中的注释会使维护变得混乱。然后，您基本上是在构建脚本中使用资源文件。

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

于 2011-06-05T22:54:15.057 回答
1

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

于 2015-10-20T09:59:23.930 回答