cldr

README

CLDR

cldr is a golang library using Common Locale Data Repository to format dates, plurals (and more in the future), inspired by twitter-cldr-rb and borrowing some codes from github.com/vube/i18n.

How to use

cldr embeds CLDR data in pure go and it doesn't import all those locale data by default. If you are using specific locale data, you can import that package as bellow:

package main

import (
	"github.com/ContextLogic/cldr"
	_ "github.com/ContextLogic/cldr/resources/locales/en"
)

func main() {
	cldr.Parse(
		"en",
		`{{p "Count" (one "{{.Count}} item") (other "{{.Count}} items")}}`,
		map[string]int{"Count": 1},
	) // "1 item in Your Cart"
}

If you don't like hand-importing locales, you can import github.com/ContextLogic/cldr/resources/locales, which import all available locales in cldr pacakge.

More API could be found here.

How to add locales

cldr.RegisterLocale(Locale{...})

How to override default locales

// solution 1
// using the same locale name

import _ github.com/ContextLogic/cldr/resources/locales/en
cldr.RegisterLocale(Locale{Locale: "en"})

// solution 2
// update the exported locale directly

import github.com/ContextLogic/cldr/resources/locales/en
en.Locale.PluralRule = "2A"

Documentation

Index

• Constants
• Variables
• func Copy(dst, src *Locale)
• func FmtCurrency(locale string, currency string, number interface{}) (formatted string, err error)
• func FmtCurrencyWhole(locale string, currency string, number interface{}) (formatted string, err error)
• func FmtDateFull(locale string, tim time.Time) (formatted string, err error)
• func FmtDateLong(locale string, tim time.Time) (formatted string, err error)
• func FmtDateMedium(locale string, tim time.Time) (formatted string, err error)
• func FmtDateShort(locale string, tim time.Time) (formatted string, err error)
• func FmtDateTimeFull(locale string, tim time.Time) (formatted string, err error)
• func FmtDateTimeLong(locale string, tim time.Time) (formatted string, err error)
• func FmtDateTimeMedium(locale string, tim time.Time) (formatted string, err error)
• func FmtDateTimeShort(locale string, tim time.Time) (formatted string, err error)
• func FmtNumber(locale string, number interface{}) (formatted string, err error)
• func FmtNumberWhole(locale string, number interface{}) (formatted string, err error)
• func FmtPercent(locale string, number interface{}) (formatted string, err error)
• func FmtTimeFull(locale string, tim time.Time) (formatted string, err error)
• func FmtTimeLong(locale string, tim time.Time) (formatted string, err error)
• func FmtTimeMedium(locale string, tim time.Time) (formatted string, err error)
• func FmtTimeShort(locale string, tim time.Time) (formatted string, err error)
• func GetPluralForm(locale string) (string, error)
• func GetPluralRule(locale string) (string, error)
• func Parse(locale, text string, args ...interface{}) (r string, err error)
• func RegisterLocale(loc *Locale)
• func RegisterLocales(locs ...*Locale)
• func RegisterPluralRule(locale string, ruler PluralRuler)
• func T(locale, key string, args ...interface{}) (formatted string, err error)
• type Calendar
  • func (c Calendar) FmtDateFull(t time.Time) (string, error)
  • func (c Calendar) FmtDateLong(t time.Time) (string, error)
  • func (c Calendar) FmtDateMedium(t time.Time) (string, error)
  • func (c Calendar) FmtDateShort(t time.Time) (string, error)
  • func (c Calendar) FmtDateTimeFull(t time.Time) (string, error)
  • func (c Calendar) FmtDateTimeLong(t time.Time) (string, error)
  • func (c Calendar) FmtDateTimeMedium(t time.Time) (string, error)
  • func (c Calendar) FmtDateTimeShort(t time.Time) (string, error)
  • func (c Calendar) FmtTimeFull(t time.Time) (string, error)
  • func (c Calendar) FmtTimeLong(t time.Time) (string, error)
  • func (c Calendar) FmtTimeMedium(t time.Time) (string, error)
  • func (c Calendar) FmtTimeShort(t time.Time) (string, error)
  • func (c Calendar) Format(datetime time.Time, pattern string) (string, error)
