1## universal-translator
2<img align="right" src="https://raw.githubusercontent.com/go-playground/universal-translator/master/logo.png">
3[](https://coveralls.io/github/go-playground/universal-translator)
4[](https://goreportcard.com/report/github.com/go-playground/universal-translator)
5[](https://godoc.org/github.com/go-playground/universal-translator)
6
7
8Universal Translator is an i18n Translator for Go/Golang using CLDR data + pluralization rules
9
10Why another i18n library?
11--------------------------
12Because none of the plural rules seem to be correct out there, including the previous implementation of this package,
13so I took it upon myself to create [locales](https://github.com/go-playground/locales) for everyone to use; this package
14is a thin wrapper around [locales](https://github.com/go-playground/locales) in order to store and translate text for
15use in your applications.
16
17Features
18--------
19- [x] Rules generated from the [CLDR](http://cldr.unicode.org/index/downloads) data, v36.0.1
20- [x] Contains Cardinal, Ordinal and Range Plural Rules
21- [x] Contains Month, Weekday and Timezone translations built in
22- [x] Contains Date & Time formatting functions
23- [x] Contains Number, Currency, Accounting and Percent formatting functions
24- [x] Supports the "Gregorian" calendar only ( my time isn't unlimited, had to draw the line somewhere )
25- [x] Support loading translations from files
26- [x] Exporting translations to file(s), mainly for getting them professionally translated
27- [ ] Code Generation for translation files -> Go code.. i.e. after it has been professionally translated
28- [ ] Tests for all languages, I need help with this, please see [here](https://github.com/go-playground/locales/issues/1)
29
30Installation
31-----------
32
33Use go get
34
35```shell
36go get github.com/go-playground/universal-translator
37```
38
39Usage & Documentation
40-------
41
42Please see https://godoc.org/github.com/go-playground/universal-translator for usage docs
43
44##### Examples:
45
46- [Basic](https://github.com/go-playground/universal-translator/tree/master/_examples/basic)
47- [Full - no files](https://github.com/go-playground/universal-translator/tree/master/_examples/full-no-files)
48- [Full - with files](https://github.com/go-playground/universal-translator/tree/master/_examples/full-with-files)
49
50File formatting
51--------------
52All types, Plain substitution, Cardinal, Ordinal and Range translations can all be contained within the same file(s);
53they are only separated for easy viewing.
54
55##### Examples:
56
57- [Formats](https://github.com/go-playground/universal-translator/tree/master/_examples/file-formats)
58
59##### Basic Makeup
60NOTE: not all fields are needed for all translation types, see [examples](https://github.com/go-playground/universal-translator/tree/master/_examples/file-formats)
61```json
62{
63 "locale": "en",
64 "key": "days-left",
65 "trans": "You have {0} day left.",
66 "type": "Cardinal",
67 "rule": "One",
68 "override": false
69}
70```
71|Field|Description|
72|---|---|
73|locale|The locale for which the translation is for.|
74|key|The translation key that will be used to store and lookup each translation; normally it is a string or integer.|
75|trans|The actual translation text.|
76|type|The type of translation Cardinal, Ordinal, Range or "" for a plain substitution(not required to be defined if plain used)|
77|rule|The plural rule for which the translation is for eg. One, Two, Few, Many or Other.(not required to be defined if plain used)|
78|override|If you wish to override an existing translation that has already been registered, set this to 'true'. 99% of the time there is no need to define it.|
79
80Help With Tests
81---------------
82To anyone interesting in helping or contributing, I sure could use some help creating tests for each language.
83Please see issue [here](https://github.com/go-playground/locales/issues/1) for details.
84
85License
86------
87Distributed under MIT License, please see license file in code for more details.
View as plain text