i18n

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: AGPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package i18n is ReputeCast's server-side localization: the app languages (English, 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

Constants

This section is empty.

Variables

View Source
var Default = Lang{Locale: English, Region: Standard}

Default is English with the ReputeCast standard formats: what API clients get unless they send Accept-Language.

View Source
var ErrUnknownKey = errors.New("i18n: unknown message key")

ErrUnknownKey is returned by Lookup for a key the catalog doesn't have.

Functions

func AndList

func AndList(l Locale, items []string) string

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 và C".

func Arguments

func Arguments(message string) ([]string, error)

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 Format

func Format(l Lang, message string, args Args) (string, error)

Format formats a message that isn't in a catalog (for tests and tools).

func FormatHTML

func FormatHTML(l Lang, message string, args Args, tags Tags) (string, error)

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 OrList

func OrList(l Locale, items []string) string

OrList joins alternatives: "Marcus Chen or Linh Nguyen", "… hoặc …".

func PseudoEnabled

func PseudoEnabled() bool

PseudoEnabled reports whether the pseudo-locale can be picked.

func SetPseudo

func SetPseudo(on bool)

SetPseudo turns the pseudo-locale on or off for this process.

func Validate

func Validate(message string) error

Validate parses a message on its own (for tests and tools).

func WithLang

func WithLang(ctx context.Context, l Lang) context.Context

WithLang returns a context that formats messages for l.

Types

type Args

type Args map[string]any

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

func Load(fsys fs.FS, namespace string) (*Catalog, error)

