gointl

go-intl

A Go implementation of the active ECMA-402 Intl API with typed constructors and generated CLDR data.

Features

• Native Intl alignment: Public packages map to the active Intl constructors: Locale, NumberFormat, DateTimeFormat, PluralRules, ListFormat, RelativeTimeFormat, DurationFormat, DisplayNames, Collator, and Segmenter.
• Typed Go bridge: Parse locale strings into locale.List, then pass time.Time, typed option structs, and typed numeric values while preserving ECMA-402 behavior.
• Root namespace: The root package represents the JavaScript Intl namespace as an aggregate facade; production services that need one formatter should import that constructor package directly.
• Reusable formatters: Construct once and reuse; constructors resolve locale, options, and data so repeated formatting stays on the cached path.
• Host-friendly records: Resolved options, parts, ranges, locale info, segments, and durations marshal with ECMA-402 JSON field names for API and JS-host boundaries.
• Structured errors: Root sentinels work with errors.Is, and gointl.Error exposes stable kind, owner, option, value, locale, and expected-value guidance.
• CLDR-backed data: Ship generated CLDR data as Go source; applications do not load JSON, ICU, or time-zone data files at runtime.
• Reference fixtures: Verify formatter output against ECMA-402-derived FormatJS fixtures and native Intl snapshots.

Installation

go get github.com/agentable/go-intl

Requires Go 1.26+.

Quick Start

Construct the formatter that matches the JavaScript Intl constructor you would use:

package main

import (
	"fmt"
	"log"
	"time"

	gointl "github.com/agentable/go-intl"
	"github.com/agentable/go-intl/datetimeformat"
	"github.com/agentable/go-intl/locale"
	"github.com/agentable/go-intl/numberformat"
)

func main() {
	locales, err := locale.ParseList("en-US")
	if err != nil {
		log.Fatal(err)
	}

	priceFormat, err := numberformat.New(locales, numberformat.Options{
		Style:    gointl.String(numberformat.CurrencyStyle),
		Currency: gointl.String("USD"),
	})
	if err != nil {
		log.Fatal(err)
	}
	price := priceFormat.Format(numberformat.Float(1234.5))

	dateFormat, err := datetimeformat.New(locales, datetimeformat.Options{
		DateStyle: gointl.String(datetimeformat.LongDateTimeStyle),
		TimeZone:  gointl.String("America/New_York"),
	})
	if err != nil {
		log.Fatal(err)
	}
	date := dateFormat.Format(time.Date(2026, time.May, 8, 14, 30, 0, 0, time.UTC))

	fmt.Println(price)
	fmt.Println(date)
}

Output:

$1,234.50
May 8, 2026

Packages

Prefer constructor subpackages in services that need one formatter. Importing github.com/agentable/go-intl is an aggregate facade: it mirrors the JavaScript Intl namespace and therefore imports every active constructor surface for namespace helpers and type aliases. Use the root package for GetCanonicalLocales, root supported-value accessors, or when you intentionally want the full Intl namespace shape.

See the Go package documentation for the full API reference.

Native Intl Mapping

The Go packages follow the ownership of the native JavaScript Intl API:

Usage

Parse Locales Once

Parse BCP 47 tags at your application boundary. Formatter constructors receive a locale.List: use nil or locale.List{} for omitted locales, and locale.ParseList for request lists that can fail.

Use the root gointl.GetCanonicalLocales helper when you need the ECMA-402 Intl.getCanonicalLocales operation. The lower-level locale-list canonicalization step is internal to constructors and SupportedLocalesOf.

locales, err := locale.ParseList("zh-Hant-TW-u-nu-hanidec")
if err != nil {
	return err
}
loc := locales[0]

fmt.Println(loc.String())
fmt.Println(loc.Maximize().String())
fmt.Println(loc.GetWeekInfo().FirstDay)
if direction := loc.GetTextInfo().Direction; direction != nil {
	fmt.Println(*direction)
}

GetTextInfo().Direction is present only when the generated CLDR script metadata has a known ltr or rtl value. Unknown direction remains nil and is omitted from JSON instead of being guessed.

Short examples below use a local mustLocaleList helper for brevity; production code should call locale.ParseList and handle the returned error.

Use Constructor Packages Directly

Use constructor packages directly in production services that need one Intl constructor, or when calls share locale, options, parts, ranges, or resolved options. This keeps the dependency graph tied to the formatter you use; the root package is measured as aggregate facade cost.

