dotnet / dotnet/docs-maui

Localization: document NeutralLanguage requirement and runtime culture switching pattern

Open
#3,255 0 comments 0 reactions 0 assignees View on GitHub
:watch: Not Triaged Pri3
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.