如何本地化的文档.NET库

本文关键字：NET 文档 本地化 | 更新日期: 2023-09-27 17:58:13

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

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

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

如何本地化的文档.NET库

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

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

我们是这样做的：

  • 我们在所有文档标签后面加了一个"<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，以你喜欢的颜色显示翻译。

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

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

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

Type, NameWithNamespace, OptionalParameterName
"member", "MyProject.Core.Loader.FillSize", ...

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

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

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

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

当然，若只更改主要的名称空间，则可以将名称空间重新映射为数据库中的特殊重新映射操作。

若你们运行开源项目，那个么使用一个协作的在线翻译工具是有意义的。

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

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

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

只要有人需要解决方案，就有一个名为Surviveplus的nuget包。XmlCommentLocalization。惊人的

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

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

以国际标准为例。类似于ISO9001。您有相同的文件（ISO 9001:2008），有英文、法文、俄文等版本。

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

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

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

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

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

相关文章：