locales := mustLocaleList("en-US")

compactFormat, err := numberformat.New(locales, numberformat.Options{
	Notation: gointl.String(numberformat.CompactNotation),
})
if err != nil {
	return err
}

rules, err := pluralrules.New(locales, pluralrules.Options{})
if err != nil {
	return err
}

category := rules.Select(pluralrules.Int(1))

fmt.Println(compactFormat.Format(numberformat.Int(1200)))
fmt.Println(category)

Formatter-specific options stay in their formatter packages. The root package does not re-export numberformat, datetimeformat, or pluralrules option names.

Filter Supported Locales

Constructor static methods stay with their packages, just like native Intl.<Constructor>.supportedLocalesOf:

requested := mustLocaleList("de-DE", "en-US-u-nu-latn", "zh-Hans-CN")

supported, err := numberformat.SupportedLocalesOf(requested, numberformat.Options{
	LocaleMatcher: gointl.String(numberformat.LookupLocaleMatcher),
})
if err != nil {
	return err
}

fmt.Println(supported)

The result preserves the requested locale order and returns requested locale values, including Unicode extensions.

Construct Formatters for Repeated Work

Use formatter packages directly when you need resolved options, parts, ranges, or repeated calls in a hot path. Constructors do the locale, option, and data setup; keep the formatter and call its methods instead of rebuilding it per value.

format, err := numberformat.New(mustLocaleList("en-US"), numberformat.Options{
	Style:       gointl.String(numberformat.UnitStyle),
	Unit:        gointl.String("kilometer-per-hour"),
	UnitDisplay: gointl.String(numberformat.ShortUnitDisplay),
})
if err != nil {
	return err
}

fmt.Println(format.Format(numberformat.Int(88)))
if unit := format.ResolvedOptions().Unit; unit != nil {
	fmt.Println(*unit)
}

Unit identifiers follow native Intl.NumberFormat: use canonical lowercase ECMA-402 identifiers such as meter, microsecond, or kilometer-per-hour.

Use Root Namespace Helpers

Import the root package when you need native Intl namespace functions or pointer helpers for optional scalar options:

import (
	"fmt"

	gointl "github.com/agentable/go-intl"
	"github.com/agentable/go-intl/locale"
)

locales := gointl.GetCanonicalLocales(mustLocaleList("en-US", "en-US"))
units := gointl.SupportedUnits()

fmt.Println(locales[0])
fmt.Println(units[:3])

Root supported-value accessors cover calendars, collations, currencies, numbering systems, time zones, and units. Collation currently reports only identifiers the active backend can apply truthfully.

Use gointl.Int, gointl.Bool, and gointl.String for optional option fields where ECMA-402 distinguishes omitted from an explicit zero, false, or empty value.

These helpers also live in the zero-dependency leaf package github.com/agentable/go-intl/option as option.Int, option.Bool, and option.String. A service that uses a single formatter package can set its optional scalar options through option without importing the aggregate root, which pulls in every constructor package. The root re-exports the same helpers as gointl.Int/gointl.Bool/gointl.String for namespace fidelity, so the root-namespace examples above stay the primary documented style.

Format Exact Decimals

Use decimal-string methods when binary float64 cannot represent the value you need to format:

format, err := numberformat.New(mustLocaleList("en-US"), numberformat.Options{
	Style:                 gointl.String(numberformat.PercentStyle),
	MinimumFractionDigits: gointl.Int(2),
	MaximumFractionDigits: gointl.Int(2),
})
if err != nil {
	return err
}

value, err := numberformat.Decimal("0.075")
if err != nil {
	return err
}

out := format.Format(value)

fmt.Println(out)

Inspect Parts

Use parts APIs when you need to style or transform individual formatted tokens:

format, err := numberformat.New(mustLocaleList("en-US"), numberformat.Options{
	Style:    gointl.String(numberformat.CurrencyStyle),
	Currency: gointl.String("USD"),
})
if err != nil {
	return err
}

for _, part := range format.FormatToParts(numberformat.Float(1234.5)) {
	fmt.Printf("%s: %q\n", part.Type, part.Value)
}

Format Number Ranges

FormatRange and FormatRangeToParts preserve input order and use native Intl range semantics. When both endpoints render to the same visible text, the result uses the locale approximate sign; when notation or suffixes render differently, the endpoints remain a real range.

format, err := numberformat.New(mustLocaleList("en-US"), numberformat.Options{
	MaximumFractionDigits: gointl.Int(0),
})
if err != nil {
	return err
}

