Improve and update Localization docs and samples

[Ponant]

I may suggest to drastically improve the localization docs.
I am happy to help, but I would like not to go through all versions of .Net Core, and rather focus on .Net 6.
I could do a video on youtube or wherever if that is acceptable on the site.
The strategy would be to first do the video and if you like it we transform it to text.
You can check out my tuto skills here https://www.youtube.com/watch?v=n5DI3VDtvAQ , and feel free to complain :)!
I have a better microphone.

Background: I worked on Localization in the past, so I knew it, but after 2-3 years I came back to Localization for a new project and somewhat needed a refresher. So I went back to the docs and found them somewhat dismanteled and not so in line with typical docs on asp.net core. It is a very confusing experience, going back and forth through the main page. I am sorry for this negative feedback.

Here is some feedback:
Sample
-The startup does not need to register RequestLocalizationOptions twice, once in services and once in app builder, see here https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/localization/sample/3.x/Localization/Startup.cs
-Update to Razor Pages or put in some sentence in the docs. For example I figured out on my own that I could do it, for example by using IndexModel as a type for IStringLocalizer. It was not difficult to guess but I believe if it was there in the docs, it would have been better

Main docs
In typical docs in this repo, the usage is to go straight with a basic configuration, i.e. AddLocalization, Configure RequestLocalizationOptions, UseRequestLocalization.

1. Then run and observe via the query string how a date is displayed in a different culture (no need for resx files at this stage).
2. Experience with fallbacks through the providers (Query, cookie and accept header)
3. Then move on to add resx files, by highlighting IStringLocalizer, IHtmlLocalizer, IViewLocalizer, data annotations
4. In that respect I find it important to mention that you can use IStringLocalizer in views and stick with that only. The other two are for html based strings
5. Then cookie
6. Then of course go to higher levels by tweaking the providers and mentionning the factory
7. etc

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: d1833676-ff1b-c587-cc9c-81afffa8ef68
• Version Independent ID: ad989395-3f49-4d55-521e-cf6fe56281ee
• Content: Globalization and localization in ASP.NET Core
• Content Source: aspnetcore/fundamentals/localization.md
• Product: aspnet-core
• Technology: aspnetcore-fundamentals
• GitHub Login: @Rick-Anderson
• Microsoft Alias: riande

[Rick-Anderson]

@Ponant and update for .NET 6 would be great. You could do a video, but we're found non-English speakers don't like video's in English, they like documentation. The updates need to be in this doc.

[Ponant]

@Rick-Anderson , for .Net 6, do I need to use the same document structure? Because personally, I would re-order sections.

[Rick-Anderson]

I think your suggestion works better. Please provide a more complete outline.
Before you start, I need to prepare a 6.0 moniker section for you.

[Rick-Anderson]

@Ponant I prepared the MD file for V6. See https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/localization.md and the raw version.

[Ponant]

OK @Rick-Anderson , so I guess I first submit in this issue a more precise template, namely sections and what they will do and in which order they appear. And once you give a green light I modify the md file and put a sample in a 6.x folder. Correct?

[Rick-Anderson]

OK @Rick-Anderson , so I guess I first submit in this issue a more precise template, namely sections and what they will do and in which order they appear. And once you give a green light I modify the md file and put a sample in a 6.x folder. Correct?

That's correct. Thanks for the help.

[Ponant]

Hi @Rick-Anderson ,
Here is what I could come with without going into code and full explanations. I believe you should be able to grasp the structure and intent.

Currently, the Overview contains almost all, which is too much in my view. Also, it seems a few stuff could go to extensibility. Also there are small details, such as the use of an async on a sync return method (the custom provider) and "Notes" which could be better placed.

Ideally, I would recommend to split the Overview to form a document tree, with sections, subsections and subsubsection, and a left panel, but I am also ok with one big page.

Below, when I mention "title is optional" it means that the content flows with the preceding section, without breaking the lecture with another title. This is easier for the user to learn from top to bottom, see below. It also removes the need to introduce sub-sub-sections. But not having sub-sub-sections makes it difficult for a returning user. For example, if the user wants to see what is the value of the query string, he could jump directly to the sub-sub-section where that is discussed.

One thing to fix (among others) is what to do with "Core", since .Net 6 is not named Core anymore.

---

Globalization and localization terms (section)

Mostly kept as is and merged with current intro (some shortening will occur). CultureInfo is mentioned here, which is needed for what follows.

ASP.NET Core's non-localized behavior (section)

Understanding how to localize an ASP.NET Core application starts with understanding the CurrentCulture and CurrentUICulture, dates and formats.

