langtag

package module
v1.0.5 Latest Latest
Warning

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

Go to latest
Published: Aug 19, 2026 License: Apache-2.0 Imports: 3 Imported by: 1

README

langtag

Go Reference Go version Test coverage Mutation OpenSSF Best Practices OpenSSF Scorecard

May this language track stand in for the one that was asked for, and how far a substitution is that

Software that stores a language choice a person made will eventually meet content tagged differently. A viewer picks a subtitle tagged nob on one episode, the next episode carries only nor, and string equality reports no match even though both name Norwegian Bokmål.

langtag canonicalizes language identifiers from any published code system onto one BCP 47 form, then grades the distance between what was wanted and what is available on a five-step scale. The only runtime dependency is golang.org/x/text.

Install

go get github.com/cplieger/langtag@latest

Usage

package main

import (
	"fmt"

	"github.com/cplieger/langtag"
)

type subtitle struct {
	file string
	lang langtag.Tag
}

func main() {
	available := []subtitle{
		{"ep2.eng.srt", langtag.MustParse("eng")},
		{"ep2.nor.srt", langtag.MustParse("nor")},
		{"ep2.swe.srt", langtag.MustParse("swe")},
	}

	want, ok := langtag.Parse("nob") // what the viewer chose on episode 1
	if !ok {
		return
	}

	matches, tier, ok := langtag.Best(want, available,
		func(s subtitle) langtag.Tag { return s.lang },
		langtag.TierSameLanguage)
	if !ok {
		fmt.Println("nothing close enough")
		return
	}
	fmt.Println(matches[0].file, "at tier", tier) // ep2.nor.srt at tier same-language
}

Parsing

Parse accepts ISO 639-1, ISO 639-2 in either the bibliographic or terminological variant, ISO 639-3, and BCP 47 tags, in any letter case, with surrounding whitespace. It returns ok == false rather than an error, because ignoring the tag is the only available recovery.

Canonicalization collapses the code systems that spell one language several ways:

Input Canonical Language
ger, deu, de de de
chi, zho, zh zh zh
iw he he
nor, no no no
nob, nb nb no
cmn cmn zh

Tag.Language reports the primary subtag after macrolanguage folding, so nob and nor share the language no while keeping distinct tags. That value is the right key for a cache or a learned-preference map, because it does not fragment across spellings.

These inputs are rejected: the empty string, the placeholder subtags that name no language (und, zxx, mul, mis), private-use subtags (qaa through qtz), and anything the IANA Language Subtag Registry does not know. Variant and extension subtags (-u-, -t-, -x-, and forms like ca-valencia) are discarded, because none of them changes which language a track is in.

The zero Tag matches nothing, including another zero Tag. Two tracks both labelled "undetermined" are not known to share a language.

Tiers

Compare(want, have) reports how far the available language sits from the wanted one. A caller passes the highest tier it will accept as a floor.

The order is by kind of license, from narrowest to widest, not by reading difficulty. Reading difficulty is not monotonic along it, and TierOtherScript is where that bites. CLDR scores a generic same-language cross-script substitution at 50, farther than every pair on the two tiers above it, so accepting other-script is a bigger ask for Chinese content than accepting intelligible is for Norwegian.

The script pairs CLDR does explicitly rate as close sit on the tier below instead, so what remains on other-script is the set CLDR does not vouch for. See Close scripts.

Close scripts

A script difference is normally farther than a region difference. A few languages are written in two scripts whose readers are taught both, where it is no barrier at all, and those sit at TierSameLanguage.

Membership is derived rather than judged. CLDR names only a handful of same-language script pairs against its generic 50, and all but one are one-way transliteration rows (ja-Latn onto ja-Jpan, hi-Latn onto hi-Deva, and the other Latin romanizations). A romanization feeding its native script is not two audiences reading each other, which is the same reason a one-way language relation is shared literacy rather than interchangeability. One symmetric pair remains:

Language Scripts Why Provenance
sr Latn and Cyrl Serbian is written in both and Serbian schooling teaches both CLDR distance 5, symmetric, against a generic 50

CloseScripts returns the list. Unlike the cross-language table it is not replaceable, because it records where CLDR states an explicit symmetric distance rather than a judgment about people. A caller that wants a script difference treated as a barrier regardless floors at same-language.

