Skip to content

feat: deprecate GetAbbreviationsForTimeZone #133

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattjohnsonpint merged 1 commit into from
Oct 31, 2025
Merged

feat: deprecate GetAbbreviationsForTimeZone #133

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 4 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ Read [this blog post](https://codeofmatt.com/localized-time-zone-names-in-net/)
Note that if you are running .NET 6+ on Linux or macOS, the built-in names now stem from ICU and thus this library is no longer needed.
See [the .NET blog post](https://devblogs.microsoft.com/dotnet/date-time-and-time-zone-enhancements-in-net-6/#time-zone-display-names-on-linux-and-macos) for more details.

**NOTE**:
Methods for retrieving localized time zone abbreviations have been deprecated, as the source data for abbreviations is generally unreliable.

Nuget Installation
=============================================================================
```powershell
Expand Down Expand Up @@ -62,29 +65,6 @@ names.Standard == "Central European Standard Time"
names.Daylight == "Central European Summer Time"
```

### GetAbbreviationsForTimeZone
Look up the localized abbreviations for a specific time zone:
```csharp
var abbreviations = TZNames.GetAbbreviationsForTimeZone("America/Los_Angeles", "en-US");

abbreviations.Generic == "PT"
abbreviations.Standard == "PST"
abbreviations.Daylight == "PDT"
```

You can pass a Windows time zone id instead, if you like:
```csharp
var abbreviations = TZNames.GetAbbreviationsForTimeZone("Romance Standard Time", "en-GB");

names.Generic == "CET"
abbreviations.Standard == "CET"
abbreviations.Daylight == "CEST"
```

**Note:** Time zone abbreviations are sometimes inconsistent, and are not necessarily
localized correctly for every time zone. In most cases, you should use abbreviations
for end-user display output only. Do not attempt to use abbreviations when parsing input.

## Methods for listing time zones

### GetDisplayNames
Expand Down Expand Up @@ -246,7 +226,7 @@ TODO: Add examples for this method.

### GetFixedTimeZoneAbbreviations

Gets the same list of zones as `GetFixedTimeZoneIds`, but includes localized abbreviations.
Gets the same list of zones as `GetFixedTimeZoneIds`, but includes abbreviations.

TODO: Add examples for this method.

Expand Down
16 changes: 9 additions & 7 deletions src/TimeZoneNames/TZNames.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,14 +210,15 @@ public static TimeZoneValues GetNamesForTimeZone(string timeZoneId, string langu
/// <param name="timeZoneId">An IANA or Windows time zone identifier.</param>
/// <param name="languageCode">The IETF language tag (culture code) to use when localizing the abbreviations.</param>
/// <returns>A <see cref="TimeZoneValues"/> object containing the localized generic, standard, and daylight abbreviations.</returns>
[Obsolete("WARNING! Time zone abbreviations are inconsistent and not well-defined in the source data. This method will be removed in a future release.")]
public static TimeZoneValues GetAbbreviationsForTimeZone(string timeZoneId, string languageCode)
{
var langKey = GetLanguageKey(languageCode);
if (langKey == null)
{
throw new ArgumentException("Invalid Language Code", nameof(languageCode));
}

if (TZConvert.TryWindowsToIana(timeZoneId, out var ianaId))
{
timeZoneId = ianaId;
Expand Down Expand Up @@ -298,7 +299,7 @@ public static IDictionary<string, string> GetDisplayNames(string languageCode, b
{
throw new ArgumentException("Invalid Language Code", nameof(languageCode));
}

var displayNames = Data.DisplayNames[langKey]
.Where(x => !TimeZoneData.ObsoleteWindowsZones.Contains(x.Key))
.ToList();
Expand All @@ -307,7 +308,7 @@ public static IDictionary<string, string> GetDisplayNames(string languageCode, b
{
return displayNames.ToOrderedDictionary(StringComparer.OrdinalIgnoreCase);
}

var languageCodeParts = languageCode.Split('_', '-');
var territoryCode = languageCodeParts.Length < 2 ? "001" : languageCodeParts[1];
return displayNames.ToOrderedDictionary(
Expand All @@ -334,7 +335,7 @@ public static ICollection<string> GetLanguageCodes()
public static ICollection<string> GetLanguageCodes(bool forDisplayNames)
{
var keys = forDisplayNames
? (IEnumerable<string>) Data.DisplayNames.Keys
? (IEnumerable<string>)Data.DisplayNames.Keys
: Data.CldrLanguageData.Keys;

return keys.OrderBy(x => x).ToList();
Expand Down Expand Up @@ -373,7 +374,7 @@ private static string GetLanguageKey(string languageCode, bool forDisplayNames =

if (key == null)
{
var keys = forDisplayNames ? (IEnumerable<string>) Data.DisplayNames.Keys : Data.CldrLanguageData.Keys;
var keys = forDisplayNames ? (IEnumerable<string>)Data.DisplayNames.Keys : Data.CldrLanguageData.Keys;
key = keys.FirstOrDefault(x =>
x.Split('_')[0].Equals(languageCode.Split('-', '_')[0], StringComparison.OrdinalIgnoreCase));

Expand Down Expand Up @@ -438,7 +439,7 @@ private static TimeZoneValues GetNames(string timeZoneId, string languageKey, bo

if (abbreviations && (timeZoneId == "Etc/GMT" || timeZoneId == "Etc/UTC"))
{
return new TimeZoneValues {Generic = "UTC", Standard = "UTC", Daylight = "UTC"};
return new TimeZoneValues { Generic = "UTC", Standard = "UTC", Daylight = "UTC" };
}

var metaZone = GetMetazone(timeZoneId);
Expand Down Expand Up @@ -626,7 +627,8 @@ private static TimeZoneValues GetNames(string timeZoneId, string languageKey, bo
}

// last chance to make a generic name if it's missing
if (values.Generic == null) {
if (values.Generic == null)
{
values.Generic = values.Standard;
}

Expand Down
90 changes: 0 additions & 90 deletions test/TimeZoneNames.Tests/TimeZoneNamesTest.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,6 @@ public void Can_Get_Names_For_US_Pacific()
Assert.Equal("Pacific Daylight Time", names.Daylight);
}

[Fact]
public void Can_Get_Abbreviations_For_US_Pacific()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("America/Los_Angeles", "en-US");

Assert.Equal("PT", abbreviations.Generic);
Assert.Equal("PST", abbreviations.Standard);
Assert.Equal("PDT", abbreviations.Daylight);
}

[Fact]
public void Can_Get_French_Names_For_US_Pacific()
{
Expand All @@ -42,16 +32,6 @@ public void Can_Get_French_Names_For_US_Pacific()
Assert.Equal("heure avancée du Pacifique", names.Daylight);
}

[Fact]
public void Can_Get_French_Abbreviations_For_US_Pacific()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("America/Los_Angeles", "fr-CA");

Assert.Equal("HP", abbreviations.Generic);
Assert.Equal("HNP", abbreviations.Standard);
Assert.Equal("HAP", abbreviations.Daylight);
}

[Fact]
public void Can_Get_Names_For_US_Arizona()
{
Expand All @@ -73,26 +53,6 @@ public void Can_Get_Names_For_UK()
Assert.Equal("British Summer Time", names.Daylight);
}

[Fact]
public void Can_Get_Abbreviations_For_UK()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("Europe/London", "en-US");

Assert.Null(abbreviations.Generic);
Assert.Equal("GMT", abbreviations.Standard);
Assert.Equal("BST", abbreviations.Daylight);
}

[Fact]
public void Can_Get_Abbreviations_For_Central_Europe()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("Central European Standard Time", "en-US");

Assert.Equal("CET", abbreviations.Generic);
Assert.Equal("CET", abbreviations.Standard);
Assert.Equal("CEST", abbreviations.Daylight);
}

[Fact]
public void Can_Get_Names_For_IE()
{
Expand All @@ -103,16 +63,6 @@ public void Can_Get_Names_For_IE()
Assert.Equal("Irish Standard Time", names.Daylight);
}

[Fact]
public void Can_Get_Abbreviations_For_IE()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("Europe/Dublin", "en-US");

Assert.Null(abbreviations.Generic);
Assert.Equal("GMT", abbreviations.Standard);
Assert.Equal("IST", abbreviations.Daylight);
}

[Fact]
public void Can_Get_Names_For_IN1()
{
Expand All @@ -123,16 +73,6 @@ public void Can_Get_Names_For_IN1()
Assert.Equal("India Standard Time", names.Daylight);
}

[Fact]
public void Can_Get_Abbreviations_For_IN1()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("Asia/Calcutta", "en-US");

Assert.Equal("IST", abbreviations.Generic);
Assert.Equal("IST", abbreviations.Standard);
Assert.Equal("IST", abbreviations.Daylight);
}

[Fact]
public void Can_Get_Names_For_IN2()
{
Expand All @@ -143,16 +83,6 @@ public void Can_Get_Names_For_IN2()
Assert.Equal("India Standard Time", names.Daylight);
}

[Fact]
public void Can_Get_Abbreviations_For_IN2()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("Asia/Kolkata", "en-US");

Assert.Equal("IST", abbreviations.Generic);
Assert.Equal("IST", abbreviations.Standard);
Assert.Equal("IST", abbreviations.Daylight);
}

[Fact]
public void Can_Get_Names_For_CN()
{
Expand All @@ -173,16 +103,6 @@ public void Can_Get_Names_For_CN()
// Assert.Equal("Urumqi Daylight Time", names.Daylight);
//}

[Fact]
public void Can_Get_Abbreviations_For_Sao_Tome()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("Sao Tome Standard Time", "en-GB");

Assert.Equal("GMT", abbreviations.Generic);
Assert.Equal("GMT", abbreviations.Standard);
Assert.Equal("GMT", abbreviations.Daylight);
}

[Fact]
public void Can_Get_Names_For_UTC()
{
Expand Down Expand Up @@ -225,16 +145,6 @@ public void Can_Get_Names_For_Windows_Timezone()
Assert.Equal("Eastern Daylight Time", names.Daylight);
}

[Fact]
public void Can_Get_Abbreviations_For_Windows_Timezone()
{
var abbreviations = TZNames.GetAbbreviationsForTimeZone("AUS Eastern Standard Time", "en-US");

Assert.Equal("AET", abbreviations.Generic);
Assert.Equal("AEST", abbreviations.Standard);
Assert.Equal("AEDT", abbreviations.Daylight);
}

//[Fact]
//public void Can_Get_Names_For_CA_Pacific_From_MX()
//{
Expand Down