• Start with a new .Net 6 project
• Briefly recall the CultureInfo object, and to access the CultureInfo object in all views, add a @using System.Globalization in _ViewImports.cshtml
• Display CurrentCulture and CurrentUICulture, dates and a 6-digit currency number in the index.cshtml View
• Discuss results, namely why the CultureInfo returns en-GB (because I am running windows 10 in en-GB display language and format). The user will be instructed to take notice of which locale appears for him/her. Change the regional format to French and observe how culture is changed, dates and numbers are changed, but not the UI culture. Pictures shown throughout. To change the latter, the user will have to change the display language of the OS, logout and login anew on Windows 10.
• The paragraph ends by stating that we set back the regional format in the OS as it was, i.e. en-GB in our case

ASP.NET Core's localized behavior (section)

Briefly explain that a full localization is done in two main steps, each of which addresses different parts of the API. Step 1 is the use of the AddRequestLocalization and Step 2 is AddLocalization with the localizers and their resx’s. Addressing in this way is important to see the separation of concerns, and to see how far one can get without resx’s

Part I: Configure and control the Cultures and UICultures to be used (subsection)

• To control the culture and ui-culture to be displayed in the browser, we start by injecting the AddRequestLocalization (not AddLocalization) service as well as the request localization middleware
• We chose on purpose to set as cultures and uicultures fr-FR and it-IT in the service, not en or en-* such that there is a distinction with respect to the default culture info gotten from the first section.
• We recommend the user to follow a similar approach for learning/testing, i.e. if he/she has an Italian OS, then he/she would set the cultures to fr-fr and en-us, for example. This also assumes that the browser is not configured for fr-FR and it-IT.

The Query String Request Culture Provider (subsubsection, title is optional)

• Once we run, the user will see en-GB, because we did not set a default culture. Here we play with the query string to display in French and Italian. We also display all languages registered
• Make the remark that, in general, it is important to be specific with which culture we are dealing. For example, prefer fr-FR or fr-CA (for canada) rather than the generic fr. The latter indeed will lead, for instance to numbers without currency when using ToString(“c”), as done in code, because fr is a parent culture of many French cultures. However, putting in fr is also a good idea for a fallback. So we show that by doing so, someone querying fr-ca will fall back to fr, so that he can read dates and numbers, but not the currency
• Modify the code to set as default language de-DE, and run again. Now the displayed information is in German by default, and no more en-GB. This is good because we gain control.
• Mention now that the query string provider is the first in the list of RequestCultureProviders, how can we get that via the Features in the HttpContext, and we display the list in the index page, which introduces the cookie and request header providers
• We mention how to customize the query string provider, by e.g. changing the query strings culture and uiculture to lang and uilang, so that https://localhost:5001/?lang=fr-fr returns something
• We next remove the querystring provider from the list to see that the query string method is not working.

The Accept Language Header Request Culture Provider (subsubsection, title is optional)

We set the browser to accept a new language, es-ES, in addition to en-GB, and we add es-ES in the service. Again, the user will be recommended to use a language he knows he does not have on his machine. Now we see that, when run, the language displayed is es-ES and not the default de-DE (or en-GB if no default was set). This is the role of the header request provider, it found es-ES so skips the default. We remove this provider, arguing that in common usage one should avoid relying on this provider, so that we are left with the cookie provider, and back to the default, German.

The Cookie Request Culture Provider (subsubsection, title is optional)

• Here we set the cookie request provider. For this we clear all providers, set a new Cookie request provider, and set the cookie name to .Contoso.Culture
• We make use of the MakeCookie method in a new language page, which displays the cultures and which is accessible from a partial view. This part actually makes use of all what has been discussed before. For example the used culture is displayed as a nav-link by using the http features.

Part II: Localize the content (subsection)

• This part will take large parts of what is already in the docs, but adapted to Razor Pages because we started with that. MVC will be mentioned when need be. It will have subsections (guessable from the bullet points below)
• We now make use of AddLocalization with a MyResources folder and explain that this extension will inject IStringLocalizer and the accompanying factory as well as the resource manager
• We introduce the SharedResources with notes on the breaking change from MSBuild since 3.0
• We show how far we can go without AddViewLocalization and AddDataAnnotationLocalization, and then show these
• The section on resource files could be simplified
• We mention the conventions for naming the resx’s
• We check culture fallback, as we did already from fr-CA to fr

---

Custom provider section and Model binding route data and query strings go to Extensibility (left panel)

[Rick-Anderson]

@Ponant fantastic outline. A few comments:

On sub-sub sections. I think titles are best, you ## section title ### sub-section section title #### sub-sub-section section title You can go with `###### if needed, but that shouldn't be necessary. Having titles gives you in page links which are useful.

Only H2's ( ## section title ) show up in the right side table. See https://github.com/dotnet/AspNetCore.Docs/pull/23068/files where I added an H3 today. Data Protection and app isolation is the link, but it doesn't show up on the right side.

with "Core", since .Net 6 is not named Core anymore.

Where .NET 6 is the correct framework, use .NET 6 and remove Core. Where it's ASP.NET Core specific, obviously keep Core.

@hishamco for review

[Ponant]

Should I draft the md?

[Ponant]

BTW, how do you preview the md file, with the code, pictures and Notes? The Preview button does not show a "live" version.