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

Tengo un proyecto de código abierto ( aquí ) cuya documentación 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 …

  • ¿Necesito extraer los comentarios XML del código y colocarlos en un archivo separado? En caso afirmativo, ¿existen herramientas para automatizar el proceso?
  • Estoy usando Sandcastle Help File Builder para construir la documentación; ¿Necesito crear un proyecto separado para comstackr el documento en inglés o se puede hacer desde el mismo proyecto?
  • ¿Hay alguna herramienta para ayudar en el proceso de traducción? Por ejemplo, ¿mostrar el documento original y traducido lado a lado?

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

Una estrategia, que requeriría una 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 tags (aunque puede recibir quejas sobre tags duplicadas).

 ///  /// Gets or sets the fill size of the load operation. ///  ///  /// Obtient ou définit la taille de remplissage de l'opération de chargement. ///  public int FillSize { get; set; } 

Resultado resultante:

   Gets or sets the fill size of the load operation.   Obtient ou définit la taille de remplissage de l'opération de chargement.   

Lo hicimos así:

  • Ponemos una etiqueta “” después de toda nuestra etiqueta de documentación como esta:

     ///  /// Description du produit /// Product's description ///  
  • Luego, en el archivo xslt de sandcastle (Development / presentaton / vs2005 / transforms / main_sandcastle.xsl) fuimos a la plantilla que coincide con “param” (línea 95 para nosotros) y agregamos

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

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

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

La estructura de 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 permitiría la traducción en una IU para cada espacio de nombres / miembro.

Puede tener un equipo de traductores por separado para revisar los elementos que aún no tienen traducción y proporcionar traducciones.

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

Una traducción predeterminada modificada 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 volver a asignar los espacios de nombres como una operación de reasignación ad-hoc en la base de datos.

Si ejecuta el proyecto de código abierto, tiene sentido utilizar una herramienta de traducción en línea de colaboración.

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

Básicamente, puedes ingresar y comenzar a contribuir con traducciones en línea.

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

Te tienes uno complicado. Realmente no existe una “mejor práctica” ya que la mayoría del software se desarrolla en inglés.

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

Tomar las normas internacionales. 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 te doy un parche, pero mis comentarios solo están en inglés, ¿cuál sería tu proceso? ¿Qué sucede si tiene 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 twig principal está en francés con la última versión, y luego actualizar los otros idiomas en su propio tiempo?

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

¿Es este un problema resuelto ya? Si piensa en un proyecto grande, multilingüe y de código abierto, ¿cómo lo manejan?

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