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

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

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

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

источник

2011-06-02 Thomas Levesque

вот почему мы делаем все комментарии на английском языке :) –

@ Аndreas, это то, что я обычно делаю ... но этот проект является особым случаем, поскольку он изначально предназначался для членов франкоязычного сообщества (Developpez .com). Теперь я хотел бы расширить аудиторию этой библиотеки ... –

Одна стратегия, которая потребует некоторой координации с файлами 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>

источник

2011-06-07 15:29:51 user7116

Спасибо, мне нравится этот подход! Это похоже на решение, предложенное Реми Бургарелом, но оно чувствует себя чистым ... –

Я никогда не находил время, чтобы на самом деле попробовать, но это ответ, который мне больше всего нравится, поэтому я принимаю его;) –

Я не был в состоянии найти любую документацию о том, как сделать эту работу. Когда я попробовал это, я просто открываю оба языка в моем файле chm. Любые подсказки о том, как это сделать «координация с файлами Sandcastle XSLT»? –

Вы сам хитрый. На самом деле не существует «лучшей практики», поскольку большинство программ разработано на английском языке.

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

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

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

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

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

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

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

источник

2011-06-05 22:54:15

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

Ставит "< EN>" тег после всей нашей документации тега, как это:
```
/// <summary> 
/// Description du produit 
/// <EN>Product's description</EN> 
/// </summary> 
```
Затем в SandCastle файл XSLT (разработка /presentaton/vs2005/transforms/main_sandcastle.xsl) мы перешли к шаблону, соответствующему параметру «param» (строка 95 для нас), и мы добавили
```
<span class="trad"> 
    <xsl:value-of select="msxsl:node-set(.)/EN"/> 
</span> 
```
И затем вы можете изменить css, чтобы отобразить перевод в вашем любимом цвете.

источник

2011-06-07 15:01:43

Это выглядит многообещающим, спасибо! Но он отображает оба языка на одной странице, не так ли? Я хотел бы сгенерировать две отдельные документы ... –

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

BTW, вы помещаете этот тег EN только в сводку или во все поля документации (параметры, возвращаемые значения и т. Д.)? –

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

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

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

Type, NameWithNamespace, OptionalParameterName 

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

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

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

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

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

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

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

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

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

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

источник

2015-09-01 13:27:56

Да, я думаю, что переводные документы, отделенные от кода, являются единственным разумным способом сделать это в общем случае. Мой вариант использования был немного другим, потому что я никогда не собирался предоставлять более двух языков; поэтому было бы разумно иметь оба языка в коде, что упростило бы обновление. –

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

источник

2015-10-20 09:59:23

Хорошо, но что он делает? Нет документации, нет сайта проекта, а сайт surviveplus.net находится на японском языке ... –

Он просто создает автономный xml на другом языке. Таким образом, вы получаете несколько xml-файлов. И каждый из них может обрабатываться отдельно вашим любимым инструментом. например sandcastle –

Да, но как он генерирует эти файлы? Вы указываете язык в комментариях к документу? –

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

ответ

Смежные вопросы