Merge pull request #12 from go-playground/file-import-export

Add File Import/Export logic

Author: Dean Karn

.gitignore

@@ -21,4 +21,4 @@ _testmain.go
 
 *.exe
 *.test
-*.prof
+*.prof

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Go Experimental
+Copyright (c) 2016 Go Playground
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,6 +1,6 @@
 ## universal-translator
 <img align="right" src="https://raw.githubusercontent.com/go-playground/universal-translator/master/logo.png">
-![Project status](https://img.shields.io/badge/version-0.14.0-green.svg)
+![Project status](https://img.shields.io/badge/version-0.15.0-green.svg)
 [![Build Status](https://semaphoreci.com/api/v1/joeybloggs/universal-translator/branches/master/badge.svg)](https://semaphoreci.com/joeybloggs/universal-translator)
 [![Coverage Status](https://coveralls.io/repos/github/go-playground/universal-translator/badge.svg)](https://coveralls.io/github/go-playground/universal-translator)
 [![Go Report Card](https://goreportcard.com/badge/github.com/go-playground/universal-translator)](https://goreportcard.com/report/github.com/go-playground/universal-translator)
@@ -25,8 +25,8 @@ Features
 - [x] Contains Date & Time formatting functions
 - [x] Contains Number, Currency, Accounting and Percent formatting functions
 - [x] Supports the "Gregorian" calendar only ( my time isn't unlimited, had to draw the line somewhere )
-- [ ] Support loading translations from files
-- [ ] Exporting translations to file, mainly for getting them professionally translated
+- [x] Support loading translations from files
+- [x] Exporting translations to file(s), mainly for getting them professionally translated
 - [ ] Code Generation for translation files -> Go code.. i.e. after it has been professionally translated
 - [ ] Tests for all languages, I need help with this, please see [here](https://github.com/go-playground/locales/issues/1)
 
@@ -35,84 +35,50 @@ Installation
 
 Use go get 
 
-```go
+```shell
 go get github.com/go-playground/universal-translator
 ```
 
-Usage
+Usage & Documentation
 -------
-```go
-package main
 
-import (
-	"fmt"
+Please see https://godoc.org/github.com/go-playground/universal-translator for usage docs
 
-	"github.com/go-playground/locales"
-	"github.com/go-playground/locales/en"
-	"github.com/go-playground/locales/en_CA"
-	"github.com/go-playground/locales/fr"
-	"github.com/go-playground/locales/nl"
-	"github.com/go-playground/universal-translator"
-)
+##### Examples:
 
-// only one instance as translators within are shared + goroutine safe
-var universalTraslator *ut.UniversalTranslator
+- [Basic](https://github.com/go-playground/universal-translator/tree/master/examples/basic)
+- [Full - no files](https://github.com/go-playground/universal-translator/tree/master/examples/full-no-files)
+- [Full - with files](https://github.com/go-playground/universal-translator/tree/master/examples/full-with-files)
 
-func main() {
+File formatting
+--------------
+All types, Plain substitution, Cardinal, Ordinal and Range translations can all be contained withing the same file(s);
+they are only separated for easy viewing.
 
-	// NOTE: this example is omitting a lot of error checking for brevity
-	e := en.New()
-	universalTraslator = ut.New(e, e, en_CA.New(), nl.New(), fr.New())
+##### Examples:
 
-	en, _ := universalTraslator.GetTranslator("en")
+- [Formats](https://github.com/go-playground/universal-translator/tree/master/examples/file-formats)
 
-	// generally used after parsing an http 'Accept-Language' header
-	// and this will try to find a matching locale you support or
-	// fallback locale.
-	// en, _ := ut.FindTranslator([]string{"en", "en_CA", "nl"})
-
-	// this will help
-	fmt.Println("Cardinal Plural Rules:", en.PluralsCardinal())
-	fmt.Println("Ordinal Plural Rules:", en.PluralsOrdinal())
-	fmt.Println("Range Plural Rules:", en.PluralsRange())
-
-	// add basic language only translations
-	// last param indicates if it's ok to override the translation if one already exists
-	en.Add("welcome", "Welcome {0} to our test", false)
-
-	// add language translations dependant on cardinal plural rules
-	en.AddCardinal("days", "You have {0} day left to register", locales.PluralRuleOne, false)
-	en.AddCardinal("days", "You have {0} days left to register", locales.PluralRuleOther, false)
-
-	// add language translations dependant on ordinal plural rules
-	en.AddOrdinal("day-of-month", "{0}st", locales.PluralRuleOne, false)
-	en.AddOrdinal("day-of-month", "{0}nd", locales.PluralRuleTwo, false)
-	en.AddOrdinal("day-of-month", "{0}rd", locales.PluralRuleFew, false)
-	en.AddOrdinal("day-of-month", "{0}th", locales.PluralRuleOther, false)
-
-	// add language translations dependant on range plural rules
-	// NOTE: only one plural rule for range in 'en' locale
-	en.AddRange("between", "It's {0}-{1} days away", locales.PluralRuleOther, false)
-
-	// now lets use the translations we just added, in the same order we added them
-
-	fmt.Println(en.T("welcome", "Joeybloggs"))
-
-	fmt.Println(en.C("days", 1, 0, en.FmtNumber(1, 0))) // you'd normally have variables defined for 1 and 0
-	fmt.Println(en.C("days", 2, 0, en.FmtNumber(2, 0)))
-	fmt.Println(en.C("days", 10456.25, 2, en.FmtNumber(10456.25, 2)))
-
-	fmt.Println(en.O("day-of-month", 1, 0, en.FmtNumber(1, 0)))
-	fmt.Println(en.O("day-of-month", 2, 0, en.FmtNumber(2, 0)))
-	fmt.Println(en.O("day-of-month", 3, 0, en.FmtNumber(3, 0)))
-	fmt.Println(en.O("day-of-month", 4, 0, en.FmtNumber(4, 0)))
-	fmt.Println(en.O("day-of-month", 10456.25, 0, en.FmtNumber(10456.25, 0)))
-
-	fmt.Println(en.R("between", 0, 0, 1, 0, en.FmtNumber(0, 0), en.FmtNumber(1, 0)))
-	fmt.Println(en.R("between", 1, 0, 2, 0, en.FmtNumber(1, 0), en.FmtNumber(2, 0)))
-	fmt.Println(en.R("between", 1, 0, 100, 0, en.FmtNumber(1, 0), en.FmtNumber(100, 0)))
+##### Basic Makeup
+NOTE: not all fields are needed for all translation types, see [examples](https://github.com/go-playground/universal-translator/tree/master/examples/file-formats)
+```json
+{
+    "locale": "en",
+    "key": "days-left",
+    "trans": "You have {0} day left.",
+    "type": "Cardinal",
+    "rule": "One",
+    "override": false
 }
 ```
+|Field|Description|
+|---|---|
+|locale|The locale for which the translation is for.|
+|key|The translation key that will be used to store and lookup each translation; normally it is a string or integer.|
+|trans|The actual translation text.|
+|type|The type of translation Cardinal, Ordinal, Range or "" for a plain substitution(not required to be defined if plain used)|
+|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)|
+|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.|
 
 Help With Tests
 ---------------

errors.go

@@ -31,19 +31,20 @@ func (e *ErrExistingTranslator) Error() string {
 
 // ErrConflictingTranslation is the error representing a conflicting translation
 type ErrConflictingTranslation struct {
-	key  interface{}
-	rule locales.PluralRule
-	text string
+	locale string
+	key    interface{}
+	rule   locales.PluralRule
+	text   string
 }
 
 // Error returns ErrConflictingTranslation's internal error text
 func (e *ErrConflictingTranslation) Error() string {
 
 	if _, ok := e.key.(string); !ok {
-		return fmt.Sprintf("error: conflicting key '%#v' rule '%s' with text '%s', value being ignored", e.key, e.rule, e.text)
+		return fmt.Sprintf("error: conflicting key '%#v' rule '%s' with text '%s' for locale '%s', value being ignored", e.key, e.rule, e.text, e.locale)
 	}
 
-	return fmt.Sprintf("error: conflicting key '%s' rule '%s' with text '%s', value being ignored", e.key, e.rule, e.text)
+	return fmt.Sprintf("error: conflicting key '%s' rule '%s' with text '%s' for locale '%s', value being ignored", e.key, e.rule, e.text, e.locale)
 }
 
 // ErrRangeTranslation is the error representing a range translation error
@@ -79,6 +80,7 @@ func (e *ErrCardinalTranslation) Error() string {
 // ErrMissingPluralTranslation is the error signifying a missing translation given
 // the locales plural rules.
 type ErrMissingPluralTranslation struct {
+	locale          string
 	key             interface{}
 	rule            locales.PluralRule
 	translationType string
@@ -88,8 +90,59 @@ type ErrMissingPluralTranslation struct {
 func (e *ErrMissingPluralTranslation) Error() string {
 
 	if _, ok := e.key.(string); !ok {
-		return fmt.Sprintf("error: missing '%s' plural rule '%s' for translation with key '%#v'", e.translationType, e.rule, e.key)
+		return fmt.Sprintf("error: missing '%s' plural rule '%s' for translation with key '%#v' and locale '%s'", e.translationType, e.rule, e.key, e.locale)
 	}
 
-	return fmt.Sprintf("error: missing '%s' plural rule '%s' for translation with key '%s'", e.translationType, e.rule, e.key)
+	return fmt.Sprintf("error: missing '%s' plural rule '%s' for translation with key '%s' and locale '%s'", e.translationType, e.rule, e.key, e.locale)
+}
+
+// ErrMissingBracket is the error representing a missing bracket in a translation
+// eg. This is a {0 <-- missing ending '}'
+type ErrMissingBracket struct {
+	locale string
+	key    interface{}
+	text   string
+}
+
+// Error returns ErrMissingBracket error message
+func (e *ErrMissingBracket) Error() string {
+	return fmt.Sprintf("error: missing bracket '{}', in translation. locale: '%s' key: '%v' text: '%s'", e.locale, e.key, e.text)
+}
+
+// ErrBadParamSyntax is the error representing a bad parameter definition in a translation
+// eg. This is a {must-be-int}
+type ErrBadParamSyntax struct {
+	locale string
+	param  string
+	key    interface{}
+	text   string
+}
+
+// Error returns ErrBadParamSyntax error message
+func (e *ErrBadParamSyntax) Error() string {
+	return fmt.Sprintf("error: bad parameter syntax, missing parameter '%s' in translation. locale: '%s' key: '%v' text: '%s'", e.param, e.locale, e.key, e.text)
+}
+
+// import/export errors
+
+// ErrMissingLocale is the error representing an expected locale that could
+// not be found aka locale not registered with the UniversalTranslator Instance
+type ErrMissingLocale struct {
+	locale string
+}
+
+// Error returns ErrMissingLocale's internal error text
+func (e *ErrMissingLocale) Error() string {
+	return fmt.Sprintf("error: locale '%s' not registered.", e.locale)
+}
+
+// ErrBadPluralDefinition is the error representing an incorrect plural definition
+// usually found within translations defined within files during the import process.
+type ErrBadPluralDefinition struct {
+	tl translation
+}
+
+// Error returns ErrBadPluralDefinition's internal error text
+func (e *ErrBadPluralDefinition) Error() string {
+	return fmt.Sprintf("error: bad plural definition '%#v'", e.tl)
 }

examples/file-formats/cardinal.json

@@ -0,0 +1,16 @@
+[
+    {
+        "locale": "en",
+        "key": "cardinal_test",
+        "trans": "You have {0} day left.",
+        "type": "Cardinal",
+        "rule": "One"
+    },
+    {
+        "locale": "en",
+        "key": "cardinal_test",
+        "trans": "You have {0} days left.",
+        "type": "Cardinal",
+        "rule": "Other"
+    }
+]

examples/file-formats/ordinal.json

@@ -0,0 +1,30 @@
+[
+    {
+        "locale": "en",
+        "key": "day",
+        "trans": "{0}st",
+        "type": "Ordinal",
+        "rule": "One"
+    },
+    {
+        "locale": "en",
+        "key": "day",
+        "trans": "{0}nd",
+        "type": "Ordinal",
+        "rule": "Two"
+    },
+    {
+        "locale": "en",
+        "key": "day",
+        "trans": "{0}rd",
+        "type": "Ordinal",
+        "rule": "Few"
+    },
+    {
+        "locale": "en",
+        "key": "day",
+        "trans": "{0}th",
+        "type": "Ordinal",
+        "rule": "Other"
+    }
+]

examples/file-formats/plain-substitution.json

@@ -0,0 +1,27 @@
+[
+    {
+        "locale": "en",
+        "key": "test_trans4",
+        "trans": "{0}{1}"
+    },
+    {
+        "locale": "en",
+        "key": "test_trans",
+        "trans": "Welcome {0} to the {1}."
+    },
+    {
+        "locale": "en",
+        "key": -1,
+        "trans": "Welcome {0}"
+    },
+    {
+        "locale": "en",
+        "key": "test_trans2",
+        "trans": "{0} to the {1}."
+    },
+    {
+        "locale": "en",
+        "key": "test_trans3",
+        "trans": "Welcome {0} to the {1}"
+    }
+]

examples/file-formats/range.json

@@ -0,0 +1,16 @@
+[
+    {
+        "locale": "nl",
+        "key": "day",
+        "trans": "er {0}-{1} dag vertrokken",
+        "type": "Range",
+        "rule": "One"
+    },
+    {
+        "locale": "nl",
+        "key": "day",
+        "trans": "er zijn {0}-{1} dagen over",
+        "type": "Range",
+        "rule": "Other"
+    }
+]

examples/full-no-files/home.tmpl

@@ -0,0 +1,35 @@
+{{ define "home" }}
+<!DOCTYPE html>
+<html>
+	<head>
+		<title>Home</title>
+	</head>
+	<body>
+		<p>Locale: {{ .Trans.Locale }}</p>
+        <p>Trans1: {{ .Trans.C "days-left" 1 0 "1" }}</p>
+        <p>Trans2: {{ .Trans.C "days-left" 2 0 "2" }}</p>
+        <p>FmtNumber Positive: {{ .Trans.FmtNumber .PositiveNum 2 }}</p>
+        <p>FmtNumber Negative: {{ .Trans.FmtNumber .NegativeNum 2 }}</p>
+        <p>FmtPercent Negative: {{ .Trans.FmtPercent .Percent 2 }}</p>
+        <p>FmtCurrency Negative: {{ .Trans.FmtCurrency .PositiveNum 2 .Trans.Currency }}</p>
+        <p>FmtCurrency Negative: {{ .Trans.FmtCurrency .NegativeNum 2 .Trans.Currency }}</p>
+        <p>FmtAccounting Negative: {{ .Trans.FmtAccounting .PositiveNum 2 .Trans.Currency }}</p>
+        <p>FmtAccounting Negative: {{ .Trans.FmtAccounting .NegativeNum 2 .Trans.Currency }}</p>
+        <p>FmtDateShort: {{ .Trans.FmtDateShort .Now }}</p>
+        <p>FmtDateMedium: {{ .Trans.FmtDateMedium .Now }}</p>
+        <p>FmtDateLong: {{ .Trans.FmtDateLong .Now }}</p>
+        <p>FmtDateFull: {{ .Trans.FmtDateFull .Now }}</p>
+        <p>FmtTimeShort: {{ .Trans.FmtTimeShort .Now }}</p>
+        <p>FmtTimeMedium: {{ .Trans.FmtTimeMedium .Now }}</p>
+        <p>FmtTimeLong: {{ .Trans.FmtTimeLong .Now }}</p>
+        <p>FmtTimeFull: {{ .Trans.FmtTimeFull .Now }}</p>
+        <p>MonthsAbbreviated: {{ .Trans.MonthsAbbreviated }}</p>
+        <p>MonthsNarrow: {{ .Trans.MonthsNarrow }}</p>
+        <p>MonthsWide: {{ .Trans.MonthsWide }}</p>
+        <p>WeekdaysAbbreviated: {{ .Trans.WeekdaysAbbreviated }}</p>
+        <p>WeekdaysNarrow: {{ .Trans.WeekdaysNarrow }}</p>
+        <p>WeekdaysShort: {{ .Trans.WeekdaysShort }}</p>
+        <p>WeekdaysWide: {{ .Trans.WeekdaysWide }}</p>
+	</body>
+</html>
+{{ end }}