Detect Localized xml Files

[Herrmel]

Hello it's me again 😁

sorry to bother you once again but I have a small enhancement regarding localization. My comments are German, so when I use inheritdoc, it is mixed between German and Englisch. Microsoft does provide some localized Commentfiles for Intellisense. As you can see in the Link, the files are placed in a Folder with the specific languagetag, so for me it's de. My Idea would be to look for a folder matching some version of the languageTag of the currently used Culture and check there for the xml-File. If there is no such File you can just do it like before.

For this I would replace the lambda in this line with a Method like this:

static string TryGetXmlFileForAssembly(string path)
	{
		string directoryPath = Path.GetDirectoryName(path)!;
		var currentCulture = Thread.CurrentThread.CurrentUICulture; // or Thread.CurrentThread.CurrentCulture?
		string culturePath = Path.Combine(directoryPath, currentCulture.Name, Path.GetFileNameWithoutExtension(path) + ".xml");
		if(File.Exists(culturePath))
		{
			return culturePath;
		}
		culturePath = Path.Combine(directoryPath, currentCulture.TwoLetterISOLanguageName, Path.GetFileNameWithoutExtension(path) + ".xml");
		if (File.Exists(culturePath)){
			return culturePath;
		}
		return Path.ChangeExtension(path, ".xml");
	}

I actually have no idea what the "namespaces.xml"-files from the next line are for so you may have to modify my Suggestion^^ ~~I also wonder if Intellisense does work this way for non CLR-Assemblies so localization would work with Nuget-References as well.~~ I tested it with the Nuget of the CLR-Refs but Intellisense did ignore the localized files I manually added in the nugetcache.

[saucecontrol]

Interesting... Having been spared the horrors of writing culture-aware code for most of my career, I generally tend to ignore those little de folders scattered around, but I can see how some people might care a great deal about them 😉

Now that I look, I can see quite a few of Microsoft's NuGet packages have localized docs in them, so this seems doable.

I'm not sure it would be correct to take on this behavior by default, or at least not based on the build host's CurrentCulture, as I could see issues coming up with CI or other environments being configured with different languages and giving unexpected results. What do you think about a configurable option for default culture/language?

Another scenario I've never considered is using InheritDoc while building packages with multi-language docs. Perhaps if you are processing an XML file that you've placed in a culture/language folder, it should try to auto-resolve matching docs based on that.

[saucecontrol]

BTW, namespaces.xml ships as part of the .NET Framework reference assemblies (both in the targeting packs and the newer NuGet packages), and it just has the documentation for all the namespaces in it. Doesn't seem like they do that any longer for the newer runtimes/standards. I don't know if that file name has special meaning for some tooling or if they just needed a place to stuff the namespace docs since their compilers don't support writing them, but I figured since they're there I may as well use them.

[Herrmel]

Interesting... Having been spared the horrors of writing culture-aware code for most of my career, I generally tend to ignore those little de folders scattered around, but I can see how some people might care a great deal about them 😉

It haunts me everytime 😅

Now that I look, I can see quite a few of Microsoft's NuGet packages have localized docs in them, so this seems doable.

~~Can you show me an example? Just interested in how the nuget is structured/exported since it didnt work for me when I tried to copy cultured xml in the nuget cache.~~ Nevermind, found one^^

I'm not sure it would be correct to take on this behavior by default, or at least not based on the build host's CurrentCulture, as I could see issues coming up with CI or other environments being configured with different languages and giving unexpected results. What do you think about a configurable option for default culture/language?

Yeah I can see that. An Option sounds great.

Another scenario I've never considered is using InheritDoc while building packages with multi-language docs. Perhaps if you are processing an XML file that you've placed in a culture/language folder, it should try to auto-resolve matching docs based on that.

Sounds like a nice feature to have. I could actually see me use it in the future when I may decide to publish my documentation in more than one language.

BTW, namespaces.xml ships as part of the .NET Framework reference assemblies (both in the targeting packs and the newer NuGet packages), and it just has the documentation for all the namespaces in it. Doesn't seem like they do that any longer for the newer runtimes/standards. I don't know if that file name has special meaning for some tooling or if they just needed a place to stuff the namespace docs since their compilers don't support writing them, but I figured since they're there I may as well use them.

Ah ok, thank you for the explanation 😄

[saucecontrol]

@Herrmel I'm planning a new release soon and was giving this and your associated PR another look. While I think this is a good feature idea, it seems Microsoft has abandoned the idea of localized XML docs, and few third parties have ever supplied them. Here's my current understanding of the situation:

• Microsoft is no longer shipping localized XML docs for the .NET SDK

  Note Localized IntelliSense files are no longer available. The latest version they're available for is .NET 5. We recommend using the English IntelliSense files.

• The few Microsoft NuGet packages that shipped with satellite packages aren't getting updates. Ex: EF6 current version is 6.4.4 (published in 2020) and supports .NET Standard 2.1, but its de satellite package stopped updates at 6.2.0 (published in 2017) and only has .NET Framework targets.

• The localized docs that were provided were mostly machine translations and, according to my European colleagues, were not very good. Many of those colleagues use browser scripts to avoid landing on the localized versions of learn.microsoft.com because they find the English version easier to understand.

All of that in mind, I think auto-discovery of localized docs probably wouldn't be a great value add. If we were to support localized overrides, I think it would have to be a more explicit config -- i.e. you'd have to force feed the .NET 5.0 localized docs into a .NET 6.0 build anyway, and with that you could add your own overrides. And if you're doing that, you could supply the language as item metadata instead of having the task guess from folder structure.

So, a couple of questions for you:

1. Is my understanding accurate, or have I missed something?
2. Would a strictly explicit setup still be worth using to you?

[Herrmel]

1. I think your takes are completly accurate as far as I can see. Especially the part with the bad auto translated Docs by microsoft most developer have to avoid.
2. I dont think we have much use from an option since microsoft abandoned their previous language translations. We kinda solved it by using something like the following instead of inheritdoc for external sources to avoid multilanguage mixup in our documentation:

/// <summary>
/// See <see cref="baseclass.Member"/>
/// </summary>

It's defnietly not pretty but somewhat solves the problem.

Thanks for your engagement.