lctime

README

lctime

Finally, simple, familiar, locale-based datetime formatting.

Install

go get -u github.com/klauspost/lctime

Usage

// Default locale is based on env vars or en_US if none are set.
fmt.Println(lctime.Strftime("%c", time.Now()))
// prints: Mon 14 Dec 2015 10:31:56 PM PST

lctime.SetLocale("es_MX")
fmt.Println(lctime.Strftime("%c", time.Now()))
// prints: lun 14 dic 2015 22:31:56 PST

This is very easy if your application only has to translate to a single language.

Multiple Locales

To do translation to multiple languages without having collisions, you can use the StrftimeLoc function. It allows you to specify a locale along your time to be translated.

	t := time.Date(2015, 12, 25, 3, 2, 1, 0, time.UTC)
	txt, err := StrftimeLoc("es_MX", "%A, %d de %B de %Y", t)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(txt)

	// Prints viernes, 25 de diciembre de 2015

If you need to do several translations or need to pass your localizer as a parameter, you can use the NewLocalizer function. It allows you to localize several strings to the same language without having to specify it every time.

	t := time.Date(2015, 12, 25, 3, 2, 1, 0, time.UTC)
	l, err := NewLocalizer("da_DK")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(l.Strftime("%A den %d. %B %Y", t))

	// Prints: fredag den 25. december 2015

The problem with the Go standard library

Go's standard library time is fine most of the time. However, it's currently impossible for the Go standard library to format dates based on a user's locale or language setting. Unfortunately, that means code like this, doesn't work.

d := time.Date(2015, 12, 25, 3, 2, 1, 0, time.UTC)
fmt.Println(d.Format("lunes, 02 de enero de 2006"))
// got:  lunes, 25 de enero de 2015
// want: viernes, 25 de diciembre de 2015

More importantly, it also means that non-English speakers will either be stuck with purely numeric dates or dates in a language they don't prefer.

The solution offered by lctime

lctime brings the familiar setlocale and strftime functions found in other programming languages like C, Python, or PHP. The formats and translations used for this package are loosely based on glibc locale files, with close to 300 locales.

Locale data is just Go code, generated by go-bindata. This means you don't have to worry about shipping anything extra. Just import and use lctime like any other package and go build like normal. Everything will just work.

Documentation

Overview

Package lctime provides a way to format dates and times using strftime directives. More importantly, it does so in a locale-aware fashion. This allows developers to format time based on a user's locale.

An initial locale is loaded at import time. It's determined by the first, non-empty locale identifier from these environment variables.

1. LC_TIME
2. LC_ALL
3. LANG

If all of the previous variables are empty, then POSIX will be the initial locale used. All locales use UTF-8 character encoding.

The formats used are loosely based on glibc locale files.

These are the supported strftime directives. They're loosely based on The Open Group Base Specifications Issue 7, http://pubs.opengroup.org/onlinepubs/9699919799/functions/strftime.html.

%a  locale's abbreviated weekday name
%A  locale's full weekday name
%b  locale's abbreviated month name
%B  locale's full month name
%c  locale's appropriate date and time representation
%C  year divided by 100 and truncated to an integer
%d  day of the month as a decimal number [01,31]
%D  %m/%d/%y
%e  day of the month as a decimal number [1,31]
%F  %Y/%m/%d
%g  last 2 digits of the week-based year as a decimal number
%G  week-based year as a decimal number (for example, 1977)
%H  hour (24-hour clock) as a decimal number [00,23]
%I  hour (12-hour clock) as a decimal number [01,12]
%j  day of the year as a decimal number [001,366]
%m  month as a decimal number [01,12]
%M  minute as a decimal number [00,59]
%n  returns a newline
%p  locale's equivalent of either a.m. or p.m.
%r  time in a.m. and p.m. notation.
%R  time in 24-hour notation %H:%M
%S  second as a decimal number [00,60]
%t  returns a tab
%T  %H:%M:%S
%u  weekday as a decimal number [1,7]
%U  week number of the year as a decimal number [00,53]
%V  week number of the year
%w  weekday as a decimal number [0,6]
%W  week number of the year as a decimal number [00,53]
%x  locale's appropriate date representation
%X  locale's appropriate time representation
%y  last two digits of the year as a decimal number [00,99]
%Y  year as a decimal number (for example, 1997)
%z  offset from UTC in the ISO 8601:2000 standard format
%Z  timezone name or abbreviation
%%  %

Index

• Variables
• func GetLocale() string
• func GetLocales() []string
• func SetLocale(id string) error
• func Strftime(format string, t time.Time) string
• func StrftimeLoc(locale, format string, t time.Time) (string, error)
• type Localizer
  • func NewLocalizer(id string) (Localizer, error)

Examples

• Localizer
• Strftime
• StrftimeLoc

Variables

var (
	// ErrNoLocale is returned when a given locale was not found.
	ErrNoLocale = errors.New("Locale not found")
	// ErrCorruptLocale is returned if a given locale file is corrupted.
	ErrCorruptLocale = errors.New("Corrupted locale")
)

Functions

func GetLocale

func GetLocale() string

GetLocale returns the currently active locale.

func GetLocales

func GetLocales() []string

GetLocales returns a slice of available locales.

func SetLocale

func SetLocale(id string) error

SetLocale activates the given locale.

func Strftime

func Strftime(format string, t time.Time) string

Strftime formats a time.Time. It's locale-aware, so make sure you call SetLocale if needed.

Example

// Initial locale based on env vars. If not set, then POSIX is used.
t := time.Date(2000, 1, 2, 3, 4, 5, 6, time.UTC)
fmt.Println(Strftime("%c", t))

Output:

Sun 02 Jan 2000 03:04:05 AM UTC

func StrftimeLoc

func StrftimeLoc(locale, format string, t time.Time) (string, error)

StrftimeLoc formats a time.Time. It's locale-aware, so make sure you call SetLocale if needed.

Example

t := time.Date(2015, 12, 25, 3, 2, 1, 0, time.UTC)
txt, err := StrftimeLoc("es_MX", "%A, %d de %B de %Y", t)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(txt)

Output:

viernes, 25 de diciembre de 2015

Types

type Localizer

type Localizer interface {
	Strftime(format string, t time.Time) string
}

Localizer provides translation to a locale.

Example

t := time.Date(2015, 12, 25, 3, 2, 1, 0, time.UTC)
l, err := NewLocalizer("da_DK")
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(l.Strftime("%A den %d. %B %Y", t))

Output:

fredag den 25. december 2015

func NewLocalizer

func NewLocalizer(id string) (Localizer, error)

NewLocalizer provides a localizer to a specific locale.