Как локализовать документацию библиотеки .NET

У меня есть проект с открытым исходным кодом (здесь), документация в настоящее время находится на французском языке. Документация создается из комментариев XML в коде, используя Sandcastle. Теперь я хотел бы перевести документацию на английский язык и предоставить документацию на обоих языках, но я не знаю, с чего начать...

Нужно ли извлекать комментарии XML из кода и помещать их в отдельный файл? Если да, есть ли какие-либо инструменты для автоматизации процесса?
Я использую Builder Builder для создания документации; мне нужно создать отдельный проект для создания документа на английском языке или это можно сделать из того же проекта?
Есть ли какие-либо инструменты для перевода в процессе перевода? например отображать оригинал и переведенный документ бок о бок?

Мне также интересны ссылки о том, как создавать многоязычную документацию, поскольку я не нашел ничего полезного в Google...

Ответ 1

Одна стратегия, которая потребует некоторой координации с файлами Sandcastle XSLT, заключается в использовании атрибута xml:lang в вашей документации XML. 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>

Ответ 2

Мы сделали это вот так:

Мы помещаем тег "<EN> " после всего нашего тега документации следующим образом:
```
/// <summary>
/// Description du produit
/// <EN>Product 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, чтобы отобразить перевод в вашем любимом цвете.

Ответ 3

У тебя своя сложная задача. Там действительно нет "лучшей практики", поскольку большинство программ разработано на английском языке.

Как говорится, если вы посмотрите на другую многоязычную документацию, как они справляются с этой проблемой?

Возьмите международные стандарты. Что-то вроде ISO 9001. У вас есть тот же документ (ISO 9001: 2008) на английском, французском, русском и т.д.

Или ISO 5247-2 имеет один документ на английском + французский + русский.

Как бы вы справились с изменениями? Скажем, я даю вам патч, но мои комментарии только на английском языке, каков будет ваш процесс? Что делать, если у вас есть патч A на английском языке, патч B на испанском языке и патч C на английском + французский?

Другой вариант - разветкить проект. У вас есть главная ветвь на французском языке с последней сборкой, а затем обновить другие языки в свое время?

Отсоединение комментариев в исходном коде будет беспорядочно поддерживать. Затем вы в основном используете файл ресурсов в своей сборке script.

Является ли эта проблема решена? Если вы думаете о каком-либо крупном многоязычном проекте с открытым исходным кодом, как он справляется с этим?

Ответ 4

Одна из возможных стратегий заключалась бы в использовании языка по умолчанию в коде и перевода переводов отдельно.

Независимо от того, какие локализованные языки у меня были бы в конечном итоге, я бы предпочел выбрать английский как язык по умолчанию/резервный документ.

Структура кода обеспечивает индексацию для вашей базы данных перевода, например:

Type, NameWithNamespace, OptionalParameterName

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

У вас может быть инструмент, который позволит выполнять перевод в пользовательском интерфейсе для каждого пространства имен/члена.

У вас может быть отдельная команда переводчиков, просматривающая предметы, которые еще не имеют перевода, и перевод переводов.

И вы можете начать отправку переведенной документации в качестве выпуска своего корабля, как только вы получите количество переведенных предметов выше порога.

Измененный перевод по умолчанию указывает, что вам нужен новый перевод для всех других языков.

Конечно, если вы выполняете основные изменения только для пространства имен, вы можете переназначить пространства имен в качестве операции повторного переопределения ad-hoc в базе данных.

Если вы запускаете проект с открытым исходным кодом, он использует инструмент совместного интерактивного перевода.

Одним из примеров такой стратегии совместного перевода, реализованной в производстве, является https://translations.atlassian.com/

В принципе, вы можете просто вступить и начать вносить переводы онлайн.

Он настроен для перевода самих продуктов, а не документации, но применяется та же практика.

Ответ 5

На всякий случай, если кому-то нужно решение, пакет nuget называется Surviveplus.XmlCommentLocalization. Потрясающие!