Multilanguage <summary> (xml doc) support in roslyn/Visual Studio

Topics: C# Language Design
Sep 5, 2014 at 8:43 AM
Problem is described here: http://stackoverflow.com/questions/6221140/how-to-localize-the-documentation-of-a-net-library

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

It will be very usefull if Visual Studio supports 'language order' of displaying IntelliSense data and popups from xml doc. For example (ru,en,sr,fr).
Roslyn CTP in Visual Studio 2013 displays FIRST summary in declaration.
Sep 5, 2014 at 9:12 AM
Like!
Sep 5, 2014 at 4:44 PM
Yeah but there are other dev's that even complain about a single <summary> tag, having multiple language documentation, for example in Microsoft dimensions, would need you to scroll 3 screens of XML documentation away before you can get to the method. But it would not hurt to have this feature
Sep 5, 2014 at 4:53 PM
I see one big project that contains xml docs in english,russian,serbian and french

2Suchiman - <summary> must be short. Longer comments must be in <remarks>. And <remarks> are not displaying by IDE.
Developer
Sep 5, 2014 at 5:46 PM
This is a neat idea, though it may be worth noting that one can work around this deficiency by using conditional compilation tools in the preprocessor. Consider the following:
#if GermanVersion
       /// <summary>
       /// Ich esse Obst.
       /// </summary>
#else
        /// <summary>
        /// I am eating fruit.
        /// </summary>
#endif
public void Eat() { /*Do Something*/ }
Note, primitive summary is indicative of my elementary knowledge of German.

-Marstr
Sep 7, 2014 at 9:58 PM
Mads, Alexei is proposing something that will be resolved per user at run time, Your workaround is compile time only.
Sep 8, 2014 at 9:40 AM
I'm a Spanish developer working in Germany, both non-English countries where English is not generally known.

Still, I think localizing for developers is a mistake. The documentation should be in the same language the API is, and unlocalizing error messages intended for the developer is a pain in the ass.

Additionally, if something like this is done seriously, with at least 10 translate languages, it will be hard to find any C# among so many translated comments.
Developer
Sep 8, 2014 at 7:04 PM
PauloMorgado wrote:
Mads, Alexei is proposing something that will be resolved per user at run time, Your workaround is compile time only.
While comments are only included as metadata in dll's, you are right that my work around omits some metadata that Alexei's proposal would include.

-Martin
Sep 9, 2014 at 10:44 PM
I think localization shouldn't happen in the source files (except for the neutral language) but after the XML documentation is generated.

We seem to have already some support for this in Visual Studio, this is how the documentation for the BCL is localized. Documentation in the neutral language is stored in assembly.xml and localized variants in sub-folders <lang-id>\assembly.xml where <lang-id> is "de" for German, "fr" for French, etc. Visual Studio then picks the documentation for IntelliSense according to the language setting of the developer's machine.
Sep 10, 2014 at 1:41 AM
Olmo wrote:
I'm a Spanish developer working in Germany, both non-English countries where English is not generally known.

Still, I think localizing for developers is a mistake. The documentation should be in the same language the API is, and unlocalizing error messages intended for the developer is a pain in the ass.
I believe supporting localization of the XML docs is already supported for compiled assemblies where each language is contained within its own separated XML file suffixed with the locale. This request probably applies to the current project where Intellisense parses XML docs in the comments.
Additionally, if something like this is done seriously, with at least 10 translate languages, it will be hard to find any C# among so many translated comments.
I agree. At that point the source file would be mostly comments. It would be nice if Visual Studio could consider a convention for regular XML file fragments to drive Intellisense so that XML docs could be contained separately from the source, e.g. Namespace.Class.doc.en-us.xml. Separate tooling support could be provided to combine all of those fragments into the final XML file.

It kind of annoys me how much of the source file is dedicated to XML documentation just with a single language. I periodically look to see if any extensions have been published to hide the XML comments collapsing them into something like an Information icon in the margin or something but I haven't found anything yet. It would probably be really easy to write an extension that would collapse XML comment sections by default when opening a source file, but I'm lazy and haven't bothered writing one.
Sep 10, 2014 at 7:26 PM
Halo_Four wrote:
It kind of annoys me how much of the source file is dedicated to XML documentation just with a single language. I periodically look to see if any extensions have been published to hide the XML comments collapsing them into something like an Information icon in the margin or something but I haven't found anything yet. It would probably be really easy to write an extension that would collapse XML comment sections by default when opening a source file, but I'm lazy and haven't bothered writing one.
Maybe this plugin is useful for you.
Sep 11, 2014 at 12:50 AM
christoph_hausner wrote:
Halo_Four wrote:
It kind of annoys me how much of the source file is dedicated to XML documentation just with a single language. I periodically look to see if any extensions have been published to hide the XML comments collapsing them into something like an Information icon in the margin or something but I haven't found anything yet. It would probably be really easy to write an extension that would collapse XML comment sections by default when opening a source file, but I'm lazy and haven't bothered writing one.
Maybe this plugin is useful for you.
Aha, I had been looking for something more specific to XML documentation comments, but yes, this looks like it might do nicely. It would be nice if the hover-over for XML documentation would be formatted nicely but at least this puts them out of the way until I want to see them. Thanks!
Sep 12, 2014 at 2:18 PM
christoph_hausner wrote:
I think localization shouldn't happen in the source files (except for the neutral language) but after the XML documentation is generated.

We seem to have already some support for this in Visual Studio, this is how the documentation for the BCL is localized. Documentation in the neutral language is stored in assembly.xml and localized variants in sub-folders <lang-id>\assembly.xml where <lang-id> is "de" for German, "fr" for French, etc. Visual Studio then picks the documentation for IntelliSense according to the language setting of the developer's machine.
For non-english developers language setting of Windows OS may not match xml comments language
Real example: Windows UI can be 'English', DateTime and Currency can be 'Serbian' and Visual Studio language is in 99.9% - English
Sep 12, 2014 at 2:26 PM
Halo_Four wrote:
This request probably applies to the current project where Intellisense parses XML docs in the comments.
Yes, this is problem only if code from one team is transfered to other to adopt solution to other country 'reality'.