intl

README

intl

CLDR v48.0 based date formatting in Golang. The formatting output is identical to the Intl.DateTimeFormat by the Node.js v24.15.0.

Requirements

Go version 1.24+.

DateTimeFormat

Option	Supported
era	✅︎
year	✅︎
month	✅︎
day	✅︎
hour	❌
minute	❌
second	❌
fractionalSecondDigits	❌
weekday	❌
hourCycle	❌
timeZoneName	❌

Development

The project uses Earthly to automate all development tasks that can be run locally and in CI/CD environments.

Documentation

Overview

Package intl provides internationalization and localization support for date and time formatting, inspired by and reflecting the ECMAScript Intl API.

This package offers a flexible and extensible way to format dates and times according to various locales, calendar systems, and custom options, similar to the JavaScript Intl.DateTimeFormat object. It supports multiple numeral systems and calendar types, including Gregorian, Persian, and Buddhist calendars.

Key features:

• Locale-aware date and time formatting
• Support for different calendar systems
• Customizable date and time formatting options
• Handling of various numeral systems
• API design similar to ECMAScript Intl.DateTimeFormat

The main types in this package are:

• DateTimeFormat: Encapsulates formatting logic for dates and times, similar to Intl.DateTimeFormat
• Options: Configures formatting options for date and time representations

Usage:

formatter := intl.NewDateTimeFormat(locale, Options{Day: Day2Digit})
now := formatter.Format(time.Now())

Index

• type DateTimeFormat
  • func NewDateTimeFormat(locale language.Tag, options Options) DateTimeFormat
  • func (f DateTimeFormat) Format(t time.Time) string
• type Day
  • func MustParseDay(s string) Day
  • func ParseDay(s string) (Day, error)
  • func (d Day) String() string
• type Era
  • func MustParseEra(s string) Era
  • func ParseEra(s string) (Era, error)
  • func (e Era) String() string
• type Month
  • func MustParseMonth(s string) Month
  • func ParseMonth(s string) (Month, error)
  • func (m Month) String() string
• type Options
• type Year
  • func MustParseYear(s string) Year
  • func ParseYear(s string) (Year, error)
  • func (y Year) String() string

Types

type DateTimeFormat

type DateTimeFormat struct {
	// contains filtered or unexported fields
}

DateTimeFormat encapsulates the configuration and functionality for formatting dates and times according to specific locales and options.

func NewDateTimeFormat

func NewDateTimeFormat(locale language.Tag, options Options) DateTimeFormat

NewDateTimeFormat creates a new DateTimeFormat instance for the specified locale and options.

This function initializes a DateTimeFormat with the default calendar based on the given locale. It supports different calendar systems including Gregorian, Persian, and Buddhist calendars.

func (DateTimeFormat) Format

func (f DateTimeFormat) Format(t time.Time) string

Format formats the given time.Time value according to the DateTimeFormat's configuration.

This method applies the formatting options specified in the DateTimeFormat instance to the provided time value.

type Day

type Day byte

Day represents the format for displaying days.

const (
	DayUnd Day = iota
	DayNumeric
	Day2Digit
)

func MustParseDay

func MustParseDay(s string) Day

MustParseDay converts a string representation of a year format to the Day type. It panics if the input string is not a valid day format.

func ParseDay

func ParseDay(s string) (Day, error)

ParseDay converts a string representation of a year format to the Day type.

Parameters:

• s: A string representing the day format. Valid values are "numeric", "2-digit", or an empty string.

Returns:

• Year: The corresponding Day constant (DayNumeric, Day2Digit, or DayUnd).
• error: An error if the input string is not a valid day format.

func (Day) String

func (d Day) String() string

String returns the string representation of the Day format. It converts the Day constant to its corresponding string value.

Returns:

• "numeric" for DayNumeric
• "2-digit" for Day2Digit
• "" for any other value (including DayUnd)

type Era

type Era byte

const (
	EraUnd Era = iota
	EraNarrow
	EraShort
	EraLong
)

func MustParseEra

func MustParseEra(s string) Era

MustParseEra converts a string representation of an era format to the Era type. It panics if the input string is not a valid era format.

func ParseEra

func ParseEra(s string) (Era, error)

ParseEra converts a string representation of a year format to the Era type.

Parameters:

• s: A string representing the era format. Valid values are "narrow", "short", "long" or an empty string.

Returns:

• Era: The corresponding Era constant (EraNarrow, EraShort, or EraLong).
• error: An error if the input string is not a valid era format.

func (Era) String

func (e Era) String() string

String returns the string representation of the Era. It converts the Era constant to its corresponding string value.

Returns:

• "narrow" for EraNarrow
• "short" for EraShort
• "long" for EraLong
• "" for any other value (including EraUnd)

type Month

type Month byte

Month represents the format for displaying months.

const (
	MonthUnd Month = iota
	MonthNumeric
	Month2Digit
	MonthLong
	MonthShort
	MonthNarrow
)

func MustParseMonth

func MustParseMonth(s string) Month

MustParseMonth converts a string representation of a month format to the Month type. It panics if the input string is not a valid month format.

func ParseMonth

func ParseMonth(s string) (Month, error)

ParseMonth converts a string representation of a month format to the Month type.

Parameters:

• s: A string representing the month format. Valid values are "numeric", "2-digit", "long", "short", "narrow", or an empty string.

Returns:

• Month: The corresponding Month constant (MonthNumeric, Month2Digit, MonthLong, MonthShort, MonthNarrow, or MonthUnd).
• error: An error if the input string is not a valid month format.

func (Month) String

func (m Month) String() string

String returns the string representation of the Month. It converts the Month constant to its corresponding string value.

Returns:

• "numeric" for MonthNumeric
• "2-digit" for Month2Digit
• "long" for MonthLong
• "short" for MonthShort
• "narrow" for MonthNarrow
• "" for any other value (including MonthUnd)

type Options

type Options struct {
	Era   Era
	Year  Year
	Month Month
	Day   Day
}

Options defines configuration parameters for NewDateTimeFormat. It allows customization of the date and time representations in formatted output.

type Year

type Year byte

Year is year option for Options.

const (
	YearUnd Year = iota
	YearNumeric
	Year2Digit
)

func MustParseYear

func MustParseYear(s string) Year

MustParseYear converts a string representation of a year format to the Year type. It panics if the input string is not a valid year format.

func ParseYear

func ParseYear(s string) (Year, error)

ParseYear converts a string representation of a year format to the Year type.

Parameters:

• s: A string representing the year format. Valid values are "numeric", "2-digit", or an empty string.

Returns:

• Year: The corresponding Year constant (YearNumeric, Year2Digit, or YearUnd).
• error: An error if the input string is not a valid year format.

func (Year) String

func (y Year) String() string

String returns the string representation of the Year. It converts the Year constant to its corresponding string value.

Returns:

• "numeric" for YearNumeric
• "2-digit" for Year2Digit
• "" for any other value (including YearUnd)