Question

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

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

我也对如何制作多语言文档的链接感兴趣，因为我在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

我们这样做了：

我们放了一个“＆lt; EN＆gt;”标记在我们所有的文档标记之后：

/// <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中为每个命名空间/成员进行翻译。

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

一旦您将翻译项目的数量超过阈值，您就可以开始将翻译后的文档作为发布的文件发布。

更改后的默认翻译表明您还需要为所有其他语言翻译新内容。

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

如果您运行opensource项目，则可以使用协作式在线翻译工具。

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

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

它的目的是翻译产品本身，而不是文档，但同样的做法也适用。

Answer 4

你有一个棘手的问题。实际上并没有“最佳实践”，因为大多数软件都是用英语开发的。

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

采取国际标准。像ISO 9001这样的东西。您有相同的文档（ISO 9001:2008），提供英语，法语，俄语等。

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

你会如何应对变化？说我给你一个补丁，但我的评论只有英文，你的过程是什么？如果您有英文补丁A，西班牙语补丁B和英语+法语补丁C怎么办？

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

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

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

Answer 5

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

如何本地化.NET库的文档

5 个答案: