Come localizzare la documentazione di una libreria .NET

Question

Ho un progetto open source (here) il cui documentation è attualmente in francese. La documentazione è generata dai commenti XML nel codice, utilizzando Sandcastle. Ora vorrei tradurre la documentazione per l'inglese e fornire la documentazione in entrambe le lingue, ma io non so davvero da dove cominciare ...

• Ho bisogno di estrarre i commenti XML dal codice e metterli in un file separato? Se sì, ci sono strumenti per automatizzare il processo?
• Uso il Generatore di file di aiuto di Sandcastle per creare la documentazione; ho bisogno di creare un progetto separato per costruire il doc in inglese, o può essere fatto dallo stesso progetto?
• Esistono strumenti per aiutare nel processo di traduzione? per esempio. visualizzare il documento originale e tradotto fianco a fianco?

Sono anche interessato a link su come produrre documentazione multilingue, come io non riuscivo a trovare nulla di utile su Google ...

Answer 1

Una strategia, che richiederebbe un coordinamento con i file XSLT Sandcastle, sarebbe quella di utilizzare l'attributo xml:lang sulla documentazione XML. Visual Studio 2010 consente di mantenere più tag (anche se è possibile che si verifichino reclami relativi a tag duplicati).

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

uscita risultante:

<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

avete voi stessi un ingannevole. Non c'è davvero una "migliore pratica" dal momento che la maggior parte del software è sviluppato in inglese.

Detto questo, se si guarda ad altra documentazione multilingue, come gestiscono questo problema?

Prendere gli standard internazionali. Qualcosa come ISO 9001. Hai lo stesso documento (ISO 9001:2008) disponibile in inglese, francese, russo, ecc.

o ISO 5247-2 ha l'unico documento in inglese + francese + russo.

Come gestiresti le modifiche? Dite che vi do una patch, ma i miei commenti sono solo in inglese, quale sarebbe il vostro processo? Cosa succede se hai la patch A in inglese, la patch B in spagnolo e la patch C in inglese + francese?

Un'altra opzione è quella di eseguire il fork del progetto. Il ramo principale deve essere in francese con l'ultima build, quindi aggiornare le altre lingue nel loro tempo?

Separare i commenti nel codice sorgente sarebbe difficile da mantenere. Quindi stai utilizzando fondamentalmente un file di risorse nel tuo script di compilazione.

Si tratta di un problema risolto già? Se pensi a un grande progetto multi-lingua, open source, come lo gestiscono?

Answer 3

L'abbiamo fatto in questo modo:

• abbiamo messo un "< EN>" tag, dopo tutto il nostro tag documentazione in questo modo:

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

• Poi nel file XSLT castello di sabbia (Sviluppo /presentaton/vs2005/transforms/main_sandcastle.xsl) siamo andati al modello corrispondente a "param" (riga 95 per noi) e abbiamo aggiunto

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

• E quindi puoi cambiare il css per visualizzare la traduzione nel tuo colore preferito.

Answer 4

Una possibile strategia sarebbe avere una lingua predefinita nel codice, e traduzioni separatamente, gli appalti.

Non importa quale localizzato lingue avrei finalmente, preferisco scegliere l'inglese come lingua predefinita/fallback della documentazione.

Struttura codice prevede l'indicizzazione per il database di traduzione, per esempio:

Type, NameWithNamespace, OptionalParameterName 

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

Si potrebbe avere uno strumento che consenta di traduzione in un'interfaccia utente per ogni spazio dei nomi/utente.

si può avere un team separato di traduttori guardando attraverso gli elementi che non hanno traduzione ancora, e traduzioni di alimentazione.

E si può iniziare shiping una documentazione tradotta come la vostra nave una release non appena si ottiene la quantità di articoli tradotti di sopra di una soglia.

Una traduzione predefinita modificata indica che è necessaria una nuova traduzione anche per tutte le altre lingue.

Naturalmente, se si fa un grandi cambiamenti namespace-only, è possibile rimappare gli spazi dei nomi come un'operazione ad hoc rimappatura nel database.

Se si esegue il progetto opensource, è necessario utilizzare uno strumento di traduzione online collaborativo.

Un esempio di tale strategia di traduzione collaborativa attuata nella produzione è https://translations.atlassian.com/

In pratica si può solo intervenire e iniziare a contribuire traduzioni on-line.

Si è impostato per tradurre i prodotti stessi, non la documentazione, ma applicare la stessa pratica.

Answer 5

Solo nel caso qualcuno ha bisogno di una soluzione c'è il pacchetto NuGet chiamato Surviveplus.XmlCommentLocalization. Sbalorditivo!