• type CalendarDateFormat
• type CalendarDayFormatNameValue
• type CalendarDayFormatNames
• type CalendarFormatNames
• type CalendarFormats
• type CalendarMonthFormatNameValue
• type CalendarMonthFormatNames
• type CalendarPeriodFormatNameValue
• type CalendarPeriodFormatNames
• type Currency
• type Locale
  • func GetLocale(locale string) (*Locale, bool)
  • func (l *Locale) FmtCurrency(currency string, number interface{}) (formatted string, err error)
  • func (l *Locale) FmtCurrencyWhole(currency string, number interface{}) (formatted string, err error)
  • func (l *Locale) FmtDateFull(tim time.Time) (string, error)
  • func (l *Locale) FmtDateLong(tim time.Time) (string, error)
  • func (l *Locale) FmtDateMedium(tim time.Time) (string, error)
  • func (l *Locale) FmtDateShort(tim time.Time) (string, error)
  • func (l *Locale) FmtDateTimeFull(tim time.Time) (string, error)
  • func (l *Locale) FmtDateTimeLong(tim time.Time) (string, error)
  • func (l *Locale) FmtDateTimeMedium(tim time.Time) (string, error)
  • func (l *Locale) FmtDateTimeShort(tim time.Time) (string, error)
  • func (l *Locale) FmtNumber(number interface{}) string
  • func (l *Locale) FmtNumberWhole(number interface{}) string
  • func (l *Locale) FmtPercent(number interface{}) string
  • func (l *Locale) FmtTimeFull(tim time.Time) (string, error)
  • func (l *Locale) FmtTimeLong(tim time.Time) (string, error)
  • func (l *Locale) FmtTimeMedium(tim time.Time) (string, error)
  • func (l *Locale) FmtTimeShort(tim time.Time) (string, error)
  • func (l Locale) FuncMap() template.FuncMap
• type Number
  • func (n Number) FmtCurrency(currency string, number float64) (formatted string, err error)
  • func (n Number) FmtCurrencyWhole(currency string, number float64) (formatted string, err error)
  • func (n Number) FmtNumber(number float64) string
  • func (n Number) FmtNumberWhole(number float64) string
  • func (n Number) FmtPercent(number float64) string
• type NumberFormats
• type NumberValue
• type PluralRule
  • func FindRule(locale string, count NumberValue) (rule PluralRule)
• type PluralRuler
• type PluralRulerFunc
  • func (p PluralRulerFunc) FindRule(n NumberValue) PluralRule
• type Symbols

Constants

const (
	DateFormatFull = iota
	DateFormatLong
	DateFormatMedium
	DateFormatShort
	TimeFormatFull
	TimeFormatLong
	TimeFormatMedium
	TimeFormatShort
	DateTimeFormatFull
	DateTimeFormatLong
	DateTimeFormatMedium
	DateTimeFormatShort
)

Standard Formats for Dates, Times & DateTimes These are the options to pass to the Format method.

const (
	PluralRuleZero  PluralRule = "zero"  // zero
	PluralRuleOne              = "one"   // singular
	PluralRuleTwo              = "two"   // dual
	PluralRuleFew              = "few"   // paucal
	PluralRuleMany             = "many"  // also used for fractions if they have a separate class
	PluralRuleOther            = "other" // required—general plural form—also used if the language only has a single form
)

Variables