text, err := format.FormatRange(numberformat.Float(1.1), numberformat.Float(1.2))
if err != nil {
	return err
}

fmt.Println(text)

Output:

~1

Marshal Records for Host Boundaries

Public ECMA-402 records use camelCase JSON keys, so API adapters and JavaScript hosts can pass them through without rebuilding field maps:

format, err := numberformat.New(mustLocaleList("en-US"), numberformat.Options{
	Style:    gointl.String(numberformat.CurrencyStyle),
	Currency: gointl.String("USD"),
})
if err != nil {
	return err
}

data, err := json.Marshal(format.ResolvedOptions())
if err != nil {
	return err
}

fmt.Println(string(data))

locale.Locale marshals as its canonical BCP 47 string. Parts, range parts, durationformat.Duration, locale WeekInfo / TextInfo, and segmenter.Segment also use ECMA-402 field names.

Format Dates and Ranges

datetimeformat accepts time.Time and supports style-based or field-based formatting:

format, err := datetimeformat.New(mustLocaleList("en-US"), datetimeformat.Options{
	DateStyle: gointl.String(datetimeformat.MediumDateTimeStyle),
	TimeStyle: gointl.String(datetimeformat.ShortDateTimeStyle),
	TimeZone:  gointl.String("America/New_York"),
})
if err != nil {
	return err
}

start := time.Date(2026, time.May, 8, 14, 30, 0, 0, time.UTC)
end := start.Add(2 * time.Hour)

fmt.Println(format.Format(start))
rangeText, err := format.FormatRange(start, end)
if err != nil {
	return err
}
fmt.Println(rangeText)

Select Plural Categories

Use pluralrules to select CLDR plural categories for message selection:

rules, err := pluralrules.New(mustLocaleList("en"), pluralrules.Options{
	Type: gointl.String(pluralrules.Ordinal),
})
if err != nil {
	return err
}

for _, n := range []int64{1, 2, 3, 4} {
	category := rules.Select(pluralrules.Int(n))
	fmt.Println(category)
}

New resolves and validates the locale's generated rule family once, so Select is total and returns a category directly. SelectRange still returns an error for invalid runtime endpoints such as NaN.

SelectRange follows the same digit-option formatting path as Select: if two decimal endpoints format to different strings, they fall through to CLDR plural range data even when their mathematical rounded values compare equal.

Compact plural selection follows native Intl behavior. Public PluralRules compact notation selects from the source decimal string plus the selected compact exponent; NumberFormat compact formatting separately chooses its compact suffix from the visible compact display decimal plus that exponent.

Output:

one
two
few
other

Format Lists and Relative Time

Use listformat and relativetimeformat for native list and relative-time phrasing:

locales := mustLocaleList("en")

list, err := listformat.New(locales, listformat.Options{
	Type:  listformat.Conjunction,
	Style: listformat.ShortStyle,
})
if err != nil {
	return err
}

relative, err := relativetimeformat.New(locales, relativetimeformat.Options{
	Numeric: relativetimeformat.NumericAuto,
})
if err != nil {
	return err
}

out, err := relative.Format(relativetimeformat.Int(-1), relativetimeformat.Day)
if err != nil {
	return err
}

fmt.Println(list.Format([]string{"red", "green", "blue"}))
fmt.Println(out)

Relative-time values always use ECMAScript Number semantics. Int and Uint are convenience conversions through float64, so integers beyond 2^53 round exactly as native Intl.RelativeTimeFormat; Float preserves negative zero.

Format Durations

Use durationformat for Intl.DurationFormat semantics, including digital time formatting and fractional sub-second rollup. Reuse the formatter for repeated duration output; it resolves its embedded number and list formatters at construction time.

format, err := durationformat.New(mustLocaleList("en"), durationformat.Options{
	Style: gointl.String(durationformat.DigitalStyle),
})
if err != nil {
	return err
}

out, err := format.Format(durationformat.Duration{
	Hours:   1,
	Minutes: 2,
	Seconds: 3,
})
if err != nil {
	return err
}

fmt.Println(out)

Output:

1:02:03

Duration fields are float64 because they mirror ECMAScript Number, but every field must be finite and integral. Formatting projects each field to its exact integer before validation and rollup, so represented values such as 1e20 nanoseconds are not narrowed to int64; fractions, NaN, and infinities return gointl.ErrInvalidValue.

