Documentation
¶
Overview ¶
Package i18n translates the interface (t()/formatPlural()): source strings are English, catalogs give their translations per language. A lookup goes down a chain - the active theme's catalog, then the engine's, then the modules' - and falls back to the source string itself.
Catalog file (JSON, one per language):
{
"strings": {
"Save": "Speichern",
"@count view": ["@count Aufruf", "@count Aufrufe"]
},
"contexts": {
"Long month name": {"May": "Mai"}
}
}
A plural entry is keyed by the singular source string and holds one form per plural category of the language (PluralIndex).
Placeholders: @name - the value HTML-escaped; %name - escaped and wrapped in <em class="placeholder">; :name - a URL (unsafe schemes dropped, non-ASCII percent-encoded, then escaped). @count in plural strings is the number.
Index ¶
- Constants
- func CheckTranslation(source, text string) error
- func Default() string
- func DirFS(dir string) fs.FS
- func ErrorText(ctx context.Context, err error) string
- func Errorf(source string, args ...any) error
- func Format(text string, args ...any) string
- func FormatText(text string, args ...any) string
- func FromContext(ctx context.Context) string
- func IsUserError(err error) bool
- func JSScript(lang string) []byte
- func JSVersion(lang string) string
- func N(source string) string
- func NC(msgctx, source string) string
- func NativeName(code string) string
- func Plural(ctx context.Context, count int, singular, plural string, args ...any) string
- func PluralCategories(lang string) []string
- func PluralIndex(lang string, count int) int
- func SetDefault(lang string)
- func SetJSKeys(keys []JSKey)
- func SetTranslator(t *Translator)
- func T(ctx context.Context, source string, args ...any) string
- func TC(ctx context.Context, msgctx, source string, args ...any) string
- func WithLang(ctx context.Context, lang string) context.Context
- type Entry
- type Error
- type JSKey
- type LanguageOption
- type Source
- type TranslationError
- type Translator
- func (t *Translator) Available(lang string) bool
- func (t *Translator) Default(lang, ctx, source string) (string, []string, bool)
- func (t *Translator) Has(lang, ctx, source string) bool
- func (t *Translator) Languages() []string
- func (t *Translator) Options() []LanguageOption
- func (t *Translator) Plural(lang, ctx string, count int, singular, plural string, args ...any) string
- func (t *Translator) PluralText(lang, ctx string, count int, singular, plural string, args ...any) string
- func (t *Translator) Site(lang, ctx, source string) (string, []string, bool)
- func (t *Translator) T(lang, ctx, source string, args ...any) string
- func (t *Translator) Text(lang, ctx, source string, args ...any) string
- func (t *Translator) WithPacks(entries []Entry) *Translator
- func (t *Translator) WithSite(entries []Entry) *Translator
Constants ¶
const SourceLanguage = "en"
SourceLanguage - the language of the source strings.
Variables ¶
This section is empty.
Functions ¶
func CheckTranslation ¶
CheckTranslation - whether text may stand for source: it keeps every placeholder of the source (@count may go - a plural form may spell the number out) and has no HTML but the source's own tags, as they are (a translation is output as HTML, unescaped); a "<" or ">" a browser takes for text is text.
func ErrorText ¶
ErrorText - err's message for the user in the request's language: the translation of an Error anywhere in err's chain; any other error gets a message of its own - its text (paths, queries, addresses) is for the log, not for visitors.
func Errorf ¶
Errorf - an Error with placeholders, for messages a service returns to be shown to the user: i18n.Errorf("User @name already exists.", "@name", name).
func Format ¶
Format fills the @name/%name/:name placeholders in text from args (name/value pairs) for HTML: values escaped, %name wrapped in <em class="placeholder">.
func FormatText ¶
FormatText fills the placeholders as plain text (values as is).
func FromContext ¶
FromContext - the request's language, else the site's default.
func IsUserError ¶
IsUserError - whether err carries a message for the user (an Error in its chain): a check the input failed rather than a failure of the site.
func JSScript ¶
JSScript - the script served at /i18n/<lang>.js: the translations of the JS strings in lang (window.kosatkaTranslations) and the runtime (Kosatka.t, Kosatka.tc, Kosatka.formatPlural). Like Go's T, the functions return plain text: placeholder values are not escaped.
func N ¶
N marks source as an interface string without translating it (like gettext_noop): for labels kept in data - maps, struct fields, defaults - and translated where shown, with T(ctx, label) or {{t .Label}}. cmd/i18n-extract finds i18n.N("…") like i18n.T.
func NativeName ¶
NativeName - the language's name in the language itself ("Deutsch"); the code for one it doesn't know.
func PluralCategories ¶
PluralCategories - the CLDR plural categories lang uses for whole numbers, in CLDR order (zero, one, two, few, many, other): the order of a plural entry's forms in its catalog ("one", "few", "many" for Russian; "one", "other" for English).
func PluralIndex ¶
PluralIndex - the plural form index of count in lang: its CLDR plural category's place among the categories lang uses for whole numbers (PluralCategories) - Russian 1 / 2-4 / 5+ (with 11-14), Polish, Czech, French and the rest by their own CLDR rules.
func SetDefault ¶
func SetDefault(lang string)
SetDefault makes lang the site's default language (from the site settings).
func SetJSKeys ¶
func SetJSKeys(keys []JSKey)
SetJSKeys sets the strings the JavaScript translates; the per-language scripts (JSScript) are rebuilt on next use.
func T ¶
T - source in the request's language as plain text, for Go code (Translator.Text with the site's translator); escaped where output.
Types ¶
type Entry ¶
Entry - a translation kept outside the catalog files (a site's own or a downloaded one, in its database): its language, context and source, its text or its plural forms (keyed by the singular source, as in a catalog).
type Error ¶
Error - an error whose message is an interface string: Error() is the English text (logs), ErrorText translates it for the user.
type JSKey ¶
JSKey - a string the site's JavaScript translates with Kosatka.t, Kosatka.tc or Kosatka.formatPlural (found at startup by internal/i18nextract.ExtractJS).
type LanguageOption ¶
LanguageOption - a language for a select: its code and native name.
func KnownLanguages ¶
func KnownLanguages() []LanguageOption
KnownLanguages - the languages it has names for, by code: what a site's content may be in (its interface - only Options').
type Source ¶
type Source struct {
Context string `json:"context,omitempty"`
Source string `json:"source"`
Plural string `json:"plural,omitempty"`
Module string `json:"module,omitempty"`
Theme string `json:"theme,omitempty"`
Starter bool `json:"starter,omitempty"`
}
Source - an interface string of the code (the source strings' list, translations/sources): its context, source (a plural string's singular, its catalog key) and plural form, and whose it is - the engine's, a module's or a theme's. Starter - a text only a new site's starter content has: written once, in the site's language, as its data (a language pack translates it; it isn't the interface's).
func CatalogSources ¶
CatalogSources - the strings the catalogs of dir (<lang>.json files) translate, each once: the strings of a theme or module the sources list hasn't (Plural unknown; a plural entry's forms tell it).
func ParseSources ¶
ParseSources - the source strings' list (JSON).
type TranslationError ¶
TranslationError - why a translation can't stand for its source: a placeholder of the source it drops (Placeholder), or HTML the source doesn't have (Tag; "<" - a tag not closed).
func (*TranslationError) Error ¶
func (e *TranslationError) Error() string
type Translator ¶
type Translator struct {
// contains filtered or unexported fields
}
Translator - the catalogs of every language, in lookup order (the theme's first, then the engine's, then the modules', then the downloaded ones - WithPacks), and the site's own translations over them (WithSite).
func Load ¶
func Load(dirs ...fs.FS) (*Translator, error)
Load builds a Translator from catalog directories in lookup order (e.g. the theme's, the engine's, the modules'): each holds <lang>.json files; a missing directory is skipped.
func (*Translator) Available ¶
func (t *Translator) Available(lang string) bool
Available - lang is one of Options.
func (*Translator) Default ¶
func (t *Translator) Default(lang, ctx, source string) (string, []string, bool)
Default - the translation of source (in context ctx) to lang by the catalogs alone, the site's own left out: its text or plural forms; false - none.
func (*Translator) Has ¶
func (t *Translator) Has(lang, ctx, source string) bool
Has - source (in context ctx) has a translation for lang.
func (*Translator) Languages ¶
func (t *Translator) Languages() []string
Languages - the languages with a catalog, sorted.
func (*Translator) Options ¶
func (t *Translator) Options() []LanguageOption
Options - the languages the interface can be shown in: the source language and every language with a catalog.
func (*Translator) Plural ¶
func (t *Translator) Plural(lang, ctx string, count int, singular, plural string, args ...any) string
Plural - the form of singular/plural for count in lang: the catalog's forms of singular (PluralIndex), else the English source forms. @count is count; args as for T. The result is HTML.
func (*Translator) PluralText ¶
func (t *Translator) PluralText(lang, ctx string, count int, singular, plural string, args ...any) string
PluralText - Plural as plain text (see Text).
func (*Translator) Site ¶
func (t *Translator) Site(lang, ctx, source string) (string, []string, bool)
Site - the site's own translation of source to lang (WithSite).
func (*Translator) T ¶
func (t *Translator) T(lang, ctx, source string, args ...any) string
T - source translated to lang, placeholders filled from args (name/value pairs: "@name", value, …). The result is HTML (values are escaped; the catalogs are trusted) - for templates.
func (*Translator) Text ¶
func (t *Translator) Text(lang, ctx, source string, args ...any) string
Text - T as plain text: values are not escaped, %name is not wrapped - for Go code, whose strings are escaped where they are output.
func (*Translator) WithPacks ¶
func (t *Translator) WithPacks(entries []Entry) *Translator
WithPacks - t with the downloaded translations (packs) as the last catalog of their languages: a copy, t is left as it is. A pack is of a language the built-in catalogs don't have, so for it the theme's catalog comes first and the pack after it.
func (*Translator) WithSite ¶
func (t *Translator) WithSite(entries []Entry) *Translator
WithSite - t with the site's own translations over its catalogs: a copy, t is left as it is. A source the site rewords in English (SourceLanguage) reads so in a language that doesn't translate it.