Jak zlokalizować dokumentację biblioteki .NET

Question

Mam projekt open source (here), którego wersja documentation jest obecnie w języku francuskim. Dokumentacja jest generowana z komentarzy XML w kodzie, używając Sandcastle. Teraz chciałbym przetłumaczyć dokumentację na język angielski i dostarczyć dokumentację w obu językach, ale tak naprawdę nie wiem od czego zacząć ...

• Czy muszę wyodrębnić komentarze XML z kodu i umieścić je w osobnym pliku? Jeśli tak, czy są jakieś narzędzia do automatyzacji procesu?
• Używam Sandcastle Help File Builder do budowania dokumentacji; czy muszę utworzyć oddzielny projekt, aby zbudować dokument w języku angielskim, czy może to zrobić z tego samego projektu?
• Czy są jakieś narzędzia pomocne w procesie tłumaczenia? na przykład wyświetlić oryginał i przetłumaczony dokument obok siebie?

Jestem również zainteresowany linki dotyczące sposobu sporządzenia dokumentacji wielojęzyczny, bo nie mógł znaleźć coś pożytecznego w Google ...

Answer 1

Jedną ze strategii, które wymagają pewnej koordynacji z plików Sandcastle XSLT, byłoby użyć atrybutu xml:lang na dokumentacji XML. Visual Studio 2010 pozwala na zachowanie wielu tagów (chociaż możesz otrzymać skargi na duplikaty tagów).

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

wyjście Wynikające:

<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

Musisz się kłopotliwe. Tak naprawdę nie ma "najlepszej praktyki", ponieważ większość oprogramowania jest opracowywana w języku angielskim.

W związku z tym, jeśli spojrzeć na inne dokumenty wielojęzyczne, w jaki sposób radzą sobie z tym problemem?

Weź międzynarodowe standardy. Coś jak ISO 9001. Masz ten sam dokument (ISO 9001:2008) dostępny w języku angielskim, francuskim, rosyjskim itd.

Lub ISO 5247-2 ma jeden dokument w języku angielskim + francuski + rosyjski.

Jak radzić sobie ze zmianami? Powiedz, że dam ci łatkę, ale moje komentarze są tylko po angielsku, jaki byłby twój proces? Co jeśli masz łatkę A w języku angielskim, poprawkę B w języku hiszpańskim i poprawkę C w języku angielskim + francuskim?

Inną opcją jest rozwidlenie projektu. Czy główna gałąź jest w języku francuskim z najnowszą wersją, a następnie zaktualizować inne języki w swoim czasie?

Oddzielenie komentarzy w kodzie źródłowym byłoby kłopotliwe w utrzymaniu. Zasadniczo używasz pliku zasobów w swoim skrypcie kompilacji.

Czy to już rozwiązany problem? Jeśli myślisz o jakimkolwiek dużym, wielojęzycznym projekcie o otwartym kodzie źródłowym, jak sobie z nim radzą?

Answer 3

Zrobiliśmy to tak:

• Włożyliśmy "< PL>" tag Wszakże nasza dokumentacja tagu jak poniżej:

  /// <summary> 
  /// Description du produit 
  /// <EN>Product's description</EN> 
  /// </summary> 
  

• następnie w sandcastle pliku XSLT (rozwój /presentaton/vs2005/transforms/main_sandcastle.xsl) przeszliśmy do szablonu pasującego do "param" (linia 95 dla nas) i dodaliśmy

  <span class="trad"> 
      <xsl:value-of select="msxsl:node-set(.)/EN"/> 
  </span> 
  

• A następnie można zmienić css, aby wyświetlić tłumaczenie w ulubionym kolorze.

Answer 4

Jedną z możliwych strategii będzie o domyślny język w kodzie, a tłumaczenia zasilające osobno.

Bez względu na to, które języki są zlokalizowane, wolałbym wybrać język angielski jako domyślny/zastępczy język dokumentacji.

struktura Kodeks przewiduje indeksowanie dla bazy tłumaczeń, na przykład:

Type, NameWithNamespace, OptionalParameterName 

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

Można mieć narzędzie, które pozwoli na tłumaczenia w interfejsie dla każdego obszaru nazw/członka.

Możesz mieć oddzielny zespół tłumaczy przeglądających pozycje, które nie mają jeszcze tłumaczenia, i dostarczają tłumaczenia.

Możesz rozpocząć wysyłkę przetłumaczonej dokumentacji jako swojego statku, gdy tylko uzyskasz ilość przetłumaczonych pozycji powyżej progu.

Zmienione tłumaczenie domyślne oznacza, że ​​potrzebne jest nowe tłumaczenie dla wszystkich innych języków.

Oczywiście, jeśli zmieniasz tylko główne obszary nazw, możesz zmienić obszar nazw jako operację ponownego mapowania ad-hoc w bazie danych.

Jeśli uruchomisz projekt opensource, używa on narzędzia do tłumaczenia online.

Jednym z przykładów takiej współpracy realizowanej strategii tłumaczeniowej w produkcji jest https://translations.atlassian.com/

Zasadniczo można po prostu krok i rozpocząć wysyłanie tłumaczeń on-line.

Jest skonfigurowany do tłumaczenia samych produktów, a nie dokumentacji, ale obowiązuje ta sama praktyka.

Answer 5

Na wypadek, gdyby ktoś potrzebował rozwiązania, istnieje pakiet nuget o nazwie Surviveplus.XmlCommentLocalization. Oszałamiający!