Deliberately absent: Simplified against Traditional Chinese, which CLDR does not name and which therefore sits at the generic 50; and uz-Latn against uz-Cyrl and az-Latn against az-Cyrl, which x/text's stale snapshot rates as close but upstream CLDR does not name either.

Tier Meaning Examples
TierIdentical The same language, the same canonical tag ger and deu, nor and no, iw and he
TierSameLanguage One language a reader takes in without effort nob and nor, cmn and zh, es-ES and es-419, sr-Latn and sr-Cyrl
TierOtherScript One language in a script its readers are not taught alongside zh-Hans and zh-Hant, uz-Latn and uz-Cyrl
TierIntelligible Two different languages that are close enough to read across nb and nn, no and da, hr and bs, cs and sk
TierSharedLiteracy A different language readers use because they are broadly literate in it ca to es
TierNone No relationship worth acting on no and sv, hi and ur, pl and cs, gl and es

The first three tiers follow from published standards data and hold no opinion. The two above them are curated judgments, and they are separate tiers because they make different claims. TierIntelligible says two languages are close enough that readers move between them, which is a symmetric property of the languages. TierSharedLiteracy says only that readers of one are, as a population, literate in the other, which is a one-way fact about people and licenses a substitution to a possibly unrelated language. Accepting the first does not accept the second.

Compare is not commutative. Cross-language relationships are directed, so the argument order matters: want is the language a person chose, have is what the content offers. A Catalan viewer accepts a Spanish track; a Spanish viewer does not accept a Catalan one.

The cross-language table

Five shipped relationships, each a claim about people rather than about code, each one arguable. Fallbacks returns the table and Reason returns the justification for a given pair, so a surprised user can be shown why a substitution happened.

Wanted Accepted Kind Both ways Why
no nn intelligible yes Bokmål and Nynorsk are the two written standards of Norwegian; Norwegian schooling teaches both
no da intelligible yes Written Bokmål derives from Danish and the two remain close on the page
hr bs intelligible yes Croatian and Bosnian are mutually intelligible and share the Latin script
cs sk intelligible yes Czech and Slovak are mutually intelligible in writing
ca es shared-literacy no Catalonia is officially bilingual and Spanish is compulsory in schooling

Entries name languages the way Tag.Language reports them, so one entry covers every spelling: a wanted language of no answers for nor, nob, no and nb alike.

The Kind decides the tier, and it has to agree with the direction. An interchangeability claim runs both ways, because that is what the claim means. A shared-literacy claim runs one way, because a majority-language population does not reciprocate. A test enforces both, so an entry cannot make the weaker claim under the stronger name.

Every entry also carries a Provenance field naming where the claim can be re-checked, which for all five is CLDR's languageInfo.xml.

WithFallbacks replaces the table for a deployment that disagrees, and WithFallbacks(nil) disables both cross-language tiers. A malformed entry is dropped rather than accommodated, so a mistake in a table removes a substitution instead of licensing an unintended one, and ValidateFallbacks reports what was dropped and why. When two entries claim one ordered pair at different tiers, the farther tier wins, so table order cannot decide how close a pair is.

TierNone is not a usable floor. It means "no relationship", so accepting it would accept every language as a substitute for every other. Match and Best therefore report nothing for a floor at TierNone or beyond, which matters because that is also what ParseTier returns for a value it does not recognise: a mistyped configuration setting matches nothing rather than everything.

A note on verifying these claims

golang.org/x/text embeds a CLDR snapshot old enough to disagree with upstream: its matcher does not know cs/sk or ca/es, and still carries a mk/bg relation that CLDR has since retired. So the reference for whether upstream carries a relation, in which direction, and at what distance, is languageInfo.xml itself, never the library's matcher. This package uses x/text only for parsing and canonicalization, which come from the IANA Language Subtag Registry and are not affected.

What this package will not do

It will not substitute an unrelated language at the intelligible tier or below. CLDR's distance data rates Basque against Spanish, Welsh against English, Tamil against English and Belarusian against Russian as close, because those populations are broadly literate in the second language. That is accurate sociolinguistics and a poor default: a viewer who chose Tamil subtitles did not ask for English ones.

Claims of that shape live at TierSharedLiteracy, alone, named for what they are, and reachable only by asking for that tier specifically. The table ships one such entry. Extending it to the rest of the family is a decision for whoever runs the software, through WithFallbacks, rather than a default anybody inherits.

