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. Pass a value from the command line or a variable through Clip before a message that refuses it quotes it.
Index ¶
- Variables
- func CheckCatalogs(fsys fs.FS, domain string) error
- func Clip(value string) string
- func IsLanguage(setting string) bool
- func Locales() fs.FS
- func Requested(setting string) string
- type CatalogError
- type Catalogs
- type Printer
- func (p *Printer) Date(t time.Time) string
- func (p *Printer) Duration(d time.Duration) string
- func (p *Printer) N(id string, count int, data ...map[string]any) string
- func (p *Printer) Number(v float64, decimals int) string
- func (p *Printer) Size(bytes int64) string
- func (p *Printer) T(id string, data ...map[string]any) string
Constants ¶
This section is empty.
Variables ¶
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.
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 ¶
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 Clip ¶ added in v0.23.3
Clip returns the first clipLimit characters of a value from the command line or a variable, then …, when the value is longer. A message that refuses the value quotes it so, as Output in contract.md asks. A hint or a next command keeps the whole value.
func IsLanguage ¶ added in v0.23.3
IsLanguage reports whether ncly accepts a language setting, with or without a catalog. It accepts a known tag such as de, its POSIX form such as fr_CA.UTF-8, C, and POSIX. It refuses an unknown language, such as xx-YY.
Types ¶
type CatalogError ¶
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 ¶
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.
type Printer ¶
type Printer struct {
// contains filtered or unexported fields
}
Printer returns catalog text and formats values in one language.
func (*Printer) Date ¶
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
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 ¶
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 ¶
Number formats v with at most the given decimals, such as 1,234.5 in English and 1 234,5 in Canadian French.