Documentation
¶
Overview ¶
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.
Index ¶
- Constants
- func Build() *translationBuilder
- func CanonicalValue(i int) string
- func Comment(c string) interface{}
- func CurrentLanguage(ctx context.Context) (int, string)
- func CurrentLanguageAttribute(ctx context.Context) string
- func ExtractBuilderFromArguments(args []interface{}) (b *translationBuilder, args2 []interface{})
- func ID(i string) interface{}
- func RegisterTranslator(domain string, t TranslatorI)
- func SetDefaultLanguage(ctx context.Context, acceptLanguageValue string) int
- func SetLanguage(ctx context.Context, i int)
- func SetSupportedLanguages(l ...ServerLanguageEntry)
- func Tag(i int) language.Tag
- type NonTranslator
- type ServerLanguageEntry
- type SupportedLanguages
- type TranslatorI
Constants ¶
const GoraddDomain = "goradd"
Predefined domains. Plugins can add their own domains.
const ProjectDomain = "project"
Variables ¶
This section is empty.
Functions ¶
func CanonicalValue ¶
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 ¶
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 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 ¶
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 ¶
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.
Types ¶
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 ¶
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
Source Files