wut

README

= Wut - A simple i18n pack

== Disclaimer

This library is a work-in-progress, and definitely not ready for production. Anything can chance, tests need improvement and there are still no benchmarks.

This library's aim is to have a simple to use and upkeep i18n library. If possible, I'll try to prepare integrations with any popular validation frameworks and whatever else looks to be useful.

== Install

[source,bash]
go get github.com/borislav-rangelov/wut

== Usage

Firstly, prepare some translations
[source,toml]
----
# resources/i18n/en.toml
language = "en"

[display]
hello = "Hello"
hello_name = 'Hello, {{ .Name }}' # standard text/template format
----

[source,toml]
----
# resources/i18n/es.toml
language = "es"
fallback = "en"

[display]
hello = "Hola"
hello_template = '{{ get "display.hello" }}, {{ .Name }}' #Keep in mind that 'get' will use the language of the template it was being used in as the starting one and needs the default lang factory to be set up.
----

Then, use the `wut.Setup()` builder to configure the library (easiest approach).

[source,go]
--
package main

import (
    "fmt"
    "github.com/borislav-rangelov/wut"
)

type User struct{
	Name string
}

func main() {
    err := wut.Setup().
	    AddFiles("resources/i18n/en.toml",
			"resources/i18n/es.toml").
		AsDefault()

	if err != nil {
		panic(err)
	}

	english := wut.Lang("en")
	spanish := wut.Lang("es")

	// "Hello"
	fmt.Println(english.Get("display.hello").Txt)
	// "Hola"
	fmt.Println(spanish.Get("display.hello").Txt)

	msg := english.Get("display.bye")
	// ""
	fmt.Println(msg.Txt)
	// "Bye"
	fmt.Println(msg.Or("Bye"))

	user := User{Name: "Wut"}
	templatedMsg := english.Get("display.hello_name", user)

	// "Hello, Wut"
	fmt.Println(templatedMsg.Txt)
}
--

Easiest config is to use `wut.Setup().AsDefault()` in the main application.
When testing, you can use `wut.SetDefaultFactory()` to prepare something for the test. If I have the time, I'll try to make a version, which is easier to test with.

If there are issues, pass in the `LangFactory`, or `LangSource` to the specific methods.

Documentation

Index

• Variables
• func SetDefaultFactory(f LangFactory)
• type ConfigMap
• type DefaultTemplateFactory
  • func (f *DefaultTemplateFactory) GetTemplate(lang string, path []string, entry string) (Template, error)
• type KeyConfig
• type LangFactory
  • func NewLangFactory(tf TemplateFactory, files ...*LangFile) (LangFactory, error)
• type LangFile
  • func ReadFile(filename string) (*LangFile, error)
  • func ValuesToLangFile(values Values) *LangFile
  • func (l *LangFile) Include(other *LangFile) error
• type LangSource
  • func Lang(code string) LangSource
• type LoadOptions
  • func Setup() LoadOptions
• type LookupSource
  • func NewLookupSource(parent LangSource, configs ConfigMap) *LookupSource
  • func (l *LookupSource) Get(key string, ctx ...any) *Result
  • func (l *LookupSource) GetFirst(keys []string, ctx ...any) *Result
  • func (l *LookupSource) Msg(m *Message) *Result
• type Message
  • func Msg(key string, ctx ...any) *Message
• type Result
  • func (r *Result) HasError() bool
  • func (r *Result) HasTxt() bool
  • func (r *Result) Key() string
  • func (r *Result) Or(other string) string
  • func (r *Result) OrErr() (string, error)
• type Template
• type TemplateFactory
• type Values

Variables

var ErrTranslationNotFound = errors.New("translation not found")

Functions

func SetDefaultFactory

func SetDefaultFactory(f LangFactory)

Types

type ConfigMap

type ConfigMap map[string]*KeyConfig

type DefaultTemplateFactory

type DefaultTemplateFactory struct{}

DefaultTemplateFactory - provides `text/template` templates if it detects a placeholder, or directly returns the string from the config

func (*DefaultTemplateFactory) GetTemplate

func (f *DefaultTemplateFactory) GetTemplate(lang string, path []string, entry string) (Template, error)

type KeyConfig

type KeyConfig struct {
	Configs  ConfigMap
	Template Template
}

type LangFactory

type LangFactory interface {
	Lang(code string) LangSource
}

func NewLangFactory

func NewLangFactory(tf TemplateFactory, files ...*LangFile) (LangFactory, error)

type LangFile

type LangFile struct {
	Language string
	Fallback string
	Values   Values
}

func ReadFile

func ReadFile(filename string) (*LangFile, error)

ReadFile opens the file and reads the config from it. Supported types: toml

func ValuesToLangFile

func ValuesToLangFile(values Values) *LangFile

func (*LangFile) Include

func (l *LangFile) Include(other *LangFile) error

type LangSource

type LangSource interface {
	Get(key string, ctx ...any) *Result
	GetFirst(key []string, ctx ...any) *Result
	Msg(*Message) *Result
}

LangSource searches for a translation to the given key

func Lang

func Lang(code string) LangSource

type LoadOptions

type LoadOptions interface {

	// TemplateFactory sets which factory will provide the templates
	// that will be returned in the end. Default is DefaultTemplateFactory
	TemplateFactory(tf TemplateFactory) LoadOptions

	// AddFiles accepts a list of files to be parsed.
	// They need to at least have the language property defined in them.
	// If adding multiple files for the same language, their fallback language MUST match.
	// The 'language' and 'fallback' settings could be moved to a separate file in the future.
	AddFiles(file ...string) LoadOptions

	// AsDefault sets the configured factory from Build as the default factory to be used by the global methods available
	AsDefault() error

	// Build configures and returns the lang factory
	Build() (LangFactory, error)
}

func Setup

func Setup() LoadOptions

type LookupSource

type LookupSource struct {
	// contains filtered or unexported fields
}

func NewLookupSource

func NewLookupSource(parent LangSource, configs ConfigMap) *LookupSource

func (*LookupSource) Get

func (l *LookupSource) Get(key string, ctx ...any) *Result

func (*LookupSource) GetFirst

func (l *LookupSource) GetFirst(keys []string, ctx ...any) *Result

func (*LookupSource) Msg

func (l *LookupSource) Msg(m *Message) *Result

type Message

type Message struct {
	Key        []string
	NoFallback bool
	Context    any
}

func Msg

func Msg(key string, ctx ...any) *Message

type Result

type Result struct {
	Msg *Message
	Txt string
	Err error
}

func (*Result) HasError

func (r *Result) HasError() bool

func (*Result) HasTxt

func (r *Result) HasTxt() bool

func (*Result) Key

func (r *Result) Key() string

func (*Result) Or

func (r *Result) Or(other string) string

func (*Result) OrErr

func (r *Result) OrErr() (string, error)

type Template

type Template func(ctx any) (string, error)

Template transforms the given context into a string

type TemplateFactory

type TemplateFactory interface {
	// GetTemplate - provides the template
	GetTemplate(lang string, path []string, entry string) (Template, error)
}

TemplateFactory provides templates based on the lang, key and value in the config This allows setting custom template resolving when needed

type Values

type Values map[string]any