Load reads messages/*.json from fsys. en.json is required. A translation may only use keys and arguments its English source has.

func MustLoad

func MustLoad(fsys fs.FS, namespace string) *Catalog

MustLoad is Load for package initialization: a broken catalog stops the program (and every test) at once.

func (*Catalog) Keys

func (c *Catalog) Keys() []string

Keys returns the message keys, sorted.

func (*Catalog) Lookup

func (c *Catalog) Lookup(key string) (Msg, error)

Lookup returns the message with this key, for keys only known at run time.

func (*Catalog) M

func (c *Catalog) M(key string) Msg

M returns the message with this key. It panics when en.json doesn't have it, so a typo fails at package initialization.

func (*Catalog) Missing

func (c *Catalog) Missing(l Locale) []string

Missing returns the keys a language hasn't translated yet.

type HTML

type HTML string

HTML is markup a caller has already escaped, kept as is in HTML output.

type HourCycle

type HourCycle string

HourCycle is a 24-hour (h23) or 12-hour (h12) clock.

const (
	H23 HourCycle = "h23"
	H12 HourCycle = "h12"
)

type Lang

type Lang struct {
	Locale Locale
	Region Region
}

Lang is how one person reads: the app language and the region format that writes dates and numbers.

func For

func For(l Locale) Lang

For returns the language a locale reads in with its own region format.

func LangFrom

func LangFrom(ctx context.Context) Lang

LangFrom returns the language stored by WithLang, or Default.

func LangFromContext

func LangFromContext(ctx context.Context) (Lang, bool)

LangFromContext is LangFrom, saying whether a language was stored.

func Resolve

func Resolve(memberLocale, memberRegion, defaultLocale, defaultRegion string) Lang

Resolve picks how a member reads: their own choices when they made them, else the instance defaults. A region the member didn't choose follows their language, or the instance's default region when the language is the instance default too.

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"
	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: English, Vietnamese, then the pseudo-locale when it's on.

func Negotiate

func Negotiate(acceptLanguage string) (l Locale, ok bool)

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

func ParseLocale(s string) (Locale, bool)

ParseLocale reads a stored or requested app language ("en", "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

func (l Locale) DefaultRegion() Region

DefaultRegion is the region format a language follows when the member hasn't chosen one: ReputeCast standard for English (and the pseudo-locale), Tiếng Việt (Việt Nam) for Vietnamese.

func (Locale) Name

func (l Locale) Name() string

Name is the language's name in itself: "English", "Tiếng Việt".

func (Locale) Tag

func (l Locale) Tag() language.Tag

Tag is the BCP 47 tag of the language, for plural rules and matching.

func (Locale) Valid

func (l Locale) Valid() bool

Valid reports whether l can be picked right now.

type Msg

type Msg struct {
	// contains filtered or unexported fields
}

Msg is one message of a catalog.

func (Msg) HTML

func (m Msg) HTML(l Lang, args Args, tags Tags) string

HTML formats the message as HTML: its text and string values are escaped, HTML values are kept, and tags go through tags.

func (Msg) ID

func (m Msg) ID() string

ID is the message's full ID, namespace.key.

func (Msg) Keep

func (m Msg) Keep(args Args) Text

Keep returns the message with its arguments, to store for later readers.

func (Msg) Source

func (m Msg) Source() string

Source is the English text.

func (Msg) Text

func (m Msg) Text(l Lang, args Args) string

Text formats the message as plain text: tags keep their content.

type ParseError

type ParseError struct {
	Message string
	Offset  int
	Reason  string
}

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 Regions

func Regions() []Region

Regions returns every region format, in picker order.

func (Region) Date

func (r Region) Date(t time.Time) string

Date writes a day with its year: Oct 14, 2026 · 14 thg 10, 2026.

func (Region) DayMonth

func (r Region) DayMonth(t time.Time) string

DayMonth writes a day without the weekday or year: 14 Oct · 14 thg 10.

func (Region) Decimal

func (r Region) Decimal(v float64, digits int) string

Decimal writes a number with exactly digits fraction digits.

func (Region) HourCycle

func (r Region) HourCycle() HourCycle

HourCycle is the region's clock: 12-hour for English (United States).

func (Region) Int

func (r Region) Int(n int64) string

Int writes an integer with the region's grouping: 48,213 · 48.213 · 48 213.

func (Region) LongDate

func (r Region) LongDate(t time.Time) string

LongDate writes a day with the weekday in full: Tuesday 14 Oct 2026.

func (Region) Money

func (r Region) Money(v float64, digits int) string

Money writes US dollars, the currency provider costs are in: $2.84 · 2,84 US$.

func (Region) MonthYear

func (r Region) MonthYear(t time.Time, long bool) string

MonthYear writes a month with its year: Oct 2026, thg 10 2026; long: October 2026, tháng 10 năm 2026.

func (Region) Name

func (r Region) Name() string

Name is the region format's name in its own language: "Tiếng Việt (Việt Nam)".

func (Region) Percent

func (r Region) Percent(v float64, digits int) string

Percent writes a percentage given in percent units (99.1 → 99.1%).

func (Region) ShortDate

func (r Region) ShortDate(t time.Time) string

ShortDate writes a day with its weekday: Tue 14 Oct · Th 3, 14 thg 10.

func (Region) Time

func (r Region) Time(t time.Time, hc HourCycle) string

Time writes a time of day on the given clock, or the region's own when hc is empty.

func (Region) Valid

func (r Region) Valid() bool

Valid reports whether r is a region format ReputeCast has.

func (Region) WeekStartsSunday

func (r Region) WeekStartsSunday() bool

WeekStartsSunday reports whether the region's week starts on Sunday.

func (Region) WeekdayDate

func (r Region) WeekdayDate(t time.Time) string

WeekdayDate writes a day with its weekday and year: Tue 14 Oct 2026.

type Tags

type Tags map[string]func(inner string) string

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

type Text struct {
	ID   string `json:"id"`
	Args Args   `json:"args,omitempty"`
}

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).

func (Text) In

func (t Text) In(l Lang) string

In writes the text in a reader's language. It returns "" when the message isn't known (no ID, or a catalog that no longer has it): the caller shows the English it stored instead.

func (Text) IsZero

func (t Text) IsZero() bool

IsZero reports whether there is no message, as in rows written before their text was kept.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL