lpax

Strong keyed string repository supporting internationalisation and separation of text definition from usage.

• Installation
• Features
• Contributing
• License

Status

Installation

To add lpax to a project run:

go get github.com/nehemming/cirocket@latest

lpax supports modules.

Features

Applications and library packages typically embed string and error messages within the code. Placing strings inline within the code can make it harder to internationalise the code or to extract a list of all error messages generated by an application. lpax provides method of registering strings that can be accessed via decentralised keys. The key system uses Go's strong typing to allow each package to create its own key system without risking overlapping with other packages keys. multiple languages can be supported for key, with fallback logic to us the default english language.

• String registration is implemented via the Registry interface. Packages can use their own registry instance but in most cases will use the shared Default registry.
• Strongly typed keys (TextID's) ensure each package has isolated keys. Keys may be of int, uint, string or struct kinds.
• Keys may be registered in multiple languages, allowing localized versions of the text to be used within an application.
• Single and plural versions of a text message can be stored.
• Applications can register overrides for messages registered by a package using the priority parameter of Register
• Attach a TextFinder instance to a context, allowing different contexts to operate in different languages.
• Helper Sprintf and Errorf functions supporting TextID implemented.

Typical implementation

Packages / applications wishing to use lpax will typically implement their own sub package containing the messages, or load them from an external source.

The example pack_example_test.go source shows a typical language package implementation.

It creates package PackID and TextID types (used as the package unique id amd message keys respectively) and registers the messages against the default registry using the init function.

type (
	// PackID is the local package id.
	// Each package should implement its own PackID type.
	// They are typically derived from the `int` type.
	PackID int

	// TextID is the id type for all messages defined by this package.
	// the TextID type must implement the lpax.TextID interface, but is typically
	// based on a `int` type.  As the package defines its own TextID it is
	// unique from other package types, and thus so are the ids.
	TextID int
)

var pack = lpax.TextMap{
	Hello:  "Hello World",
	-Hello: "Hello Worlds",
}

// register is the text registry callback function used to return the text mappings.
func register(packID lpax.PackID, langTag lpax.Tag) lpax.TextMap {
	return pack
}

func init() {
	// register the text mappings with the share test registry.
	lpax.Default().Register(ExamplePackID, register, lpax.DefaultPriority, language.English)
}

Users of the messages can then use the lpax Sprintf, CtxSprintf, Errorf or CtxErrorf methods to output the messages.

func Example() {
	fmt.Println(lpax.Sprintf(Hello))
	fmt.Println(lpax.Sprintf(Hello.Plural()))

	// Output:
	// Hello World
	// Hello Worlds
}

Messages can also be retrieved by calling Default().Text(id)

Contributing

We would welcome contributions to this project. Please read our CONTRIBUTION file for further details on how you can participate or report any issues.

License

This software is licensed under the Apache License.