README.md
1## locales
2<img align="right" src="https://raw.githubusercontent.com/go-playground/locales/master/logo.png">
3[](https://travis-ci.org/go-playground/locales)
4[](https://goreportcard.com/report/github.com/go-playground/locales)
5[](https://godoc.org/github.com/go-playground/locales)
6
7[](https://gitter.im/go-playground/locales?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
8
9Locales is a set of locales generated from the [Unicode CLDR Project](http://cldr.unicode.org/) which can be used independently or within
10an i18n package; these were built for use with, but not exclusive to, [Universal Translator](https://github.com/go-playground/universal-translator).
11
12Features
13--------
14- [x] Rules generated from the latest [CLDR](http://cldr.unicode.org/index/downloads) data, v31.0.1
15- [x] Contains Cardinal, Ordinal and Range Plural Rules
16- [x] Contains Month, Weekday and Timezone translations built in
17- [x] Contains Date & Time formatting functions
18- [x] Contains Number, Currency, Accounting and Percent formatting functions
19- [x] Supports the "Gregorian" calendar only ( my time isn't unlimited, had to draw the line somewhere )
20
21Full Tests
22--------------------
23I could sure use your help adding tests for every locale, it is a huge undertaking and I just don't have the free time to do it all at the moment;
24any help would be **greatly appreciated!!!!** please see [issue](https://github.com/go-playground/locales/issues/1) for details.
25
26Installation
27-----------
28
29Use go get
30
31```shell
32go get github.com/go-playground/locales
33```
34
35NOTES
36--------
37You'll notice most return types are []byte, this is because most of the time the results will be concatenated with a larger body
38of text and can avoid some allocations if already appending to a byte array, otherwise just cast as string.
39
40Usage
41-------
42```go
43package main
44
45import (
46 "fmt"
47 "time"
48
49 "github.com/go-playground/locales/currency"
50 "github.com/go-playground/locales/en_CA"
51)
52
53func main() {
54
55 loc, _ := time.LoadLocation("America/Toronto")
56 datetime := time.Date(2016, 02, 03, 9, 0, 1, 0, loc)
57
58 l := en_CA.New()
59
60 // Dates
61 fmt.Println(l.FmtDateFull(datetime))
62 fmt.Println(l.FmtDateLong(datetime))
63 fmt.Println(l.FmtDateMedium(datetime))
64 fmt.Println(l.FmtDateShort(datetime))
65
66 // Times
67 fmt.Println(l.FmtTimeFull(datetime))
68 fmt.Println(l.FmtTimeLong(datetime))
69 fmt.Println(l.FmtTimeMedium(datetime))
70 fmt.Println(l.FmtTimeShort(datetime))
71
72 // Months Wide
73 fmt.Println(l.MonthWide(time.January))
74 fmt.Println(l.MonthWide(time.February))
75 fmt.Println(l.MonthWide(time.March))
76 // ...
77
78 // Months Abbreviated
79 fmt.Println(l.MonthAbbreviated(time.January))
80 fmt.Println(l.MonthAbbreviated(time.February))
81 fmt.Println(l.MonthAbbreviated(time.March))
82 // ...
83
84 // Months Narrow
85 fmt.Println(l.MonthNarrow(time.January))
86 fmt.Println(l.MonthNarrow(time.February))
87 fmt.Println(l.MonthNarrow(time.March))
88 // ...
89
90 // Weekdays Wide
91 fmt.Println(l.WeekdayWide(time.Sunday))
92 fmt.Println(l.WeekdayWide(time.Monday))
93 fmt.Println(l.WeekdayWide(time.Tuesday))
94 // ...
95
96 // Weekdays Abbreviated
97 fmt.Println(l.WeekdayAbbreviated(time.Sunday))
98 fmt.Println(l.WeekdayAbbreviated(time.Monday))
99 fmt.Println(l.WeekdayAbbreviated(time.Tuesday))
100 // ...
101
102 // Weekdays Short
103 fmt.Println(l.WeekdayShort(time.Sunday))
104 fmt.Println(l.WeekdayShort(time.Monday))
105 fmt.Println(l.WeekdayShort(time.Tuesday))
106 // ...
107
108 // Weekdays Narrow
109 fmt.Println(l.WeekdayNarrow(time.Sunday))
110 fmt.Println(l.WeekdayNarrow(time.Monday))
111 fmt.Println(l.WeekdayNarrow(time.Tuesday))
112 // ...
113
114 var f64 float64
115
116 f64 = -10356.4523
117
118 // Number
119 fmt.Println(l.FmtNumber(f64, 2))
120
121 // Currency
122 fmt.Println(l.FmtCurrency(f64, 2, currency.CAD))
123 fmt.Println(l.FmtCurrency(f64, 2, currency.USD))
124
125 // Accounting
126 fmt.Println(l.FmtAccounting(f64, 2, currency.CAD))
127 fmt.Println(l.FmtAccounting(f64, 2, currency.USD))
128
129 f64 = 78.12
130
131 // Percent
132 fmt.Println(l.FmtPercent(f64, 0))
133
134 // Plural Rules for locale, so you know what rules you must cover
135 fmt.Println(l.PluralsCardinal())
136 fmt.Println(l.PluralsOrdinal())
137
138 // Cardinal Plural Rules
139 fmt.Println(l.CardinalPluralRule(1, 0))
140 fmt.Println(l.CardinalPluralRule(1.0, 0))
141 fmt.Println(l.CardinalPluralRule(1.0, 1))
142 fmt.Println(l.CardinalPluralRule(3, 0))
143
144 // Ordinal Plural Rules
145 fmt.Println(l.OrdinalPluralRule(21, 0)) // 21st
146 fmt.Println(l.OrdinalPluralRule(22, 0)) // 22nd
147 fmt.Println(l.OrdinalPluralRule(33, 0)) // 33rd
148 fmt.Println(l.OrdinalPluralRule(34, 0)) // 34th
149
150 // Range Plural Rules
151 fmt.Println(l.RangePluralRule(1, 0, 1, 0)) // 1-1
152 fmt.Println(l.RangePluralRule(1, 0, 2, 0)) // 1-2
153 fmt.Println(l.RangePluralRule(5, 0, 8, 0)) // 5-8
154}
155```
156
157NOTES:
158-------
159These rules were generated from the [Unicode CLDR Project](http://cldr.unicode.org/), if you encounter any issues
160I strongly encourage contributing to the CLDR project to get the locale information corrected and the next time
161these locales are regenerated the fix will come with.
162
163I do however realize that time constraints are often important and so there are two options:
164
1651. Create your own locale, copy, paste and modify, and ensure it complies with the `Translator` interface.
1662. Add an exception in the locale generation code directly and once regenerated, fix will be in place.
167
168Please to not make fixes inside the locale files, they WILL get overwritten when the locales are regenerated.
169
170License
171------
172Distributed under MIT License, please see license file in code for more details.
173
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}