This project has moved and is read-only. For the latest updates, please go here.

Filtering documentation comments

May 29, 2008 at 8:12 AM
We usually write our documentation comments in two or more languages identifying the language with the "lang" attribute in each XML tag. Example:

<summary lang="hu">
magyar szöveg
<summary lang="en">
English text

Is it possible with SHFB (or Sandcastle) to filter these comments when building documentation and only use for example english comments?
Is there a (standard) way to do multi-language documentation comments?


May 29, 2008 at 4:16 PM
Edited May 29, 2008 at 4:16 PM
No comments tags support an attribute for localization.  There are no provisions within the Sandcastle transformations to select comments based on language either.  I believe the way some are doing it is to maintain separate XML comments files for each language (not within the code).  You can set the language in SHFB and it will adjust its selection of framework comments and resources based on the language selected but you would still need separate projects for each language with the appropriate comments files selected in each for your assemblies.

May 30, 2008 at 10:58 AM
Thank you, Eric! I will maintain separate comments files.
Now what should I do to have framework comments in different language than English? I have already installed LanguagePack for .NET and selected that language in SHFB but framework comments are still in englis.

May 30, 2008 at 4:11 PM
I didn't know there was a language pack.  Do you have the URL?  In the next SHFB release, I took a guess at how multi-language support might work based on how VS2008 installed the comments files.  Since there's a language pack, I'll see about supporting it too if it works differently.

Jun 2, 2008 at 7:44 AM
The language pack is here. As I can see it does not install any localized XML for texts so this is not the solution I am looking for. Maybe I should install a localized .NET version.

Jun 3, 2008 at 9:11 PM

It looks like the language pack just installs localized text for the messages in the assemblies.  You can download .NET for a specific language and then install it on a test machine or in a virtual machine to get the XML comments files for the language.  Somebody else asked about the comments files and I think that's what they ended up doing.  Not an efficient means of doing it but it works.