Version: v0.17.2 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Jul 28, 2021 License: MIT Imports: 6 Imported by: 0



The i18n package provides support services for translation of goradd web pages and widgets.

Overview Internationalization is a complex beast. Beyond all the previous attempts at doing it, GO is actively developing the golang.org/x/text library to provide additional translation and internationalization support.

This new GO library is unfortunately a bit opinionated. It provides an extractor that searches for strings in your application and dumps them to a json file ready for translation. However, it will only look for strings that are being processed by the message.Sprintf and similar functions. It does some code analysis to extract the strings in ways that provide additional information to translators and the reassembly process, which is great, but a bit limited.

This 18n package works with the page.control.T() and similar functions to try to provide some GO like functionality in a less opinionated way.

Translators At the top level are the translators, which are contained in a global map of TranslatorI interfaces that implement the Translate function. These translators are keyed by a domain name, not an http domain name, but a domain borrowed from the historical gettext process. It simply lets you specify different translators for different strings, and it is primarily useful by allowing libraries and the goradd core to provide their own translations and translators of their own string. Also, you can replace those and provide your own translations of these same strings if you want. Library makers, and the goradd framework, simply need to register their translators during their own package initialization, and you can replace those during the local application package initialization process.

As far as implementing translation for your own application, you can either do it the GO way using the message.Printer functionality provided by golang.org/x/text/message (see https://godoc.org/golang.org/x/text for details and a reference to a very helpful youtube video on the subject), or you can use goradd's translator service.

Goradd Translation To send a string to your application translator, simply call T("message") on any control or form, and it will return the translation. You can add some annotations by adding an i18n.ID() call or i18n.Comment() call to the call, like so:

newMessage := ctrl.T("my message", i18n.ID("Use this ID for additional context"), i18n.Comment("This can become an extracted comment))

The code generated forms and controls automatically call this function to translate strings.

The extractor for this is not yet built, but it should not be too hard, as a great example is already in the go/text library.

Since translation is provided by an interface, you can handle translation however you want by simply creating an object that implements the TranslateI interface, and then passing it to RegisterTranslator with the GoraddProject domain. There are a huge variety of libraries available for managing translations with .po files, with online utilities like Google's own Translation Toolkit, with databases, static linking, etc. Its up to you.

You can see examples of how the framework itself does it in the source.



View Source
const GoraddDomain = "goradd"

Predefined domains. Plugins can add their own domains.

View Source
const ProjectDomain = "project"


This section is empty.


func Build

func Build() *translationBuilder

Build returns a new translation builder.

func CanonicalValue

func CanonicalValue(i int) string

CanonicalValue will return the canonical value of the language at the given position

func Comment

func Comment(c string) interface{}

Comment adds a comment to the translation. It is used in extracted files, but does not impact the translator.

func CurrentLanguage

func CurrentLanguage(ctx context.Context) (int, string)

CurrentLanguage returns the ordinal value of the current language, and the canonical value If the language setting is not yet set, it returns the default language

func CurrentLanguageAttribute

func CurrentLanguageAttribute(ctx context.Context) string

func ExtractBuilderFromArguments

func ExtractBuilderFromArguments(args []interface{}) (b *translationBuilder, args2 []interface{})

ExtractBuilderFromArguments will return a new builder, but also will extract any builder-specific commands from the argmument list, assign those to the builder, and then return what is left of the arguments after the extraction.

func ID

func ID(i string) interface{}

ID is a parameter you can add to the page.control.T() function to specify a message id. Usually the message id is the same as the string being translated, but when multiple strings are translated that are the same but have different meaning, this will be required. This is used as the msgctxt value in PO files, and is combined with the message to make a composite id in golang translation files. Adding a comment is helpful in these situations.

func RegisterTranslator

func RegisterTranslator(domain string, t TranslatorI)

RegisterTranslator sets the translation service for the given domain to the given translator

func SetDefaultLanguage

func SetDefaultLanguage(ctx context.Context, acceptLanguageValue string) int

SetDefaultLanguage is called by the framework to set up the session variable with a default language if one has not yet been set. The default language is based on the "accept-language" header value and the list of languages that the application supports.

func SetLanguage

func SetLanguage(ctx context.Context, i int)

Call SetLanguage to set the user's language to a specific language from the list of supported languages.

func SetSupportedLanguages

func SetSupportedLanguages(l ...ServerLanguageEntry)

SetSupportedLanguages sets up the languages that the application supports. It expects both a list of language tags and a matching list of dictionaries. You should only call this during application startup to inject your list of supported languages into the application.

func Tag

func Tag(i int) language.Tag

Tag returns the language tag corresponding to the given language position


type NonTranslator

type NonTranslator struct {

NonTranslator is the default translator that just passes all strings through unchanged.

func (NonTranslator) Translate

func (n NonTranslator) Translate(b *translationBuilder) string

type ServerLanguageEntry

type ServerLanguageEntry struct {
	// Tag is the language tag for the language
	Tag language.Tag
	// Dict is the corresponding language dictionary, helping us to describe the language to users
	Dict *display.Dictionary
	// LangString is the string to display in the lang attribute of the html tag. Leave it blank to get the default from the Tag.
	LangString string

ServerLanguageEntry is a description of a supported language from the server's perspective. It includes the information the server will need to describe the language to the browser and to do the translation.

type SupportedLanguages

type SupportedLanguages []struct {
	LocalName  string
	NativeName string

SupportedLanguages is returuned by GetSupported

func GetSupportedLanguages

func GetSupportedLanguages(t language.Tag) SupportedLanguages

GetSupportedLanguages returns a slice of the supported languages, in both the language indicated and the native representation of the name of that language. You could use this to present a menu to the user. The order is the same as the ServerLanguages and ServerDictionaries

type TranslatorI

type TranslatorI interface {
	// Translate returns the translation of the string contained in the translationBuilder
	Translate(b *translationBuilder) string

TranslatorI is the interface that translators must fulfill

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL