README
¶
lctime
Finally, simple, familiar, locale-based datetime formatting.
Install
go get -u gitlab.com/variadico/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 := lctime.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 langauge 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.
- LC_TIME
- LC_ALL
- 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 ¶
Examples ¶
Constants ¶
This section is empty.
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 Strftime ¶
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 ¶
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 ¶
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 ¶
NewLocalizer provides a localizer to a specific locale.
Source Files
Directories