var FuncMap = template.FuncMap{
	"t":                    Parse,
	"locale":               func() string { return "" },
	"fmt_date_full":        FmtDateFull,
	"fmt_date_long":        FmtDateLong,
	"fmt_date_medium":      FmtDateMedium,
	"fmt_date_short":       FmtDateShort,
	"fmt_date_time_full":   FmtDateTimeFull,
	"fmt_date_time_long":   FmtDateTimeLong,
	"fmt_date_time_medium": FmtDateTimeMedium,
	"fmt_date_time_short":  FmtDateTimeShort,
	"fmt_time_full":        FmtTimeFull,
	"fmt_time_long":        FmtTimeLong,
	"fmt_time_medium":      FmtTimeMedium,
	"fmt_time_short":       FmtTimeShort,
	"fmt_currency":         FmtCurrency,
	"fmt_currency_whole":   FmtCurrencyWhole,
	"fmt_number":           FmtNumber,
	"fmt_number_whole":     FmtNumberWhole,
	"fmt_percent":          FmtPercent,
}

Functions

func Copy

func Copy(dst, src *Locale)

Copy only override dst value if src value is not a zero value

TODO: write a auto generator

func FmtCurrency

func FmtCurrency(locale string, currency string, number interface{}) (formatted string, err error)

func FmtCurrencyWhole

func FmtCurrencyWhole(locale string, currency string, number interface{}) (formatted string, err error)

func FmtDateFull

func FmtDateFull(locale string, tim time.Time) (formatted string, err error)

func FmtDateLong

func FmtDateLong(locale string, tim time.Time) (formatted string, err error)

func FmtDateMedium

func FmtDateMedium(locale string, tim time.Time) (formatted string, err error)

func FmtDateShort

func FmtDateShort(locale string, tim time.Time) (formatted string, err error)

func FmtDateTimeFull

func FmtDateTimeFull(locale string, tim time.Time) (formatted string, err error)

func FmtDateTimeLong

func FmtDateTimeLong(locale string, tim time.Time) (formatted string, err error)

func FmtDateTimeMedium

func FmtDateTimeMedium(locale string, tim time.Time) (formatted string, err error)

func FmtDateTimeShort

func FmtDateTimeShort(locale string, tim time.Time) (formatted string, err error)

func FmtNumber

func FmtNumber(locale string, number interface{}) (formatted string, err error)

func FmtNumberWhole

func FmtNumberWhole(locale string, number interface{}) (formatted string, err error)

func FmtPercent

func FmtPercent(locale string, number interface{}) (formatted string, err error)

func FmtTimeFull

func FmtTimeFull(locale string, tim time.Time) (formatted string, err error)

func FmtTimeLong

func FmtTimeLong(locale string, tim time.Time) (formatted string, err error)

func FmtTimeMedium

func FmtTimeMedium(locale string, tim time.Time) (formatted string, err error)

func FmtTimeShort

func FmtTimeShort(locale string, tim time.Time) (formatted string, err error)

func GetPluralForm

func GetPluralForm(locale string) (string, error)

GetPluralForm returns the plural form corresponding to a locale http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html

func GetPluralRule

func GetPluralRule(locale string) (string, error)

GetPluralRule returns the plural rule corresponding to a locale, in the form "[1-6][A-I]" as defined above

func Parse

func Parse(locale, text string, args ...interface{}) (r string, err error)

TODO: rename to T and add helper in Locale

func RegisterLocale

func RegisterLocale(loc *Locale)

TODO: can override partially instead of replace it as a whole for existed locales

func RegisterLocales

func RegisterLocales(locs ...*Locale)

RegisterLocales registers multiple locales in one go.

func RegisterPluralRule

func RegisterPluralRule(locale string, ruler PluralRuler)

func T

func T(locale, key string, args ...interface{}) (formatted string, err error)

Types

type Calendar

type Calendar struct {
	Formats     CalendarFormats
	FormatNames CalendarFormatNames
}

func (Calendar) FmtDateFull

func (c Calendar) FmtDateFull(t time.Time) (string, error)

func (Calendar) FmtDateLong

