EarthCountriesInfo 10.2.0

EarthCountriesInfo

EarthCountriesInfo is an open-source C# class library that provides comprehensive information about countries on planet Earth. Whether you're building educational tools, geographic applications, or simply curious about global diversity, EarthCountriesInfo has you covered!

Features

• Country Names: Retrieve country names in multiple languages.
• Country Phone Codes: Access phone codes for each country.
• Valid Lengths and Formats: Obtain valid phone number lengths and formats (if available).

Where the data comes from

Country names are derived from the Unicode CLDR (version 48.2.1), the same locale data that underpins ICU and the .NET globalization stack. They are regenerated by tools/GenerateCountryData, which pins the CLDR version in a single constant.

Two caveats worth knowing before you depend on a given value:

• CLDR does not cover every language this library exposes. 23 of the 240 LanguageId values have no CLDR locale at all, and 28 more cover only a handful of territories. For those, the previously curated name is kept rather than blanked, so roughly 2,600 names are not CLDR-derived.
• Names are populated for about 84% of country/language pairs. The rest are the empty string, which means "no translation available" — fall back to another language such as LanguageId.en.

Phone codes and number formats are not CLDR data; they are maintained in this repository.

CLDR is licensed under Unicode-3.0 — see THIRD-PARTY-NOTICES.md.

Installation

To include EarthCountriesInfo in your project, install the NuGet package:

dotnet add package EarthCountriesInfo

Usage

Country Properties

The CountryProperties class provides essential information for each country:

public sealed record CountryProperties(
    IReadOnlyDictionary<LanguageId, string> CountryNames,
    string CountryPhoneCode,
    IReadOnlyDictionary<int, string>? ValidLengthsAndFormat
);

• CountryNames: A dictionary containing country names in various languages. Every supported language is present as a key; where no translation is available the value is an empty string, so treat empty as "unknown" and fall back to another language such as LanguageId.en.
• CountryPhoneCode: The international phone code for the country, digits only, without a leading +.
• ValidLengthsAndFormat (optional): Valid phone number lengths mapped to a display format, where each # is one digit. null when unknown.

Example Usage

using EarthCountriesInfo;
using HumanLanguages;

// Get information for a specific country (e.g., INDIA)
if (Countries.CountryPropertiesDictionary.TryGetValue(CountryIsoCode.IN, out CountryProperties? infoAboutIndia))
{
	Console.WriteLine($"Country Name (English): {infoAboutIndia.CountryNames[LanguageId.en]}");
	Console.WriteLine($"Country Phone Code: +{infoAboutIndia.CountryPhoneCode}");

	if (infoAboutIndia.ValidLengthsAndFormat != null)
	{
		foreach (var (length, format) in infoAboutIndia.ValidLengthsAndFormat)
		{
			Console.WriteLine($"Valid Length: {length}, Format: {format}");
		}
	}

}

Contributing

We welcome contributions! If you find a bug, have an idea for improvement, or want to add support for additional countries, please submit an issue or a pull request on GitHub.

Before editing a country name by hand: the names in EarthCountriesInfo/CountryInformation/*.cs are generated, and a re-run of tools/GenerateCountryData will overwrite anything you change there.

• A name that is wrong in CLDR should be fixed upstream in CLDR; it then arrives here on the next version bump.
• A name for a language CLDR does not cover can be edited in place — the generator keeps existing values when CLDR has nothing.
• A name that should deliberately differ from CLDR belongs in the EditorialOverrides table in tools/GenerateCountryData/Program.cs, with a comment explaining why.

Phone codes and ValidLengthsAndFormat are not generated and can be edited directly.

GitHub Repository

Visit our GitHub repository for the latest updates, documentation, and community contributions: EarthCountriesInfo GitHub Repository

License

This project is licensed under the GNU GENERAL PUBLIC LICENSE.

Happy coding! 🌎🚀📚