Documentation
¶
Overview ¶
Package i18n is ReputeCast's server-side localization: the app languages (English, German, Spanish, French, Vietnamese and the pseudo-locale used to check layouts), region formats, language negotiation, CLDR plural rules and message catalogs.
Catalogs ¶
A package keeps its messages in messages/<locale>.json next to its code and embeds them:
//go:embed messages/*.json
var messagesFS embed.FS
var msgs = i18n.MustLoad(messagesFS, "systemmail")
var mInviteSubject = msgs.M("invite.subject") // panics at init when the key is missing
en.json holds the English source; every other file is a translation of it. A file is a flat object of keys to ICU MessageFormat strings ("key": "text", or "key": {"message": "text", "note": "for translators"}).
Why this format: the web app's messages are ICU MessageFormat too (web/src/i18n), so translators learn one syntax for the whole product and translation platforms (Weblate, Crowdin, Lokalise) import the files as "ICU JSON". Plurals follow CLDR on both sides: golang.org/x/text here, Intl.PluralRules in the browser. pnpm run i18n:check lists missing keys for the server catalogs as well as the web's.
The formatter implements the part of ICU MessageFormat ReputeCast uses: simple and number arguments, plural (with =N, offset and #), select, selectordinal and <tags>, with ICU's apostrophe quoting. It needs nothing beyond golang.org/x/text, which the module already depends on.
Text the server stores for people who read it later keeps the message's ID and arguments as a Text (Msg.Keep), and Text.In writes it in each reader's language.
Languages and regions ¶
A Lang is how one person reads: the app language (Locale) and the region format (Region) that writes dates and numbers. Region formats are a snapshot of Unicode CLDR kept in this package and mirrored by web/src/i18n/regions.ts, so the server and every browser write the same date the same way; testdata/regions.json holds the vectors both test. "ReputeCast standard" keeps the app's own formats (Tue 14 Oct 2026 · 09:00 · 48,213 · 99.1% · $2.84).
Index ¶
- Variables
- func AndList(l Locale, items []string) string
- func Arguments(message string) ([]string, error)
- func Format(l Lang, message string, args Args) (string, error)
- func FormatHTML(l Lang, message string, args Args, tags Tags) (string, error)
- func KeepsCapitals(l Locale) bool
- func LanguageName(l Locale, code string) string
- func LowersLanguageNames(l Locale) bool
- func OrList(l Locale, items []string) string
- func PseudoEnabled() bool
- func Quote(l Locale, s string) string
- func SetPseudo(on bool)
- func StandaloneLanguageName(l Locale, name string) string
- func Validate(message string) error
- func WithLang(ctx context.Context, l Lang) context.Context
- type Args
- type Catalog
- type HTML
- type HourCycle
- type Lang
- type Locale
- type Msg
- type ParseError
- type Region
- func (r Region) Date(t time.Time) string
- func (r Region) DayMonth(t time.Time) string
- func (r Region) Decimal(v float64, digits int) string
- func (r Region) HourCycle() HourCycle
- func (r Region) Int(n int64) string
- func (r Region) LongDate(t time.Time) string
- func (r Region) Money(v float64, digits int) string
- func (r Region) MonthYear(t time.Time, long bool) string
- func (r Region) Name() string
- func (r Region) Percent(v float64, digits int) string
- func (r Region) ShortDate(t time.Time) string
- func (r Region) Time(t time.Time, hc HourCycle) string
- func (r Region) Valid() bool
- func (r Region) WeekStartsSunday() bool
- func (r Region) WeekdayDate(t time.Time) string
- type Tags
- type Text
Constants ¶
This section is empty.
Variables ¶
var Default = Lang{Locale: English, Region: Standard}
Default is English with the ReputeCast standard formats: what API clients get unless they send Accept-Language.
var ErrUnknownKey = errors.New("i18n: unknown message key")
ErrUnknownKey is returned by Lookup for a key the catalog doesn't have.
Functions ¶
func AndList ¶
AndList joins items the way the language writes a list: "A, B and C" (English keeps the house style, without the serial comma), "A, B y C", "A, B và C".
func Arguments ¶
Arguments returns the arguments a message uses and its tags ("<link>"), sorted, so text written for a message can be checked against its source.
func FormatHTML ¶
FormatHTML is Format for HTML output, as Msg.HTML formats: the text and string values are escaped, HTML values are kept and tags go through tags. It formats text a workspace wrote for a message, such as the built-in labels of its public pages in a language ReputeCast isn't translated into.
func KeepsCapitals ¶
KeepsCapitals reports whether l writes a phrase's first letter as it is inside a sentence: German capitalises every noun, so a label put inside a sentence ("Kampagnen senden") keeps its capital, where English and the others start it with a small letter ("send campaigns").
func LanguageName ¶
LanguageName names a language (a code such as "es" or "pt-BR") in an app language as CLDR does, as the name stands on its own: "Inglés", "Anglais", "Englisch", "Tiếng Anh". It is "" for English (callers keep their own English names) and for a code CLDR doesn't name in l.
func LowersLanguageNames ¶
LowersLanguageNames reports whether l writes a language's name in lower case inside a sentence ("tiếng Anh", "inglés", "anglais").
func PseudoEnabled ¶
func PseudoEnabled() bool
PseudoEnabled reports whether the pseudo-locale can be picked.
func Quote ¶
Quote puts a name between the quotation marks of l: „Weekly Digest“ in German, « Weekly Digest » in French (with no-break spaces), “Weekly Digest” in English and the others.
func SetPseudo ¶
func SetPseudo(on bool)
SetPseudo turns the pseudo-locale on or off for this process.
func StandaloneLanguageName ¶
StandaloneLanguageName is a language's name as it stands on its own in l: Spanish and French capitalise it ("inglés" → "Inglés"). A name a catalog gives (a translation of "Spanish") is noted, so the name takes the case its place needs inside a sentence too.
Types ¶
type Args ¶
Args are a message's values by name: strings, numbers, HTML (trusted markup for HTML output) or times (written as dates).
type Catalog ¶
type Catalog struct {
Namespace string
// contains filtered or unexported fields
}
Catalog is one package's messages: the English source (messages/en.json) and its translations (messages/vi.json…).
func Catalogs ¶
func Catalogs() []*Catalog
Catalogs returns every catalog loaded so far, by namespace.
func Load ¶
Load reads messages/*.json from fsys. en.json is required. A translation may only use keys and arguments its English source has.
func MustLoad ¶
MustLoad is Load for package initialization: a broken catalog stops the program (and every test) at once.
type HTML ¶
type HTML string
HTML is markup a caller has already escaped, kept as is in HTML output.
type Lang ¶
Lang is how one person reads: the app language and the region format that writes dates and numbers.
func LangFromContext ¶
LangFromContext is LangFrom, saying whether a language was stored.
type Locale ¶
type Locale string
Locale is an app language: the language of ReputeCast's own interface and of the emails it sends to members.
const ( English Locale = "en" German Locale = "de" Spanish Locale = "es" French Locale = "fr" Vietnamese Locale = "vi" // Pseudo is the pseudo-locale "Pseudo (+40%)": every letter accented, // about 40% longer and wrapped in ⟦ ⟧. It checks layouts, and text that // skipped the catalogs shows without the brackets. Available only in // development or when the server runs with i18n.pseudo_locale on. Pseudo Locale = "en-XA" )
func Locales ¶
func Locales() []Locale
Locales returns the app languages that can be picked, in picker order: the app languages, then the pseudo-locale when it's on.
func Negotiate ¶
Negotiate picks the app language for an Accept-Language header. ok is false when the header is empty or names nothing ReputeCast is translated into; the language is English then.
func ParseLocale ¶
ParseLocale reads a stored or requested app language ("en", "de", "es", "fr", "vi", "en-XA"), ignoring case. Regional variants of a supported language match it ("vi-VN" is Vietnamese), except the pseudo-locale, which must be exact.
func (Locale) DefaultRegion ¶
DefaultRegion is the region format a language follows when the member hasn't chosen one: ReputeCast standard for English (and the pseudo-locale), the language's own country for the others: Deutsch (Deutschland), Español (España), Français (France), Tiếng Việt (Việt Nam).
type Msg ¶
type Msg struct {
// contains filtered or unexported fields
}
Msg is one message of a catalog.
func (Msg) HTML ¶
HTML formats the message as HTML: its text and string values are escaped, HTML values are kept, and tags go through tags.
type ParseError ¶
ParseError points at what's wrong in a message.
func (*ParseError) Error ¶
func (e *ParseError) Error() string
type Region ¶
type Region string
Region is a region format: how dates, times and numbers are written. Standard is ReputeCast's own; the others are CLDR locales.
const Standard Region = "standard"
Standard keeps the formats ReputeCast has always used: Tue 14 Oct 2026 · 09:00 · 48,213 · 99.1% · $2.84.
func (Region) Money ¶
Money writes US dollars, the currency provider costs are in: $2.84 · 2,84 US$.
func (Region) MonthYear ¶
MonthYear writes a month with its year: Oct 2026, thg 10 2026; long: October 2026, tháng 10 năm 2026.
func (Region) Time ¶
Time writes a time of day on the given clock, or the region's own when hc is empty.
func (Region) WeekStartsSunday ¶
WeekStartsSunday reports whether the region's week starts on Sunday.
type Tags ¶
Tags turn a message's <tags> into HTML: the function gets the tag's content, already escaped. <b>, <strong>, <i> and <em> work without one; any other tag without a function keeps only its content.
type Text ¶
Text is a message kept for readers who come later: a catalog message's ID and its arguments, written in each reader's language when it's read. The server stores it beside the English for text other people read later (a Send Readiness run's checks, a notification, a plan's log).
Arguments go through JSON: numbers come back as float64 and times as RFC 3339 strings, which {at, date} and {at, time} read again. Keep a time in the zone the reader should see it in (the workspace's).