Name Codes, Sort Text, and Segment Strings

Use the remaining constructor packages when you need display names, collation, or text boundaries:

locales := mustLocaleList("en")

names, err := displaynames.New(locales, displaynames.Options{
	Type: gointl.String(displaynames.Region),
})
if err != nil {
	return err
}
region, ok, err := names.Of("FR")
if err != nil {
	return err
}
if ok {
	fmt.Println(region)
}

coll, err := collator.New(locales, collator.Options{})
if err != nil {
	return err
}
words := []string{"z", "a", "ä"}
slices.SortFunc(words, coll.Compare)
fmt.Println(words)

seg, err := segmenter.New(locales, segmenter.Options{
	Granularity: segmenter.WordGranularity,
})
if err != nil {
	return err
}
for part := range seg.Segment("Hello, world.").All() {
	if part.IsWordLike {
		fmt.Println(part.Segment)
	}
}

Supported Data

tools/locale-profile.json defines the CLDR locale profile used by generated number, date, plural, list, relative time, duration, display-name, unit, currency, and time-zone display data. Constructor SupportedLocalesOf methods derive support from the payload family they use, so a locale is advertised only when the backing data or engine can support it.

The default data profile is a curated product shape, not a hidden compatibility matrix: 104 locale tags, CLDR 48.1.0, ICU 78, and IANA tzdata 2025b. Most CLDR-backed constructors share that generated profile. Collator and Segmenter are intentionally engine-specific: Collator follows golang.org/x/text/collate, and Segmenter currently reports only locales whose UAX #29 boundaries do not require dictionary or CJK tailoring. For example, ja, th, and zh-Hant are not advertised by segmenter.SupportedLocalesOf until tailored segmentation lands.

To broaden generated CLDR coverage, add tags to tools/locale-profile.json and run task data. Any profile expansion must also include behavior evidence (task data:contract and task conformance:verify), binary-size evidence (task build:size), and cold-build evidence (task build:size:cold). Selectable build profiles are deliberately absent until repeated host demand proves that a single curated default cannot serve the product.

To check runtime support, call the constructor package's SupportedLocalesOf.

Locale parsing accepts BCP 47 tags through golang.org/x/text/language. Root supported-value accessors return ECMA-402 values: calendars are gregory and iso8601, numbering systems include the simple digit systems from ECMA-402, units come from the sanctioned unit list, currencies come from CLDR, time zones come from the generated IANA/CLDR identifier registry, and collations come from the active collation backend.

DateTimeFormat currently formats Gregorian/ISO calendar data. Well-formed but unsupported calendar requests participate in locale negotiation and fall back to the generated calendar data; malformed calendar identifiers return constructor errors.

DateTimeFormat accepts every named Zone or Link in the pinned IANA registry and matches identifiers using ECMA-402 ASCII-case-insensitive rules. Links such as US/Eastern, Atlantic/Jan_Mayen, and Pacific/Truk resolve to stable primary identifiers. SupportedTimeZones returns the complete primary projection, and Locale.GetTimeZones returns the zone.tab primary identifiers for the locale's explicit region. Localized time-zone names remain CLDR display data; Go's embedded time/tzdata supplies transition bytes.

DateTimeFormat.FormatRange and FormatRangeToParts preserve caller-provided endpoint order. A later first argument is valid and remains startRange; the methods do not silently sort the range.

Known Divergences

go-intl matches observable ECMA-402 output where it can and documents every accepted difference. Two categories exist:

• Typed bridges turn JavaScript dynamic shapes into idiomatic Go signatures. They are intentional and stable.
• Conformance divergences are accepted reference mismatches; each one is enumerated and audited by task conformance:verify.

Typed bridges

Conformance divergences

Per-package accepted mismatches against FormatJS/Node reference output live in <package>/testdata/divergences.md only when that package has an active or resolved divergence history. Do not create or retain empty placeholder divergences.md files. The current active divergence audit is:

• datetimeformat/testdata/divergences.md

Each entry uses the strict id, source, owner, status, reason, optional DateTimeFormat native_witness, review_after, and removal_path fields. Unknown, duplicate, malformed, or incomplete fields fail task conformance:verify; resolved records are validated as history before being excluded from active fixture matching.

Error Handling

Constructors and formatter methods return errors that work with the root sentinels in github.com/agentable/go-intl. Most caller-fixable failures also carry *gointl.Error, which is useful for config UIs, API errors, and host bindings that need stable machine-readable context. The human error string uses an expected ...; got ... shape and omits internal ECMA-402 abstract-operation names.