Everything below that tier is structural. Tiers 0 through 2 cannot express a cross-language relationship at all, and the intelligible tier is a hand-curated symmetric set, so no amount of loosening a floor short of shared-literacy can reach an unrelated language. Tests enumerate 33 such pairs and assert every one stays at TierNone at every floor.

Also absent, deliberately: collation, formatting, content negotiation, Accept-Language parsing, and any numeric distance between tiers (a number invites arithmetic across steps that are not commensurable). Display names live in the optional langtag/name subpackage, kept separate because its CLDR tables add roughly 2.5 MB to a binary.

Written, not spoken

Every cross-language entry is a claim about reading. Danish and Norwegian are close on the page and much further apart aloud, which is the clearest case. Software matching an audio track should stop at TierOtherScript or below; the tiers above it are subtitle-grade claims and this package cannot tell which kind of track a caller is matching.

Adding to the table

A missing entry means a track is left alone, which is what a caller had before adopting this package. A wrong entry means a library silently rewritten into a language nobody asked for. The two failure modes are not symmetric, so the table grows on request rather than on inference.

Open an issue naming the two languages, the direction, whether it holds both ways, and why a reader of the first can use the second. Two things disqualify a proposal. Anything derivable from macrolanguage folding, script or region is already tiers 0 to 2 and needs no entry. And a one-way claim is shared literacy rather than interchangeability, whatever its distance, so it belongs on the upper tier and inherits that tier's opt-in.

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md for the conventions and how to run the checks locally.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package langtag answers one question: may this language track stand in for the one that was asked for, and how far a substitution is that.

The question comes up whenever software holds a language choice a person made and then meets content tagged differently. A media library is the motivating case: a viewer selects a subtitle tagged "nob" on one episode, the next episode carries only "nor", and string equality reports no match even though both name Norwegian Bokmål.

Tags are structured, not opaque

Language identifiers arrive from files, transcoders and third-party APIs in every code system ever published: ISO 639-1 two-letter codes, both the bibliographic and terminological ISO 639-2 variants, ISO 639-3, and BCP 47 tags with script and region subtags. Parse canonicalizes all of them onto one BCP 47 form, so the twenty ISO 639-2 duplicate pairs (ger/deu, fre/fra, chi/zho and the rest) and the deprecated codes (in, iw, ji) stop being distinct identities.

Distance is graded, not binary

Compare reports a Tier: how far a candidate sits from what was wanted. Tiers 0 through 2 are derived from published standards data. The two above them are curated judgments, split because they make different claims: TierIntelligible says two languages are close enough to read across, and TierSharedLiteracy says only that readers of one are broadly literate in the other. A caller sets a floor and nothing beyond it is a match.

want, _ := langtag.Parse("nob")
have, _ := langtag.Parse("nor")
langtag.Compare(want, have) // TierSameLanguage

What this package deliberately will not do

It will not substitute an unrelated language at the intelligible tier or below. CLDR's own distance data rates Basque against Spanish, Welsh against English and Tamil against English as close, because those populations are broadly literate in the second language. That is accurate sociolinguistics and a poor default: a viewer who chose Tamil subtitles did not ask for English ones. Claims of that shape live at TierSharedLiteracy alone, named for what they are, and the table ships one of them.

Every cross-language entry is a claim about reading. Danish and Norwegian are close on the page and much further apart aloud. Software matching an audio track should stop at TierOtherScript; this package cannot tell which kind of track a caller is matching.

It is not a general internationalization library. There is no collation, no formatting and no content negotiation. Display names live in the optional subpackage langtag/name, which is separate because its CLDR tables add roughly 2.5 MB to a binary.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Match

func Match(want, have Tag, floor Tier) bool

Match reports whether have is an acceptable stand-in for want at or within floor, using the built-in table.

TierNone is not a usable floor and always reports false, in either position. It means "no relationship", so accepting it as a floor would accept every language as a substitute for every other. That matters because it is also what ParseTier returns for input it does not recognise: a mistyped configuration value therefore matches nothing rather than everything.

Example

A floor keeps a caller from reaching further than it intends.

package main

import (
	"fmt"

	"github.com/cplieger/langtag"
)

func main() {
	want := langtag.MustParse("zh-Hans")
	have := langtag.MustParse("zh-Hant")
	fmt.Println("at same-language:", langtag.Match(want, have, langtag.TierSameLanguage))
	fmt.Println("at other-script: ", langtag.Match(want, have, langtag.TierOtherScript))
}
Output:
at same-language: false
at other-script:  true

func Reason

func Reason(want, have Tag) (string, bool)

Reason returns the recorded justification for a cross-language substitution under the built-in table. See Comparer.Reason.

Example

Reason explains a tier-3 substitution, so a surprised user can be told why.

package main

import (
	"fmt"

	"github.com/cplieger/langtag"
)

func main() {
	reason, ok := langtag.Reason(langtag.MustParse("nb"), langtag.MustParse("da"))
	fmt.Println(ok)
	fmt.Println(reason)
}
Output:
true
Written Bokmål derives from Danish and the two remain close on the page. This is a written-language claim only; the spoken languages are much further apart.

func Valid

func Valid(raw string) bool

Valid reports whether raw names a language. Intended for validating configuration at load time, so that a typo fails loudly at startup instead of silently matching nothing forever.

func ValidateFallbacks added in v1.0.2

func ValidateFallbacks(f []Fallback) []error

ValidateFallbacks reports why each rejected entry in f was rejected, in order, and returns nil when every entry is usable. WithFallbacks drops the same entries silently, because a table is configuration rather than a runtime input; this is the way to find out what it dropped.

Types

type CloseScript added in v1.0.4

type CloseScript struct {
	// Language is the primary subtag after macrolanguage folding.
	Language string
	// A and B are the ISO 15924 script codes, in either order.
	A, B string
	// Reason states why readers move between them.
	Reason string
	// Provenance records where the claim can be re-checked.
	Provenance string
}

CloseScript is a pair of scripts that one language's readers move between freely, so a difference between them is not a barrier the way a script difference usually is.

This is a narrow escape hatch from the structural rule that a script difference is farther than a region difference. That rule is right in general and wrong for a handful of languages written in two scripts whose readers are taught both.

func CloseScripts added in v1.0.4

func CloseScripts() []CloseScript

CloseScripts returns a copy of the built-in list of script pairs that read as one language.

Unlike Fallbacks, this list is not replaceable. It records where CLDR states an explicit symmetric distance for a script pair, which is a fact about the data rather than a judgment about people, so a deployment has nothing to disagree with. A caller that wants a script difference treated as a barrier anyway floors at TierSameLanguage and gets that.

type Comparer

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

Comparer answers tier questions against a specific fallback table. Use it when the built-in cross-language judgments do not suit the deployment; the package-level Compare, Match and Best use the built-in table.

A Comparer is immutable after construction and safe for concurrent use.

func Default

func Default() *Comparer

Default returns the Comparer backed by the built-in table.

func WithFallbacks

func WithFallbacks(f []Fallback) *Comparer

WithFallbacks returns a Comparer using the supplied cross-language table instead of the built-in one. Passing nil or an empty slice disables both cross-language tiers, so no substitution beyond TierOtherScript can occur at any floor.

Entries name languages as Tag.Language reports them, so "no" rather than "nb" or "nor". An entry naming anything else simply never matches.

Malformed entries are DROPPED rather than accommodated, so a table authoring mistake removes a substitution instead of licensing an unintended one. See ValidateFallbacks to find out which entries were rejected and why. An entry is malformed when it names no language on either side, names one language on both, carries no Kind, or claims a Kind that disagrees with its direction.

Example

A deployment that disagrees with a shipped judgment replaces the table instead of forking the package. Passing nil disables tier 3 outright.

package main

import (
	"fmt"

	"github.com/cplieger/langtag"
)

func main() {
	strict := langtag.WithFallbacks(nil)
	nb, nn := langtag.MustParse("nb"), langtag.MustParse("nn")
	fmt.Println("built-in:", langtag.Compare(nb, nn))
	fmt.Println("no table:", strict.Compare(nb, nn))
}
Output:
built-in: intelligible
no table: none

func (*Comparer) Compare

func (c *Comparer) Compare(want, have Tag) Tier

Compare reports how far the available tag have sits from the wanted tag want. See the package-level Compare for the argument-order contract.

func (*Comparer) Match added in v1.0.3

func (c *Comparer) Match(want, have Tag, floor Tier) bool

Match reports whether have is an acceptable stand-in for want at or within floor, under this Comparer's table. See the package-level Match for the floor contract, which is identical: a floor of TierNone or beyond always reports false.

func (*Comparer) Reason

func (c *Comparer) Reason(want, have Tag) (string, bool)

Reason returns the recorded justification for a cross-language substitution, and ok=false when the pair is not one. Intended for explaining a surprising choice in a log line or a user-facing message.

type Fallback

type Fallback struct {
	// Want is the language subtag a reader asked for.
	Want string
	// Have is the language subtag they can use instead.
	Have string
	// Reason states why a reader of Want can use Have. It exists so that an
	// entry cannot be added without an argument, and so that a surprised user
	// can be shown one.
	Reason string
	// Provenance records where the claim comes from, so a later maintainer can
	// re-check it rather than inheriting it on trust.
	Provenance string
	// Kind decides the tier, and must agree with Both: an interchangeability
	// claim runs both ways, a shared-literacy claim runs one way.
	Kind Kind
	// Both records that the relationship holds in the reverse direction too.
	Both bool
}

Fallback is one directed cross-language relationship: a reader who wants the language Want can use a track in the language Have.

Want and Have are primary language subtags after macrolanguage folding, the value Tag.Language reports. One entry therefore covers every spelling of the languages it names: a Want of "no" answers for nor, nob, no and nb alike, and no second entry is needed for the umbrella tag.

func Fallbacks

func Fallbacks() []Fallback

Fallbacks returns a copy of the built-in table, so that a caller can read the shipped judgments, and amend a copy, without being able to mutate the package's own.

type Kind added in v1.0.1

type Kind uint8

Kind separates the two different claims a cross-language fallback can make. It decides which tier an entry lands on, so that a caller can accept one kind of substitution without accepting the other.

const (
	// KindUnset is the zero value, and it is not a usable Kind. An entry must
	// name its kind, because the two kinds land on different tiers and the
	// weaker claim must never inherit the stronger tier by default. Entries
	// carrying KindUnset are dropped by [WithFallbacks].
	KindUnset Kind = iota

	// Intelligible means the two languages are close enough that readers move
	// between them. Such a relationship runs both ways.
	Intelligible

	// SharedLiteracy means readers of the wanted language are, as a population,
	// literate in the other one, which may be entirely unrelated. Such a
	// relationship runs one way: the majority-language population does not
	// reciprocate.
	SharedLiteracy
)

func (Kind) String added in v1.0.1

func (k Kind) String() string

String returns the name of the kind.

func (Kind) Tier added in v1.0.1

func (k Kind) Tier() Tier

Tier returns the tier an entry of this Kind produces. An unset or unknown Kind yields TierNone, so a malformed entry can never license a substitution.

type Tag

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

Tag is a canonical BCP 47 language tag that names an actual language.

The zero Tag is invalid: it is what Parse returns for input that names no language, and it matches nothing at any tier, including another zero Tag. Two tracks both tagged "undetermined" are not known to share a language.

Tag holds only strings, so it is comparable, copyable and carries no reference to the parsing library in its public shape.

func MustParse

func MustParse(raw string) Tag

MustParse is Parse for identifiers fixed at compile time. It panics when raw does not name a language, so it belongs in package-level tables and tests, never on a path that handles input.

func Parse

func Parse(raw string) (Tag, bool)

Parse canonicalizes one raw language identifier from an untrusted source.

It accepts ISO 639-1, ISO 639-2 (bibliographic or terminological), ISO 639-3 and BCP 47 tags, in any letter case, with surrounding whitespace. ok is false, and the returned Tag is the zero Tag, for the empty string, for the placeholder subtags that name no language (und, zxx, mul, mis), for private-use subtags (qaa through qtz), and for anything the IANA Language Subtag Registry does not know.

Parse never reports an error value. Callers act on ok; there is no recovery from a malformed tag beyond ignoring it, and every call site would otherwise discard the error.

Example

One language spelled two ways is one language.

package main

import (
	"fmt"

	"github.com/cplieger/langtag"
)

