vendor/github.com/go-playground/universal-translator/README.md

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