i18n

package
v0.18.5 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package i18n looks up the text that ncly and its extensions show a human in their message catalogs, and formats numbers, sizes, and dates for the active language. Every catalog entry carries a description that tells a translator where the text appears.

Send every string that a human reads through a catalog. Name each ID <domain>.<thing>, and never reuse an ID for a new meaning. Give every message that holds a number its plural forms. Send such a message through N, Size, or Duration: T always shows its other form, and the test binary of cmd/ncly refuses it. Format numbers, sizes, durations, and dates through this package, and let translated text set its own width.

Index

Constants

This section is empty.

Variables

View Source
var PluralGuard bool

PluralGuard, when true, makes Printer.T panic on a message with a one form in any loaded language, and name its ID. T passes no count, so it shows the other form. Only the test binary of cmd/ncly sets it, so a scenario fails where such a call runs, even with the ID in a variable. See #234.

View Source
var Pseudo = language.MustParse("en-XA")

Pseudo is the pseudo-locale: every catalog string, marked between ⟦ and ⟧, so a scenario finds the text that bypasses the catalog.

Functions

func CheckCatalogs

func CheckCatalogs(fsys fs.FS, domain string) error

CheckCatalogs applies the catalog rules of SDK in contract.md to the catalogs at the top of fsys: every entry has a description, an entry whose other form reads a number field has a one form, and every language holds exactly the IDs of en. A non-empty domain, an extension's, also requires every ID to start with the domain and a dot.

func Locales

func Locales() fs.FS

Locales returns the SDK's own catalogs: the text that the SDK renders, such as help pages, usage errors, and outcome summaries.

func Requested

func Requested(setting string) string

Requested returns the language that a setting requests, as a tag, such as fr-CA for fr_CA.UTF-8, whether or not a catalog speaks it. A setting that names no known language, including C and POSIX, requests en.

Types

type CatalogError

type CatalogError struct {
	File string
	Line int
	Err  error
}

CatalogError reports an en catalog that is missing, unreadable, or not a catalog. Line is 0 when the parser does not say where.

func (*CatalogError) Error

func (e *CatalogError) Error() string

func (*CatalogError) Unwrap

func (e *CatalogError) Unwrap() error

type Catalogs

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

Catalogs holds the catalogs of one or more owners, such as the SDK and core, or the SDK and an extension: for each owner, one file per language, named after its tag, such as en.toml or fr-CA.toml. Each owner's en catalog is required, and the pseudo-locale marks it.

func Load

func Load(folders ...fs.FS) (*Catalogs, error)

Load reads the catalogs at the top of each folder. Only each en catalog must be valid: a translation that cannot be read is skipped, so its entries fall back to en. The owners' IDs never overlap, as the catalog rules require, so the order of the folders does not matter.

func (*Catalogs) Has

func (c *Catalogs) Has(id string) bool

Has reports whether the en catalog holds an ID.

func (*Catalogs) Match

func (c *Catalogs) Match(setting string) language.Tag

Match picks the catalog for a language setting, such as fr-CA, fr, or the POSIX form fr_CA.UTF-8. A setting with no close catalog, including C and POSIX, gets English. The pseudo-locale needs an exact request, so that en-GB never selects it.

func (*Catalogs) Printer

func (c *Catalogs) Printer(setting string) *Printer

Printer returns a printer of these catalogs for a language setting.

type Printer

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

Printer returns catalog text and formats values in one language.

func (*Printer) Date

func (p *Printer) Date(t time.Time) string

Date formats a day as ISO 8601, such as 2026-10-06, in every language: it reads the same in English and is the Canadian French standard.

func (*Printer) Duration added in v0.18.0

func (p *Printer) Duration(d time.Duration) string

Duration formats d in the largest unit, up to the hour, that keeps the number at 1 or more, with at most one decimal, such as 1.5 s or 2 min, in the plural form of that number. Milliseconds take no decimal.

func (*Printer) N

func (p *Printer) N(id string, count int, data ...map[string]any) string

N returns the plural form of the message id that fits count, with data filling its template. Count in the template is always count, formatted.

func (*Printer) Number

func (p *Printer) Number(v float64, decimals int) string

Number formats v with at most the given decimals, such as 1,234.5 in English and 1 234,5 in Canadian French.

func (*Printer) Size

func (p *Printer) Size(bytes int64) string

Size formats a byte count with at most one decimal in the largest unit that keeps the number at 1 or more, such as 1.5 MB, in the plural form of that number. Bytes take no decimal.

func (*Printer) T

func (p *Printer) T(id string, data ...map[string]any) string

T returns the catalog message for id, with data filling its template. A message that the active catalog lacks falls back to en, and a message that en lacks too returns the id itself, so a scenario shows it.

Jump to

Keyboard shortcuts

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