func (c Calendar) FmtDateLong(t time.Time) (string, error)

func (Calendar) FmtDateMedium

func (c Calendar) FmtDateMedium(t time.Time) (string, error)

func (Calendar) FmtDateShort

func (c Calendar) FmtDateShort(t time.Time) (string, error)

func (Calendar) FmtDateTimeFull

func (c Calendar) FmtDateTimeFull(t time.Time) (string, error)

func (Calendar) FmtDateTimeLong

func (c Calendar) FmtDateTimeLong(t time.Time) (string, error)

func (Calendar) FmtDateTimeMedium

func (c Calendar) FmtDateTimeMedium(t time.Time) (string, error)

func (Calendar) FmtDateTimeShort

func (c Calendar) FmtDateTimeShort(t time.Time) (string, error)

func (Calendar) FmtTimeFull

func (c Calendar) FmtTimeFull(t time.Time) (string, error)

func (Calendar) FmtTimeLong

func (c Calendar) FmtTimeLong(t time.Time) (string, error)

func (Calendar) FmtTimeMedium

func (c Calendar) FmtTimeMedium(t time.Time) (string, error)

func (Calendar) FmtTimeShort

func (c Calendar) FmtTimeShort(t time.Time) (string, error)

func (Calendar) Format

func (c Calendar) Format(datetime time.Time, pattern string) (string, error)

Format takes a time struct and a format and returns a formatted string. Callers should use a DateFormat, TimeFormat, or DateTimeFormat constant.

type CalendarDateFormat

type CalendarDateFormat struct{ Full, Long, Medium, Short string }

type CalendarDayFormatNameValue

type CalendarDayFormatNameValue struct {
	Sun, Mon, Tue, Wed, Thu, Fri, Sat string
}

type CalendarDayFormatNames

type CalendarDayFormatNames struct {
	Abbreviated CalendarDayFormatNameValue
	Narrow      CalendarDayFormatNameValue
	Short       CalendarDayFormatNameValue
	Wide        CalendarDayFormatNameValue
}

type CalendarFormatNames

type CalendarFormatNames struct {
	Months  CalendarMonthFormatNames
	Days    CalendarDayFormatNames
	Periods CalendarPeriodFormatNames
}

type CalendarFormats

type CalendarFormats struct {
	Date     CalendarDateFormat
	Time     CalendarDateFormat
	DateTime CalendarDateFormat
}

type CalendarMonthFormatNameValue

type CalendarMonthFormatNameValue struct {
	Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec string
}

type CalendarMonthFormatNames

type CalendarMonthFormatNames struct {
	Abbreviated CalendarMonthFormatNameValue
	Narrow      CalendarMonthFormatNameValue
	Short       CalendarMonthFormatNameValue
	Wide        CalendarMonthFormatNameValue
}

type CalendarPeriodFormatNameValue

type CalendarPeriodFormatNameValue struct {
	AM, PM string
}

type CalendarPeriodFormatNames

type CalendarPeriodFormatNames struct {
	Abbreviated CalendarPeriodFormatNameValue
	Narrow      CalendarPeriodFormatNameValue
	Short       CalendarPeriodFormatNameValue
	Wide        CalendarPeriodFormatNameValue
}

type Currency

type Currency struct {
	Currency    string
	DisplayName string
	Symbol      string
}

type Locale

type Locale struct {
	Locale     string
	Number     Number
	Calendar   Calendar
	PluralRule string
}

@xerox

func GetLocale

func GetLocale(locale string) (*Locale, bool)

GetLocale returns a pointer to an existing locale object and a boolean whether the locale exists.

func (*Locale) FmtCurrency

func (l *Locale) FmtCurrency(currency string, number interface{}) (formatted string, err error)

func (*Locale) FmtCurrencyWhole

func (l *Locale) FmtCurrencyWhole(currency string, number interface{}) (formatted string, err error)

func (*Locale) FmtDateFull