func main() {
	for _, raw := range []string{"ger", "deu", "de", "nob", "nor"} {
		tag, _ := langtag.Parse(raw)
		fmt.Printf("%-4s -> tag %-3s language %s\n", raw, tag, tag.Language())
	}
}
Output:
ger  -> tag de  language de
deu  -> tag de  language de
de   -> tag de  language de
nob  -> tag nb  language no
nor  -> tag no  language no

func (Tag) IsZero

func (t Tag) IsZero() bool

IsZero reports whether t names no language. Every comparison involving a zero Tag yields TierNone.

func (Tag) Language

func (t Tag) Language() string

Language returns the primary language subtag after macrolanguage folding: "no" for both nob and nor, "zh" for both cmn and zho. Two tags share a language exactly when this value matches. It is the right key for a per-language cache or a learned-preference map, because it does not fragment across the code systems that name one language several ways.

func (Tag) Script

func (t Tag) Script() string

Script returns the ISO 15924 script code, resolved to CLDR's default for the language when the tag itself does not state one.

func (Tag) String

func (t Tag) String() string

String returns the canonical BCP 47 form, or the empty string for the zero Tag.

type Tier

type Tier uint8

Tier is how far an available language sits from the one that was wanted. A caller picks the highest tier it will accept as a floor.

The order is by KIND OF LICENSE, from narrowest to widest: the same tag, then the same language, then the same language in another script, then a close language, then a language readers merely happen to be schooled in. It is deliberately NOT a reading-difficulty scale, and reading difficulty is not monotonic along it. TierOtherScript is where that shows: what remains on it is the script pairs CLDR does not explicitly rate, which it scores at 50, farther than any pair on the two tiers above. A caller serving Chinese content should weigh that before accepting TierOtherScript.

Tiers 0 through 2 follow from published standards data and hold no opinion. The two tiers above them are curated judgments, and they are separated because they make different kinds of claim: TierIntelligible says two languages are interchangeable, while TierSharedLiteracy says only that readers of one are, as a population, literate in the other. The second is a much weaker claim and the substitution it licenses is a different language entirely, so reaching it takes its own opt-in.

const (
	// TierIdentical means the two tags canonicalize to the same thing. It
	// covers the code systems that spell one language several ways: nor and
	// no, ger and deu, chi and zho, iw and he.
	TierIdentical Tier = iota

	// TierSameLanguage means one language a reader takes in without effort. It
	// covers macrolanguage folding (nob against nor, cmn against zho), regional
	// variants (es-ES against es-419, pt-BR against pt-PT, en-GB against en-US),
	// and the script pairs whose readers are taught both, which is Serbian
	// Latin against Serbian Cyrillic (see [CloseScripts]).
	TierSameLanguage

	// TierOtherScript means one language in a script its readers are NOT
	// generally taught alongside: Simplified against Traditional Chinese,
	// uz-Latn against uz-Cyrl. Readers of one usually manage the other, with
	// effort. The pairs CLDR explicitly rates as close sit on the tier below
	// instead, so what remains here is the set CLDR does not vouch for, which
	// it scores at 50 against 4 to 20 for every curated close-language pair.
	// That is why this tier can be a bigger ask than the two above it.
	TierOtherScript

	// TierIntelligible means two different languages that readers move between
	// because the languages themselves are close: Bokmål and Nynorsk, Danish
	// and Norwegian, Croatian and Bosnian, Czech and Slovak. The relationship
	// runs both ways, which is the mark of interchangeability rather than of
	// one population's schooling.
	//
	// These are written-language claims. Two languages readable to each other
	// on the page are not necessarily comprehensible to each other aloud, and
	// Danish against Norwegian is exactly that case. A caller matching audio
	// should not reach this tier.
	TierIntelligible

	// TierSharedLiteracy means a different, not necessarily related language
	// that readers of the wanted one can use because they are broadly literate
	// in it. Catalan readers read Spanish. The relationship runs one way only,
	// and the two languages may be unrelated.
	//
	// This tier exists so the claim can be made honestly and separately rather
	// than smuggled in beside interchangeability. It is never reached unless a
	// caller asks for it by name, and the table ships one entry: extending it
	// to the rest of the family is a decision for whoever runs the software,
	// through [WithFallbacks].
	TierSharedLiteracy

	// TierNone means no relationship worth acting on. It is also the answer
	// whenever either tag is the zero Tag.
	TierNone
)

func Best

func Best[T any](want Tag, candidates []T, tagOf func(T) Tag, floor Tier) (out []T, tier Tier, ok bool)

