Cách bản địa hóa tài liệu của thư viện .NET

Question

Tôi có một dự án mã nguồn mở (here) có số documentation hiện có bằng tiếng Pháp. Tài liệu được tạo ra từ các chú thích XML trong mã, sử dụng Sandcastle. Bây giờ tôi muốn dịch tài liệu sang tiếng Anh và cung cấp tài liệu bằng cả hai ngôn ngữ, nhưng tôi thực sự không biết bắt đầu từ đâu ...

• Tôi có cần trích xuất các nhận xét XML từ mã và đặt chúng trong một tệp riêng biệt? Nếu có, có công cụ nào để tự động hóa quy trình không?
• Tôi đang sử dụng Trình tạo tệp trợ giúp Sandcastle để xây dựng tài liệu; tôi có cần phải tạo một dự án riêng để xây dựng tài liệu bằng tiếng Anh hay nó có thể được thực hiện từ cùng một dự án không?
• Có công cụ nào để trợ giúp trong quá trình dịch không? ví dụ. hiển thị tài liệu gốc và được dịch bên cạnh?

Tôi cũng quan tâm đến việc liên kết trên làm thế nào để tạo ra tài liệu đa ngôn ngữ, như tôi không thể tìm thấy bất cứ điều gì hữu ích trên Google ...

Answer 1

Một chiến lược cần có sự phối hợp với tệp Sandcastle XSLT, sẽ sử dụng thuộc tính xml:lang trên tài liệu XML của bạn. Visual Studio 2010 cho phép nhiều thẻ vẫn còn (mặc dù bạn có thể nhận được khiếu nại về các thẻ trùng lặp).

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

Kết quả đầu ra:

<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

Bạn có cho mình một ai khéo léo. Có thực sự không phải là một "thực hành tốt nhất" vì hầu hết các phần mềm được phát triển bằng tiếng Anh.

Điều đó đang được nói, nếu bạn xem tài liệu đa ngôn ngữ khác, cách xử lý vấn đề này?

Lấy tiêu chuẩn quốc tế. Một cái gì đó như ISO 9001. Bạn có cùng tài liệu (ISO 9001:2008) có sẵn bằng tiếng Anh, tiếng Pháp, tiếng Nga, v.v.

Hoặc ISO 5247-2 có một tài liệu bằng tiếng Anh + tiếng Pháp + tiếng Nga.

Bạn xử lý các thay đổi như thế nào? Nói rằng tôi đưa cho bạn một bản vá, nhưng nhận xét của tôi chỉ bằng tiếng Anh, quy trình của bạn sẽ là gì? Nếu bạn có bản vá A bằng tiếng Anh, bản vá B bằng tiếng Tây Ban Nha và bản vá C bằng tiếng Anh + tiếng Pháp thì sao?

Một tùy chọn khác là ngã ba dự án. Có chi nhánh chính bằng tiếng Pháp với bản dựng mới nhất, sau đó đưa các ngôn ngữ khác cập nhật vào thời điểm riêng của họ?

Tách nhận xét trong mã nguồn của bạn sẽ bị lộn xộn để duy trì. Về cơ bản, bạn đang sử dụng một tệp tài nguyên trong tập lệnh xây dựng của mình.

Đây có phải là sự cố đã được giải quyết chưa? Nếu bạn nghĩ về bất kỳ dự án nguồn mở đa ngôn ngữ lớn nào, thì họ xử lý nó như thế nào?

Answer 3

Chúng tôi đã làm điều đó như thế này:

• Chúng tôi đặt một "< EN>" tag sau khi tất cả thẻ tài liệu hướng dẫn của chúng tôi như thế này:

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

• Sau đó, trong tập tin XSLT lâu đài cát (Phát triển /presentaton/vs2005/transforms/main_sandcastle.xsl) chúng tôi đã đi đến mẫu khớp với "param" (dòng 95 cho chúng tôi) và chúng tôi đã thêm

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

• Và sau đó bạn có thể thay đổi css để hiển thị bản dịch theo màu yêu thích của bạn.

Answer 4

Một chiến lược có thể sẽ có một ngôn ngữ mặc định trong mã, và cung cấp dịch riêng rẽ.

Cho dù tôi có ngôn ngữ bản địa hóa nào, tôi cũng muốn chọn tiếng Anh làm ngôn ngữ mặc định/dự phòng của tài liệu.

cấu trúc luật quy định chỉ mục cho cơ sở dữ liệu dịch của bạn, ví dụ:

Type, NameWithNamespace, OptionalParameterName 

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

Bạn có thể có một công cụ mà sẽ cho phép dịch trong một giao diện người dùng cho mỗi namespace/thành viên.

Bạn có thể có một nhóm dịch giả riêng biệt xem qua các mục chưa có bản dịch và cung cấp bản dịch.

Và bạn có thể bắt đầu gửi tài liệu đã dịch làm bản phát hành của mình ngay sau khi bạn nhận được số lượng bản dịch đã dịch ở trên ngưỡng.

Bản dịch mặc định đã thay đổi sẽ cho biết rằng bạn cũng cần bản dịch mới cho tất cả các ngôn ngữ khác.

Tất nhiên, nếu bạn thực hiện một thay đổi chỉ không gian tên lớn, bạn có thể remap không gian tên dưới dạng thao tác remapping ad-hoc trong cơ sở dữ liệu.

Nếu bạn chạy dự án mã nguồn mở, nó giúp tạo ra một công cụ dịch thuật trực tuyến hợp tác.

Một ví dụ về chiến lược hợp tác dịch như vậy được thực hiện trong sản xuất là https://translations.atlassian.com/

Về cơ bản bạn chỉ có thể bước vào và bắt đầu đóng góp bản dịch trực tuyến.

Nó được thiết lập để dịch các sản phẩm, chứ không phải tài liệu, nhưng thực hành tương tự cũng được áp dụng.

Answer 5

Chỉ trong trường hợp bất kỳ ai cần giải pháp, có gói nuget gọi là Surviveplus.XmlCommentLocalization. Kinh ngạc!