Add support for platform specific localized display names for DayOfWeek and Month

core/api/kotlinx-datetime.api

@@ -195,6 +195,8 @@ public final class kotlinx/datetime/DayOfWeek : java/lang/Enum {
 public final class kotlinx/datetime/DayOfWeekKt {
 	public static final synthetic fun DayOfWeek (I)Ljava/time/DayOfWeek;
 	public static final fun DayOfWeek (I)Lkotlinx/datetime/DayOfWeek;
+	public static final fun displayName (Lkotlinx/datetime/DayOfWeek;Lkotlinx/datetime/TextStyle;Lkotlinx/datetime/Locale;)Ljava/lang/String;
+	public static synthetic fun displayName$default (Lkotlinx/datetime/DayOfWeek;Lkotlinx/datetime/TextStyle;Lkotlinx/datetime/Locale;ILjava/lang/Object;)Ljava/lang/String;
 	public static final fun getIsoDayNumber (Ljava/time/DayOfWeek;)I
 	public static final fun getIsoDayNumber (Lkotlinx/datetime/DayOfWeek;)I
 }
@@ -548,6 +550,19 @@ public final class kotlinx/datetime/LocalTimeKt {
 	public static final fun toLocalTime (Ljava/lang/String;)Lkotlinx/datetime/LocalTime;
 }
 
+public final class kotlinx/datetime/Locale {
+	public static final field Companion Lkotlinx/datetime/Locale$Companion;
+}
+
+public final class kotlinx/datetime/Locale$Companion {
+	public final fun getDefault ()Lkotlinx/datetime/Locale;
+}
+
+public final class kotlinx/datetime/LocaleKt {
+	public static final fun toJavaLocale (Lkotlinx/datetime/Locale;)Ljava/util/Locale;
+	public static final fun toKotlinLocale (Ljava/util/Locale;)Lkotlinx/datetime/Locale;
+}
+
 public final class kotlinx/datetime/Month : java/lang/Enum {
 	public static final field APRIL Lkotlinx/datetime/Month;
 	public static final field AUGUST Lkotlinx/datetime/Month;
@@ -569,6 +584,8 @@ public final class kotlinx/datetime/Month : java/lang/Enum {
 public final class kotlinx/datetime/MonthKt {
 	public static final synthetic fun Month (I)Ljava/time/Month;
 	public static final fun Month (I)Lkotlinx/datetime/Month;
+	public static final fun displayName (Lkotlinx/datetime/Month;Lkotlinx/datetime/TextStyle;Lkotlinx/datetime/Locale;)Ljava/lang/String;
+	public static synthetic fun displayName$default (Lkotlinx/datetime/Month;Lkotlinx/datetime/TextStyle;Lkotlinx/datetime/Locale;ILjava/lang/Object;)Ljava/lang/String;
 	public static final fun getNumber (Ljava/time/Month;)I
 	public static final fun getNumber (Lkotlinx/datetime/Month;)I
 }
@@ -592,6 +609,18 @@ public final class kotlinx/datetime/Ser : java/io/Externalizable {
 public final class kotlinx/datetime/Ser$Companion {
 }
 
+public final class kotlinx/datetime/TextStyle : java/lang/Enum {
+	public static final field FULL Lkotlinx/datetime/TextStyle;
+	public static final field FULL_STANDALONE Lkotlinx/datetime/TextStyle;
+	public static final field NARROW Lkotlinx/datetime/TextStyle;
+	public static final field NARROW_STANDALONE Lkotlinx/datetime/TextStyle;
+	public static final field SHORT Lkotlinx/datetime/TextStyle;
+	public static final field SHORT_STANDALONE Lkotlinx/datetime/TextStyle;
+	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public static fun valueOf (Ljava/lang/String;)Lkotlinx/datetime/TextStyle;
+	public static fun values ()[Lkotlinx/datetime/TextStyle;
+}
+
 public class kotlinx/datetime/TimeZone {
 	public static final field Companion Lkotlinx/datetime/TimeZone$Companion;
 	public fun equals (Ljava/lang/Object;)Z
@@ -1003,6 +1032,10 @@ public final class kotlinx/datetime/format/DayOfWeekNames$Companion {
 	public final fun getENGLISH_FULL ()Lkotlinx/datetime/format/DayOfWeekNames;
 }
 
+public final class kotlinx/datetime/format/DayOfWeekNamesExtKt {
+	public static final fun getENGLISH_NARROW (Lkotlinx/datetime/format/DayOfWeekNames$Companion;)Ljava/util/List;
+}
+
 public abstract interface annotation class kotlinx/datetime/format/FormatStringsInDatetimeFormats : java/lang/annotation/Annotation {
 }
 
@@ -1021,6 +1054,10 @@ public final class kotlinx/datetime/format/MonthNames$Companion {
 	public final fun getENGLISH_FULL ()Lkotlinx/datetime/format/MonthNames;
 }
 
+public final class kotlinx/datetime/format/MonthNamesExtKt {
+	public static final fun getENGLISH_NARROW (Lkotlinx/datetime/format/MonthNames$Companion;)Ljava/util/List;
+}
+
 public final class kotlinx/datetime/format/Padding : java/lang/Enum {
 	public static final field NONE Lkotlinx/datetime/format/Padding;
 	public static final field SPACE Lkotlinx/datetime/format/Padding;

core/api/kotlinx-datetime.klib.api

@@ -71,6 +71,21 @@ final enum class kotlinx.datetime/Month : kotlin/Enum<kotlinx.datetime/Month> {
     final fun values(): kotlin/Array<kotlinx.datetime/Month> // kotlinx.datetime/Month.values|values#static(){}[0]
 }
 
+final enum class kotlinx.datetime/TextStyle : kotlin/Enum<kotlinx.datetime/TextStyle> { // kotlinx.datetime/TextStyle|null[0]
+    enum entry FULL // kotlinx.datetime/TextStyle.FULL|null[0]
+    enum entry FULL_STANDALONE // kotlinx.datetime/TextStyle.FULL_STANDALONE|null[0]
+    enum entry NARROW // kotlinx.datetime/TextStyle.NARROW|null[0]
+    enum entry NARROW_STANDALONE // kotlinx.datetime/TextStyle.NARROW_STANDALONE|null[0]
+    enum entry SHORT // kotlinx.datetime/TextStyle.SHORT|null[0]
+    enum entry SHORT_STANDALONE // kotlinx.datetime/TextStyle.SHORT_STANDALONE|null[0]
+
+    final val entries // kotlinx.datetime/TextStyle.entries|#static{}entries[0]
+        final fun <get-entries>(): kotlin.enums/EnumEntries<kotlinx.datetime/TextStyle> // kotlinx.datetime/TextStyle.entries.<get-entries>|<get-entries>#static(){}[0]
+
+    final fun valueOf(kotlin/String): kotlinx.datetime/TextStyle // kotlinx.datetime/TextStyle.valueOf|valueOf#static(kotlin.String){}[0]
+    final fun values(): kotlin/Array<kotlinx.datetime/TextStyle> // kotlinx.datetime/TextStyle.values|values#static(){}[0]
+}
+
 abstract interface kotlinx.datetime/Clock { // kotlinx.datetime/Clock|null[0]
     abstract fun now(): kotlinx.datetime/Instant // kotlinx.datetime/Clock.now|now(){}[0]
 
@@ -552,6 +567,12 @@ final class kotlinx.datetime/LocalTime : kotlin/Comparable<kotlinx.datetime/Loca
     }
 }
 
+final class kotlinx.datetime/Locale { // kotlinx.datetime/Locale|null[0]
+    final object Companion { // kotlinx.datetime/Locale.Companion|null[0]
+        final fun getDefault(): kotlinx.datetime/Locale // kotlinx.datetime/Locale.Companion.getDefault|getDefault(){}[0]
+    }
+}
+
 final class kotlinx.datetime/OverloadMarker // kotlinx.datetime/OverloadMarker|null[0]
 
 final class kotlinx.datetime/UtcOffset { // kotlinx.datetime/UtcOffset|null[0]
@@ -1077,6 +1098,10 @@ final object kotlinx.datetime.serializers/YearMonthSerializer : kotlinx.serializ
     final fun serialize(kotlinx.serialization.encoding/Encoder, kotlinx.datetime/YearMonth) // kotlinx.datetime.serializers/YearMonthSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlinx.datetime.YearMonth){}[0]
 }
 
+final val kotlinx.datetime.format/ENGLISH_NARROW // kotlinx.datetime.format/ENGLISH_NARROW|@kotlinx.datetime.format.DayOfWeekNames.Companion{}ENGLISH_NARROW[0]
+    final fun (kotlinx.datetime.format/DayOfWeekNames.Companion).<get-ENGLISH_NARROW>(): kotlin.collections/List<kotlin/String> // kotlinx.datetime.format/ENGLISH_NARROW.<get-ENGLISH_NARROW>|<get-ENGLISH_NARROW>@kotlinx.datetime.format.DayOfWeekNames.Companion(){}[0]
+final val kotlinx.datetime.format/ENGLISH_NARROW // kotlinx.datetime.format/ENGLISH_NARROW|@kotlinx.datetime.format.MonthNames.Companion{}ENGLISH_NARROW[0]
+    final fun (kotlinx.datetime.format/MonthNames.Companion).<get-ENGLISH_NARROW>(): kotlin.collections/List<kotlin/String> // kotlinx.datetime.format/ENGLISH_NARROW.<get-ENGLISH_NARROW>|<get-ENGLISH_NARROW>@kotlinx.datetime.format.MonthNames.Companion(){}[0]
 final val kotlinx.datetime/isDistantFuture // kotlinx.datetime/isDistantFuture|@kotlinx.datetime.Instant{}isDistantFuture[0]
     final fun (kotlinx.datetime/Instant).<get-isDistantFuture>(): kotlin/Boolean // kotlinx.datetime/isDistantFuture.<get-isDistantFuture>|<get-isDistantFuture>@kotlinx.datetime.Instant(){}[0]
 final val kotlinx.datetime/isDistantPast // kotlinx.datetime/isDistantPast|@kotlinx.datetime.Instant{}isDistantPast[0]
@@ -1139,6 +1164,7 @@ final fun (kotlinx.datetime/Clock).kotlinx.datetime/todayAt(kotlinx.datetime/Tim
 final fun (kotlinx.datetime/Clock).kotlinx.datetime/todayIn(kotlinx.datetime/TimeZone): kotlinx.datetime/LocalDate // kotlinx.datetime/todayIn|todayIn@kotlinx.datetime.Clock(kotlinx.datetime.TimeZone){}[0]
 final fun (kotlinx.datetime/DatePeriod).kotlinx.datetime/plus(kotlinx.datetime/DatePeriod): kotlinx.datetime/DatePeriod // kotlinx.datetime/plus|plus@kotlinx.datetime.DatePeriod(kotlinx.datetime.DatePeriod){}[0]
 final fun (kotlinx.datetime/DateTimePeriod).kotlinx.datetime/plus(kotlinx.datetime/DateTimePeriod): kotlinx.datetime/DateTimePeriod // kotlinx.datetime/plus|plus@kotlinx.datetime.DateTimePeriod(kotlinx.datetime.DateTimePeriod){}[0]
+final fun (kotlinx.datetime/DayOfWeek).kotlinx.datetime/displayName(kotlinx.datetime/TextStyle = ..., kotlinx.datetime/Locale = ...): kotlin/String // kotlinx.datetime/displayName|displayName@kotlinx.datetime.DayOfWeek(kotlinx.datetime.TextStyle;kotlinx.datetime.Locale){}[0]
 final fun (kotlinx.datetime/Instant).kotlinx.datetime/daysUntil(kotlinx.datetime/Instant, kotlinx.datetime/TimeZone): kotlin/Int // kotlinx.datetime/daysUntil|daysUntil@kotlinx.datetime.Instant(kotlinx.datetime.Instant;kotlinx.datetime.TimeZone){}[0]
 final fun (kotlinx.datetime/Instant).kotlinx.datetime/format(kotlinx.datetime.format/DateTimeFormat<kotlinx.datetime.format/DateTimeComponents>, kotlinx.datetime/UtcOffset = ...): kotlin/String // kotlinx.datetime/format|format@kotlinx.datetime.Instant(kotlinx.datetime.format.DateTimeFormat<kotlinx.datetime.format.DateTimeComponents>;kotlinx.datetime.UtcOffset){}[0]
 final fun (kotlinx.datetime/Instant).kotlinx.datetime/minus(kotlin/Int, kotlinx.datetime/DateTimeUnit, kotlinx.datetime/TimeZone): kotlinx.datetime/Instant // kotlinx.datetime/minus|minus@kotlinx.datetime.Instant(kotlin.Int;kotlinx.datetime.DateTimeUnit;kotlinx.datetime.TimeZone){}[0]
@@ -1207,6 +1233,7 @@ final fun (kotlinx.datetime/LocalTime).kotlinx.datetime/atDate(kotlin/Int, kotli
 final fun (kotlinx.datetime/LocalTime).kotlinx.datetime/atDate(kotlin/Int, kotlinx.datetime/Month, kotlin/Int, kotlin/Unit = ...): kotlinx.datetime/LocalDateTime // kotlinx.datetime/atDate|atDate@kotlinx.datetime.LocalTime(kotlin.Int;kotlinx.datetime.Month;kotlin.Int;kotlin.Unit){}[0]
 final fun (kotlinx.datetime/LocalTime).kotlinx.datetime/atDate(kotlinx.datetime/LocalDate): kotlinx.datetime/LocalDateTime // kotlinx.datetime/atDate|atDate@kotlinx.datetime.LocalTime(kotlinx.datetime.LocalDate){}[0]
 final fun (kotlinx.datetime/LocalTime).kotlinx.datetime/format(kotlinx.datetime.format/DateTimeFormat<kotlinx.datetime/LocalTime>): kotlin/String // kotlinx.datetime/format|format@kotlinx.datetime.LocalTime(kotlinx.datetime.format.DateTimeFormat<kotlinx.datetime.LocalTime>){}[0]
+final fun (kotlinx.datetime/Month).kotlinx.datetime/displayName(kotlinx.datetime/TextStyle = ..., kotlinx.datetime/Locale = ...): kotlin/String // kotlinx.datetime/displayName|displayName@kotlinx.datetime.Month(kotlinx.datetime.TextStyle;kotlinx.datetime.Locale){}[0]
 final fun (kotlinx.datetime/TimeZone).kotlinx.datetime/offsetAt(kotlin.time/Instant): kotlinx.datetime/UtcOffset // kotlinx.datetime/offsetAt|offsetAt@kotlinx.datetime.TimeZone(kotlin.time.Instant){}[0]
 final fun (kotlinx.datetime/TimeZone).kotlinx.datetime/offsetAt(kotlinx.datetime/Instant): kotlinx.datetime/UtcOffset // kotlinx.datetime/offsetAt|offsetAt@kotlinx.datetime.TimeZone(kotlinx.datetime.Instant){}[0]
 final fun (kotlinx.datetime/UtcOffset).kotlinx.datetime/asTimeZone(): kotlinx.datetime/FixedOffsetTimeZone // kotlinx.datetime/asTimeZone|asTimeZone@kotlinx.datetime.UtcOffset(){}[0]

core/common/src/DayOfWeekExt.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2019-2025 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+@file:JvmName("DayOfWeekKt")
+@file:JvmMultifileClass
+
+package kotlinx.datetime
+
+import kotlin.jvm.JvmMultifileClass
+import kotlin.jvm.JvmName
+
+/**
+ * Returns the localized display name for this day of the week.
+ *
+ * The display name is formatted according to the specified [textStyle] and [locale].
+ * For example, [DayOfWeek.MONDAY] with [TextStyle.FULL_STANDALONE] and English locale
+ * returns "Monday", while with [TextStyle.SHORT] it returns "Mon".
+ *
+ * The distinction between standalone and non-standalone styles matters in some languages
+ * where grammatical forms differ based on context. For example, in some Slavic languages,
+ * the standalone form is used when the day appears alone, while the non-standalone form
+ * is used when it's part of a date phrase.
+ *
+ * @param textStyle the text style to use for formatting (default: [TextStyle.FULL_STANDALONE])
+ * @param locale the locale to use for formatting (default: system default locale)
+ * @return the localized display name for this day of the week
+ * @sample kotlinx.datetime.test.samples.DayOfWeekSamples.displayName
+ */
+public expect fun DayOfWeek.displayName(
+    textStyle: TextStyle = TextStyle.FULL_STANDALONE,
+    locale: Locale = Locale.getDefault()
+): String

core/common/src/Locale.kt

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2019-2025 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime
+
+/**
+ * Represents a locale, which is used to format date and time values according to cultural conventions.
+ *
+ * This is a platform-specific type:
+ * - On JVM: [java.util.Locale]
+ * - On iOS/macOS: NSLocale
+ * - On other platforms: platform-specific locale representation
+ *
+ * @sample kotlinx.datetime.test.samples.LocaleSamples.usage
+ */
+public expect class Locale {
+    public companion object {
+        /**
+         * Returns the default locale for the current system.
+         */
+        public fun getDefault(): Locale
+    }
+}

core/common/src/MonthExt.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2019-2025 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+@file:JvmName("MonthKt")
+@file:JvmMultifileClass
+
+package kotlinx.datetime
+
+import kotlin.jvm.JvmMultifileClass
+import kotlin.jvm.JvmName
+
+/**
+ * Returns the localized display name for this month.
+ *
+ * The display name is formatted according to the specified [textStyle] and [locale].
+ * For example, [Month.JANUARY] with [TextStyle.FULL_STANDALONE] and English locale
+ * returns "January", while with [TextStyle.SHORT] it returns "Jan".
+ *
+ * The distinction between standalone and non-standalone styles matters in some languages
+ * where grammatical forms differ based on context. For example, in Polish, the standalone
+ * form of January is "styczeń", while the genitive form used in dates is "stycznia".
+ *
+ * @param textStyle the text style to use for formatting (default: [TextStyle.FULL_STANDALONE])
+ * @param locale the locale to use for formatting (default: system default locale)
+ * @return the localized display name for this month
+ * @sample kotlinx.datetime.test.samples.MonthSamples.displayName
+ */
+public expect fun Month.displayName(
+    textStyle: TextStyle = TextStyle.FULL_STANDALONE,
+    locale: Locale = Locale.getDefault()
+): String

core/common/src/TextStyle.kt

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2019-2025 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime
+
+/**
+ * Represents the style used for formatting date-time text, such as month or day-of-week names.
+ *
+ * Different styles provide different levels of detail and formatting:
+ * - [FULL] and [FULL_STANDALONE] provide complete names (e.g., "January", "Monday")
+ * - [SHORT] and [SHORT_STANDALONE] provide abbreviated names (e.g., "Jan", "Mon")
+ * - [NARROW] and [NARROW_STANDALONE] provide minimal names (e.g., "J", "M")
+ *
+ * The standalone versions are used when the name appears in isolation,
+ * while the non-standalone versions are used when the name appears as part of a larger phrase.
+ * This distinction is important in some languages where grammatical forms differ based on context.
+ * For example, in Polish, the standalone form of "January" is "styczeń",
+ * while the genitive form used in dates is "stycznia".
+ */
+public enum class TextStyle {
+    /**
+     * Full text style, typically used in context (e.g., "Monday", "January").
+     */
+    FULL,
+
+    /**
+     * Full text style for standalone use (e.g., "Monday", "January").
+     * This is the default style for most use cases.
+     */
+    FULL_STANDALONE,
+
+    /**
+     * Short or abbreviated text style, typically used in context (e.g., "Mon", "Jan").
+     */
+    SHORT,
+
+    /**
+     * Short or abbreviated text style for standalone use (e.g., "Mon", "Jan").
+     */
+    SHORT_STANDALONE,
+
+    /**
+     * Narrow text style, typically a single character, used in context (e.g., "M", "J").
+     */
+    NARROW,
+
+    /**
+     * Narrow text style for standalone use, typically a single character (e.g., "M", "J").
+     */
+    NARROW_STANDALONE,
+}

core/common/src/format/DayOfWeekNamesExt.kt

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2019-2025 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime.format
+
+/**
+ * Narrow English names of weekdays from 'M' to 'S'.
+ * Used primarily as fallback for localization on platforms where narrow names are unavailable.
+ */
+public val DayOfWeekNames.Companion.ENGLISH_NARROW: List<String>
+    get() = listOf("M", "T", "W", "T", "F", "S", "S")

core/common/src/format/MonthNamesExt.kt

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2019-2025 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime.format
+
+/**
+ * Narrow English month names.
+ * Used primarily as fallback for localization on platforms where narrow names are unavailable.
+ */
+public val MonthNames.Companion.ENGLISH_NARROW: List<String>
+    get() = listOf(
+        "J", "F", "M", "A", "M", "J",
+        "J", "A", "S", "O", "N", "D"
+    )