Best returns the candidates closest to want and the tier they matched at, using the built-in table. See BestWith.

Example

Best selects from a caller's own type and returns every candidate at the closest tier, leaving the final choice to whatever the caller ranks by.

package main

import (
	"fmt"

	"github.com/cplieger/langtag"
)

func main() {
	type subtitle struct {
		file  string
		codec string
		lang  langtag.Tag
	}
	available := []subtitle{
		{"ep2.eng.srt", "srt", langtag.MustParse("eng")},
		{"ep2.nor.ass", "ass", langtag.MustParse("nor")},
		{"ep2.nor.srt", "srt", langtag.MustParse("nor")},
		{"ep2.swe.srt", "srt", langtag.MustParse("swe")},
	}
	want := langtag.MustParse("nob") // the viewer chose Bokmål on episode 1

	matches, tier, ok := langtag.Best(want, available,
		func(s subtitle) langtag.Tag { return s.lang },
		langtag.TierSameLanguage)
	if !ok {
		fmt.Println("no usable subtitle")
		return
	}
	fmt.Printf("matched at tier %s:\n", tier)
	for _, m := range matches {
		fmt.Printf("  %s (%s)\n", m.file, m.codec)
	}
}
Output:
matched at tier same-language:
  ep2.nor.ass (ass)
  ep2.nor.srt (srt)

func BestWith

func BestWith[T any](c *Comparer, want Tag, candidates []T, tagOf func(T) Tag, floor Tier) (out []T, tier Tier, ok bool)

BestWith returns every candidate at the closest tier reached, the tier itself, and whether anything was within floor.

All returned candidates share one tier, because the caller is expected to rank within a language by criteria this package knows nothing about: codec, forced and hearing-impaired flags, track title, provider score. Input order is preserved so an existing tie-break stays deterministic.

tagOf extracts the language from a candidate, which lets a caller pass its own type without building a parallel slice and mapping indices back. A candidate whose tag is the zero Tag never matches.

A floor of TierNone or beyond selects nothing, and does NOT widen to the most permissive tier. An unrecognised configuration value parses to TierNone (see ParseTier), and the safe reading of an unusable floor is that no substitution was authorised, not that every substitution was.

func Compare

func Compare(want, have Tag) Tier

Compare reports how far the available tag have sits from the wanted tag want, using the built-in table.

The argument order is load-bearing. Cross-language entries are directed, so Compare(want, have) and Compare(have, want) can differ: a Catalan viewer accepts a Spanish track, and a Spanish viewer does not accept a Catalan one. want is always the language a person chose; have is what the content offers.

Example

Compare grades the distance rather than answering yes or no.

package main

import (
	"fmt"

	"github.com/cplieger/langtag"
)

func main() {
	want := langtag.MustParse("nob")
	for _, raw := range []string{"nob", "nor", "nn", "sv"} {
		have := langtag.MustParse(raw)
		fmt.Printf("a viewer wanting nob, offered %-4s: %s\n", raw, langtag.Compare(want, have))
	}
}
Output:
a viewer wanting nob, offered nob : identical
a viewer wanting nob, offered nor : same-language
a viewer wanting nob, offered nn  : intelligible
a viewer wanting nob, offered sv  : none
Example (Directed)

Tier-3 relationships are directed, because shared literacy usually runs one way: Catalan readers read Spanish, and Spanish readers do not read Catalan.

package main

import (
	"fmt"

	"github.com/cplieger/langtag"
)

func main() {
	ca, es := langtag.MustParse("ca"), langtag.MustParse("es")
	fmt.Println("wanting ca, offered es:", langtag.Compare(ca, es))
	fmt.Println("wanting es, offered ca:", langtag.Compare(es, ca))
}
Output:
wanting ca, offered es: shared-literacy
wanting es, offered ca: none

func ParseTier

func ParseTier(s string) (Tier, bool)

ParseTier maps a configuration string onto a Tier. It accepts the spellings String produces, in any letter case, plus the underscore form so that an operator who writes same_language is not punished for it. ok is false for anything else, and for "none", which is not a usable floor: a floor of TierNone would accept every language as a substitute for every other.

func (Tier) String

func (t Tier) String() string

String returns the configuration spelling of the tier.

Jump to

Keyboard shortcuts

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