net - remarks c#

Cómo localizar la documentación de una biblioteca.NET

Question

Tengo un proyecto de código abierto ( here ) cuya documentation está actualmente en francés. La documentación se genera a partir de comentarios XML en código, utilizando Sandcastle. Ahora me gustaría traducir la documentación al inglés y proporcionar documentación en ambos idiomas, pero realmente no sé por dónde empezar ...

• ¿Debo extraer los comentarios XML del código y ponerlos en un archivo separado? En caso afirmativo, ¿hay alguna herramienta para automatizar el proceso?
• Estoy usando Sandcastle Help File Builder para compilar la documentación; ¿Necesito crear un proyecto separado para construir el documento en inglés, o puedo hacerlo desde el mismo proyecto?
• ¿Hay alguna herramienta para ayudar en el proceso de traducción? por ejemplo, mostrar el documento original y el documento traducido uno al lado del otro?

También me interesan los enlaces sobre cómo producir documentación multilingüe, ya que no pude encontrar nada útil en Google ...

Answer 1

En caso de que alguien necesite una solución, hay un paquete Surviveplus.XmlCommentLocalization llamado Surviveplus.XmlCommentLocalization . ¡Maravilloso!

Answer 2

Lo hicimos así:

• Colocamos una etiqueta "<EN>" después de toda nuestra etiqueta de documentación como esta:

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

• Luego en el archivo sandcastle xslt (Desarrollo / presentación / vs2005 / transformaciones / main_sandcastle.xsl) fuimos a la plantilla que coincide con "param" (línea 95 para nosotros) y agregamos

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

• Y luego puede cambiar el CSS para mostrar la traducción en su color favorito.

Answer 3

Una estrategia posible sería tener un lenguaje predeterminado en el código y suministrar traducciones por separado.

No importa qué idiomas localizados tendría finalmente, preferiría elegir el inglés como el idioma predeterminado / alternativo de la documentación.

La estructura del código proporciona indexación para su base de datos de traducción, por ejemplo:

Type, NameWithNamespace, OptionalParameterName

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

Podría tener una herramienta que permita la traducción en una interfaz de usuario para cada espacio de nombre / miembro.

Puede tener un equipo de traductores separado que revise los elementos que todavía no tienen traducción y que proporcionen traducciones.

Y puede comenzar a enviar una documentación traducida como un envío de su barco tan pronto como obtenga la cantidad de artículos traducidos por encima de un umbral.

Una traducción predeterminada cambiada indicaría que también necesita una nueva traducción para todos los demás idiomas.

Por supuesto, si realiza cambios importantes solo en el espacio de nombres, puede reasignar los espacios de nombres como una operación de reasignación ad-hoc en la base de datos.

Si ejecuta un proyecto de código abierto, utiliza una herramienta de traducción en línea colaborativa.

Un ejemplo de dicha estrategia de traducción colaborativa implementada en producción es https://translations.atlassian.com/

Básicamente, puede intervenir y comenzar a contribuir traducciones en línea.

Está configurado para traducir los productos en sí mismos, no la documentación, pero se aplica la misma práctica.

Answer 4

Usted mismo tiene una trampa. Realmente no hay una "mejor práctica" ya que la mayoría del software se desarrolla en inglés.

Dicho esto, si mira otra documentación multilingüe, ¿cómo manejan este problema?

Toma estándares internacionales. Algo como ISO 9001 . Tiene el mismo documento ( ISO 9001: 2008 ) disponible en inglés, francés, ruso, etc.

O ISO 5247-2 tiene el documento en inglés + francés + ruso.

¿Cómo manejarías los cambios? Digamos que le doy un parche, pero mis comentarios solo están en inglés, ¿cuál sería su proceso? ¿Qué pasa si tienes el parche A en inglés, el parche B en español y el parche C en inglés + francés?

Otra opción es bifurcar el proyecto. ¿La rama principal debe estar en francés con la última compilación, y luego actualizar los otros idiomas en su propio tiempo?

Separar los comentarios en su código fuente sería complicado de mantener. Entonces, básicamente estás usando un archivo de recursos en tu script de compilación.

¿Ya es un problema resuelto? Si piensas en algún proyecto grande, multilingüe y de código abierto, ¿cómo lo manejan?

Answer 5

Una estrategia, que requeriría cierta coordinación con los archivos XSLT de Sandcastle, sería usar el atributo xml:lang en su documentación XML. Visual Studio 2010 permite que permanezcan varias etiquetas (aunque puede recibir quejas sobre etiquetas duplicadas).

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

Resultado resultante:

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