Skip to content

using-cultures.mdx

Latest commit

 

History

History
91 lines (70 loc) · 3.59 KB

using-cultures.mdx

File metadata and controls

91 lines (70 loc) · 3.59 KB
Raw
id using-cultures
title Choose explicit and ambient cultures
sidebar_position 2
diataxis how-to
persona application developer
example illustrative

Choose explicit and ambient cultures

Orientation

Pass a CultureInfo directly when an overload accepts one. It makes the language choice visible, keeps concurrent requests isolated, and is easy to test. Set CurrentCulture and CurrentUICulture together at a request, message, or job boundary for APIs that use ambient culture.

Culture names are .NET culture identifiers. A specific culture such as fr-FR can fall back through its .NET parent chain to neutral fr locale data. Humanizer then uses the registry default only if no registered parent matches.

Example

using System.Globalization;
using Humanizer;

var french = CultureInfo.GetCultureInfo("fr-FR");

Console.WriteLine(42.ToWords(french));
Console.WriteLine(DateTime.UtcNow.AddDays(-1).Humanize(culture: french));

CultureInfo.CurrentCulture = french;
CultureInfo.CurrentUICulture = french;
Console.WriteLine(new[] { "un", "deux", "trois" }.Humanize());

The first two calls are explicit. The collection call uses ambient UI culture because collection formatting has no culture parameter.

For application code, establish ambient culture once at the request, message, or background-job boundary. Keep using explicit overloads inside shared services where possible; this prevents one concurrent operation from changing another operation's output.

Pitfall

CurrentCulture and CurrentUICulture serve different .NET concerns. Numeric/date formatting commonly follows CurrentCulture; resource and collection localization can follow CurrentUICulture. Setting only one can produce mixed-language output. Also avoid changing process-wide culture in a shared request path when an explicit overload exists.

Parent fallback is resolution, not parity proof. If fr-CA reaches fr, that only identifies where the data came from. It does not establish that French Canadian wording matches every neutral-French choice.

On Humanizer 4, use Configurator.IsCultureSupported(culture) before choosing an application fallback. It checks generated Humanizer locale data through the named parent chain and does not return true merely because the default English localizers could produce output:

var requested = CultureInfo.GetCultureInfo("fr-FR");
var culture = Configurator.IsCultureSupported(requested)
    ? requested
    : CultureInfo.GetCultureInfo("en");

If inherited or direct output is wrong, follow the language correction guide or open a prefilled locale issue.

Version notes

Explicit and ambient CultureInfo selection applies across the supported documentation corpus. The locale set and package layout are versioned: Humanizer 4 has generated locale data in the consolidated Humanizer package, while published versions through 3.0.10 use the metapackage and locale-package graph documented in their snapshot. Configurator.IsCultureSupported is a Humanizer 4 API.

Related guides and API