Localization: document NeutralLanguage requirement and runtime culture switching pattern
- Dominant language
- No language data
- Stars
- 282
- Forks
- 265
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 19
Description
## Summary
The localization documentation is missing two pieces of guidance:
1. **`NeutralLanguage` must be set** in the `.csproj` — without it, `ResourceManager` may return `null` for default-culture lookups at runtime, causing silent fallback failures instead of a clear error.
2. **Runtime culture switching** — the docs show how to set up localized resources, but do not document the `LocalizationResourceManager` pattern that allows users to switch language at runtime without restarting the app.
## Why it matters
### Missing NeutralLanguage
If `` is not set in the `.csproj`, resource lookups for the default language may silently return `null` instead of the expected string. The app shows blank labels with no error — extremely hard to diagnose because it only happens for the default culture (other cultures work fine via satellite assemblies).
### No runtime switching pattern
Many apps need a "change language" settings page. The official docs show resource file setup and XAML `x:Static` bindings, but these bindings do not update when the culture changes at runtime. Developers need a `LocalizationResourceManager` pattern that raises `PropertyChanged` to trigger XAML rebinding.
## What should be documented
### NeutralLanguage requirement
Add to the setup section:
```xml
en-US
```
> **Warning:** Without `NeutralLanguage` set, `ResourceManager` may return `null` for default-culture string lookups at runtime. Always set this property to match your default `.resx` file's culture.
### Runtime culture switching
Document the `LocalizationResourceManager` pattern:
```csharp
public class LocalizationResourceManager : INotifyPropertyChanged
{
public static LocalizationResourceManager Instance { get; } = new();
public string this[string key] => AppResources.ResourceManager.GetString(key, CultureInfo.CurrentUICulture) ?? key;
public event PropertyChangedEventHandler? PropertyChanged;
public void SetCulture(CultureInfo culture)
{
CultureInfo.CurrentUICulture = culture;
CultureInfo.CurrentCulture = culture;
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(null));
}
}
```
```xml
```
## Suggested location
`docs/fundamentals/localization.md` — add `NeutralLanguage` to the setup section; add a new "Switch language at runtime" section
Contributor guide
Assessment
This issue has not been assessed yet.