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

Question

Tengo un proyecto de código abierto (here) cuyo documentation se encuentra 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 ...

• ¿Necesito 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? p.ej. mostrar el documento original y el documento traducido uno al lado del otro?

también estoy interesado en enlaces sobre cómo producir documentación multilingüe, ya que no pude encontrar nada útil en Google ...

Answer 1

Una de las estrategias, lo que requeriría algún tipo de coordinación con los archivos XSLT castillo de arena, sería utilizar 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; 
} 

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

Answer 2

Usted mismo un asunto difícil. 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?

Take International Standards. Algo así como ISO 9001. Tiene el mismo documento (ISO 9001:2008) disponible en inglés, francés, ruso, etc.

O ISO 5247-2 tiene el único 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 la separación de los comentarios en el código fuente sería complicado de mantener. Entonces, básicamente estás usando un archivo de recursos en tu script de compilación.

¿Este problema ya se ha solucionado? Si piensas en algún proyecto grande, multilingüe y de código abierto, ¿cómo lo manejan?

Answer 3

que lo hicimos así:

• ponemos un "< ES>" etiqueta después de todo nuestra etiqueta de la documentación de la siguiente manera:

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

• A continuación, en el archivo XSLT castillo de arena (Desarrollo /presentaton/vs2005/transforms/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 4

Una posible estrategia sería tener un idioma por defecto en el código, y traducciones por separado de suministro.

No importa qué idiomas localizada Me hubiera finalmente, preferiría elegir Inglés como idioma por defecto/repliegue de la documentación.

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

Type, NameWithNamespace, OptionalParameterName 

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

Se podría disponer de una herramienta que permita la traducción en una interfaz de usuario para cada espacio de nombres/miembro.

Usted puede tener un equipo independiente de traductores que buscan a través de los artículos que no tienen traducción todavía, y traducciones de suministro.

Y se puede empezar shipingand una documentación traducida como su buque un comunicado tan pronto como se obtiene la cantidad de artículos traducidos por encima de un umbral.

Una traducción omisión modificados que indicaría que necesita una nueva traducción para todos los otros idiomas también.

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 proyecto de código abierto, que hace que el SENCE de usar una herramienta colaborativa de traducción en línea.

Un ejemplo de esta estrategia de traducción colaborativa implementado en la producción es https://translations.atlassian.com/

Básicamente sólo podría intervenir y comenzar a contribuir traducciones en línea.

Se creó para traducir los productos en sí, no a la documentación, pero la misma práctica se aplica.

Answer 5

Por si alguien necesita una solución, hay un paquete nuget llamado Surviveplus.XmlCommentLocalization. ¡Maravilloso!