gointl.ErrUnsupportedOption also matches errors.ErrUnsupported.

_, err := numberformat.New(mustLocaleList("en-US"), numberformat.Options{
	Style: gointl.String(numberformat.CurrencyStyle),
})
if err != nil {
	if errors.Is(err, gointl.ErrInvalidOption) {
		if detail, ok := errors.AsType[*gointl.Error](err); ok {
			return fmt.Errorf("fix %s %s=%q (expected %s): %w",
				detail.Owner, detail.Name, detail.Value, detail.Expected, err)
		}
		return fmt.Errorf("fix formatter options: %w", err)
	}
	return err
}

Error.Kind is one of invalidOption, unsupportedOption, invalidValue, or invalidCode. Error.Expected is optional; when it is empty, Error() still derives generic expected-value guidance from the error kind and field name. The wrapped sentinel remains the source of truth for branching with errors.Is.

Development

Development guidance for coding agents lives in CLAUDE.md, with AGENTS.md kept as the same entrypoint.

task deps                 # Download modules and tidy go.mod/go.sum
task fmt                  # Format Go code
task vet                  # Run go vet
task test                 # Run go test -race -p 1 ./...
task lint                 # Run go mod tidy check and golangci-lint
task codegraph:source        # Build a source-only CodeGraph mirror under .tmp/codegraph-source
task codegraph:source:status # Verify mirror/worktree sync, then show CodeGraph index status
task codegraph:source:sync-check # Verify source-only mirror matches the current worktree
task conformance:verify   # Validate fixtures, skip-list, coverage, Node witness matrix, and divergence audit
task conformance:witness  # Refresh generated Node Intl witness fixtures with the active node binary
task data                 # Regenerate CLDR data into internal/cldr/ (writes back)
task data:check           # Regenerate/compare CLDR data and run gen-cldr test/vet
task data:contract        # Verify generated CLDR data contracts
task build:size           # Report root, formatter, and CLDR binary size deltas
task build:size:cold      # Report the same size table after clearing Go's build cache
task bench:run            # Run one-shot benchmark telemetry
task bench                # Produce a non-blocking benchmark report, optionally with BASELINE=<file>
task vuln                 # Run govulncheck
task verify               # Run deps, fmt, vet, lint, test, conformance, data contract, and vuln checks

The host consumer profile is exercised by go test ./...; it protects supported-set boundaries and reversed range behavior that host integrations depend on.

Use task codegraph:source before structural exploration. The generated mirror excludes .references/ and lives under ignored .tmp/codegraph-source, so current-source questions do not accidentally traverse the vendored reference trees. task codegraph:source:status checks that the mirror still matches the working tree before reporting the CodeGraph index status; use task codegraph:source:sync-check when you only need the mirror freshness check. Reference projects keep their own CodeGraph indexes when a comparison needs implementation evidence.

Measure aggregate root facade cost separately from per-surface formatter cost. Treat go list -deps . as root aggregate evidence only; use direct subpackage commands for single-formatter dependency measurements.

go list -deps . | wc -l
go list -deps ./numberformat | wc -l
go list -deps ./datetimeformat | wc -l
task build:size  # CLDR linker smoke for generated data changes
task build:size:cold  # CLDR cold-build smoke for profile changes

For binary-size checks, label root facade harnesses separately from formatter-only harnesses.

Run a targeted package while developing:

go test -race ./numberformat/...
go test -race -run TestPluralRules_Cardinal/en ./pluralrules/
(cd tools/gen-cldr && go test ./...)
(cd tools/gen-cldr && go vet ./...)
(cd tools/gen-plural-rules && go test ./...)
(cd tools/gen-plural-rules && go vet ./...)
(cd tools/gen-fixtures-from-formatjs && go test ./...)
(cd tools/gen-fixtures-from-formatjs && go vet ./...)
go test ./tools/conformance ./tools/check-conformance

Documentation

• SPECS record public contracts, formatter behavior, data layout, and conformance rules.
• CLAUDE.md defines development workflow and repository conventions for AI coding agents.

Contributing

Open an issue before changing public behavior. Keep README changes focused on installation, usage, examples, and development commands; put contracts in SPECS/ and agent workflow rules in CLAUDE.md and the AGENTS.md symlink.

License

This project is licensed under the MIT License - see the LICENSE file for details.