LocaleNames 49.0.0

LocaleNames

Names of languages, countries and currencies in almost any language, for .NET. Look a name up by its code, or a code by its name.

The data comes from Unicode CLDR, is embedded in the package, and needs no network access or OS culture data. Targets netstandard2.0 and net10.0.

Install

dotnet add package LocaleNames

LocaleNames is a meta package that references two others, which you can use on their own:

Take LocaleNames to get everything. The data lives in one shared assembly, LocaleNames.Data.

Selecting locales

To ship only some locales, reference LocaleNames.Data (it brings LocaleNames.Core with it) and list the locales you need. Their data is then embedded into your own assembly during the build, and the LocaleNames.Data assembly is left out of your output:

<PropertyGroup>
  
  <LocaleNamesLocales>cs;en;en_GB</LocaleNamesLocales>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="LocaleNames.Data" Version="..." />
</ItemGroup>

Set it in the project that is deployed (the application). The list works the same when you reference LocaleNames, but then there is no need for it.

• Every locale has its own complete data, en_GB does not depend on en.
• A locale that is not listed has no translations: its lookups return nothing. If the requested culture has no data of its own, the lookup falls back to its parent culture, so list that one too. For example en-US has no data of its own and uses en, so a user with the en-US culture gets translations only when en is listed.
• When no locale data can be found at all (not for a single locale, but nowhere), the first lookup throws InvalidOperationException. Its message names what was searched and how to fix it. This is a setup problem, such as a trimmed LocaleNames.Data assembly or a missing assembly attribute, and it is deliberately not reported as empty translations.

LocaleNames.Core finds the resources in loaded assemblies marked by the package. The mark is an assembly attribute generated by the SDK, so it is missing when GenerateAssemblyInfo is false. In that case, register your assembly yourself, once at startup, before the first lookup:

LocaleResourceProvider.Register(typeof(SomeTypeInYourAssembly).Assembly);

Without a selection no registration is needed, LocaleNames.Data is found on its own. A registered assembly is searched before it, so registering one deliberately overrides the data in LocaleNames.Data.

Trimming and native AOT

The library uses no reflection or runtime code generation, so it is trimming and native AOT compatible. The data is stored in a compact binary format, read by hand rather than deserialized from JSON, see the data format.

LocaleNames.Data is found by its name and nothing references it from code, so the package roots the assembly (TrimmerRootAssembly) to keep it from being trimmed. This is done by the package automatically. If the data is missing in a published AOT app anyway, check that build/LocaleNames.Data.targets of the package is imported. With a selection there is nothing to keep, the data is part of your assembly.

Usage

Get a translations object for the language you want the names in, then query it.

var cs = LocaleTranslationsFactory.ForLanguageCode("cs-CZ");
var en = LocaleTranslationsFactory.ForCultureInfo(new CultureInfo("en-US"));

Languages

en.FindLanguageName("cs-CZ");   // Czech
en.FindLanguageCode("Czech");   // cs
en.GetAllLanguageCodes();

Countries

en.FindCountryName("DE");       // Germany
en.FindCountryCode("Germany");  // DE
en.GetAllCountryCodes();

Currencies

cs.FindCurrencyName("CZK");                      // česká koruna
cs.FindCurrencyName("CZK", PluralCategory.Few);  // české koruny
cs.FindCurrencyPluralNames("CZK");               // all plural forms
cs.FindCurrencyCode("česká koruna");             // CZK

en.FindCurrencySymbol("CZK");                       // CZK
en.FindCurrencySymbol("CZK", AltVariant.Narrow);    // Kč
en.GetAllCurrencyCodes();

License

The code is licensed under the MIT License.

The locale data comes from Unicode CLDR and is licensed under the Unicode License v3 (Unicode-3.0). Copyright © 2015-2024 Unicode, Inc. The LocaleNames.Data package and assemblies that embed selected locales (LocaleNamesLocales) contain this data.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

Activity