func (l *Locale) FmtDateFull(tim time.Time) (string, error)

func (*Locale) FmtDateLong

func (l *Locale) FmtDateLong(tim time.Time) (string, error)

func (*Locale) FmtDateMedium

func (l *Locale) FmtDateMedium(tim time.Time) (string, error)

func (*Locale) FmtDateShort

func (l *Locale) FmtDateShort(tim time.Time) (string, error)

func (*Locale) FmtDateTimeFull

func (l *Locale) FmtDateTimeFull(tim time.Time) (string, error)

func (*Locale) FmtDateTimeLong

func (l *Locale) FmtDateTimeLong(tim time.Time) (string, error)

func (*Locale) FmtDateTimeMedium

func (l *Locale) FmtDateTimeMedium(tim time.Time) (string, error)

func (*Locale) FmtDateTimeShort

func (l *Locale) FmtDateTimeShort(tim time.Time) (string, error)

func (*Locale) FmtNumber

func (l *Locale) FmtNumber(number interface{}) string

func (*Locale) FmtNumberWhole

func (l *Locale) FmtNumberWhole(number interface{}) string

func (*Locale) FmtPercent

func (l *Locale) FmtPercent(number interface{}) string

func (*Locale) FmtTimeFull

func (l *Locale) FmtTimeFull(tim time.Time) (string, error)

func (*Locale) FmtTimeLong

func (l *Locale) FmtTimeLong(tim time.Time) (string, error)

func (*Locale) FmtTimeMedium

func (l *Locale) FmtTimeMedium(tim time.Time) (string, error)

func (*Locale) FmtTimeShort

func (l *Locale) FmtTimeShort(tim time.Time) (string, error)

func (Locale) FuncMap

func (l Locale) FuncMap() template.FuncMap

type Number

type Number struct {
	Symbols    Symbols
	Formats    NumberFormats
	Currencies []Currency
}

func (Number) FmtCurrency

func (n Number) FmtCurrency(currency string, number float64) (formatted string, err error)

FormatCurrency takes a float number and a currency key and returns a string with a properly formatted currency amount with the correct currency symbol. If a symbol cannot be found for the reqested currency, the the key is used instead. If the currency key requested is not recognized, it is used as the symbol, and an error is returned with the formatted string.

func (Number) FmtCurrencyWhole

func (n Number) FmtCurrencyWhole(currency string, number float64) (formatted string, err error)

FormatCurrencyWhole does exactly what FormatCurrency does, but it leaves off any decimal places. AKA, it would return $100 rather than $100.00.

func (Number) FmtNumber

func (n Number) FmtNumber(number float64) string

FormatNumber takes a float number and returns a properly formatted string representation of that number according to the locale's number format.

func (Number) FmtNumberWhole

func (n Number) FmtNumberWhole(number float64) string

FormatNumberWhole does exactly what FormatNumber does, but it leaves off any decimal places. AKA, it would return 100 rather than 100.01.

func (Number) FmtPercent

func (n Number) FmtPercent(number float64) string

FormatPercent takes a float number and returns a properly formatted string representation of that number as a percentage according to the locale's percentage format.

type NumberFormats

type NumberFormats struct {
	Decimal  string
	Currency string
	Percent  string
}

type NumberValue

type NumberValue interface{}

Number should be one of these types:

int, float

type PluralRule

type PluralRule string

func FindRule

func FindRule(locale string, count NumberValue) (rule PluralRule)

type PluralRuler

type PluralRuler interface {
	FindRule(n NumberValue) PluralRule
}

type PluralRulerFunc

type PluralRulerFunc func(n NumberValue) PluralRule

func (PluralRulerFunc) FindRule

func (p PluralRulerFunc) FindRule(n NumberValue) PluralRule

type Symbols

type Symbols struct {
	Decimal  string
	Group    string
	Negative string
	Percent  string
	PerMille string
}