langtag

package
v0.3.6 Latest Latest
Warning

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

 Go to latest Published: Nov 9, 2026 License: GPL-3.0 Imports: 4 Imported by: 0

Documentation

Overview

Package langtag is the single shared language-tag helper for Ether.

It exists so subtitles, trackprefs, plex and the transcode probes do not drift apart with private copies of the same normalisation: a tag is parsed as BCP 47 (primary, optional script, optional region), folded to a canonical comparable form, and matched by tier.

Index

Constants

View Source 
const (
	RankNoMatch         = 0
	RankRegionalVariant = 2 // Different region of same language with no script conflict (e.g. es-419 × es-ES, fr-CA × fr-FR)
	RankBareCandidate   = 3 // Regional/scripted want matched against a bare primary track (e.g. es-419 × es, pt-BR × pt)
	RankMatchingSubtag  = 4 // Generic want × regional/scripted track, or matching script/region when one side is more specific
	RankExact           = 5 // Exact primary + script + region match (including implied Chinese script/region pairs)
)

Extended BCP-47 match ranks returned by MatchRank (higher is better, 0 = no match).

View Source 
const (
	RoleMain        = "main"
	RoleCommentary  = "commentary"
	RoleDescription = "description"
)

Stream role constants returned by TrackRole.

Variables

This section is empty.

Functions

func BestStreamMatchRank 

func BestStreamMatchRank(want, streamLang, streamTitle string) int

BestStreamMatchRank returns the highest MatchRank(want, candidate) across a stream's EffectiveLanguages(streamLang, streamTitle).

func CanonicalBCP47 

func CanonicalBCP47(raw string) string

CanonicalBCP47 returns the normalized BCP-47 string preserving script and region subtags across all languages (e.g. "es-419", "fr-CA", "sr-Latn", "pt-BR", "zh-Hant-TW").

func EffectiveLanguages 

func EffectiveLanguages(lang, title string) []string

EffectiveLanguages returns the effective BCP-47 language tag(s) for a stream given its container Language tag and stream Title:

  • If lang is empty, "und", or "mul", it falls back to ParseLanguages(title).
  • If lang is a bare primary tag (e.g. "spa"/"es", "por"/"pt", "fre"/"fr") and title advertises a regional/script variant of that same primary (e.g. "Español Latino" -> "es-419"), the specific tag is returned first.
  • Otherwise, CanonicalBCP47(lang) is returned.

func InferMultiAudioLanguages 

func InferMultiAudioLanguages(streams []StreamLangInput, releaseLanguages []string) []string

InferMultiAudioLanguages infers the missing language of a single untagged main-dialogue audio stream when a multi-language release advertises English plus exactly one non-English language and the other main audio stream(s) are already identified as English. It returns a slice parallel to streams with an inferred BCP-47 code for that stream (and "" for all others).

func MatchRank 

func MatchRank(want, candidate string) int

MatchRank scores how well a candidate track tag satisfies a wanted language preference using full BCP-47 primary, script, and region subtags across all languages (higher is better, 0 = incompatible):

  • 5 (RankExact): Exact match on primary + effective script + effective region (e.g. es-419 × es-419, sr-Latn × sr-Latn, zh-TW × zh-Hant-TW, en × eng).
  • 4 (RankMatchingSubtag): Generic want × regional/scripted track (es × es-419, pt × pt-BR), or matching script/region when one side is more specific (sr-Latn × sr-Latn-RS, zh-Hant × zh-Hant-HK).
  • 3 (RankBareCandidate): Regional/scripted want × bare primary candidate (es-419 × es, pt-BR × por, sr-Latn × sr, zh-TW × zh).
  • 2 (RankRegionalVariant): Sibling region with no script conflict (es-419 × es-ES, fr-CA × fr-FR, en-GB × en-US). Portuguese (pt-BR vs pt-PT) and Chinese (zh-CN vs zh-TW) remain 0 because viewers treat them as distinct languages.
  • 0 (RankNoMatch): Different primary language, empty/undetermined tag, or conflicting script (sr-Latn × sr-Cyrl, zh-Hans × zh-Hant, uz-Latn × uz-Cyrl).

func MatchTier 

func MatchTier(want, track string) int

MatchTier scores a wanted language against a track language, both normalised with Normalize:

  • 3: exact (pt-br × pt-br, pt × pt, por × pt after normalising);
  • 2: generic want × regional track (pt × pt-br, zh × zh-tw) — a generic preference accepts any region of the language;
  • 1: regional want × generic track (pt-br × pt, zh-tw × zh) — accepted, but weak: it never beats tier 3 or 2 for the same want;
  • 0: different languages, regions that differ (pt-br × pt-pt, zh-cn × zh-tw), or an empty/invalid side.

Because only pt/zh keep a region after normalising, script is never mistaken for region here: zh-TW × zh-Hant-TW both fold to zh-tw (3).

func Normalize 

func Normalize(tag string) string

Normalize folds a language tag to its canonical comparable form: the primary subtag, plus the region only for Portuguese and Chinese (pt-br vs pt-pt and zh-cn vs zh-tw are distinct languages to every consumer; en-GB and en-US are not). The script is discarded, except that for Chinese a script without an explicit region implies one by convention: zh-Hans -> zh-cn, zh-Hant -> zh-tw (an explicit region always wins: zh-Hant-CN -> zh-cn). "pob" folds to "pt-br", ISO 639-2 primaries to ISO 639-1, and empty, invalid or undetermined tags to "".

func ParseLanguages 

func ParseLanguages(title string) []string

ParseLanguages extracts the languages advertised in a stream title such as "English / French", "AC3 5.1 English+French+Spanish", "Español Latino 5.1", or "Português (Brasil)". Codec, channel, and role tokens are filtered out, and results are returned in canonical BCP-47 form preserving first-seen order.

func TrackRole 

func TrackRole(title string, commentary, visualImpaired *bool) string

TrackRole classifies an audio stream's role ("main", "commentary", or "description") using both container disposition flags and stream title cues.

Types

type StreamLangInput 

type StreamLangInput struct {
	Type           string
	Language       string
	Title          string
	Commentary     *bool
	VisualImpaired *bool
}

StreamLangInput describes one stream for multi-audio release language inference.

type Tag 

type Tag struct {
	Primary string
	Script  string
	Region  string
}

Tag is a parsed BCP 47 tag. Primary is canonical: known ISO 639-2 codes fold to their ISO 639-1 form ("eng" -> "en", "por" -> "pt"), and the legacy OpenSubtitles code "pob" parses as primary "pt" with region "br". Script and Region are lower-case and empty when absent.

func ParseBCP47 

func ParseBCP47(tag string) (Tag, bool)

ParseBCP47 parses a BCP 47 tag into primary, script and region.

The region is the 2-letter or 3-digit subtag that follows the optional 4-letter script subtag — never the script itself, so "zh-Hant-TW" yields primary "zh", script "hant", region "tw" (taking the second subtag as the region would read "hant" and lose "tw"). Variant and extension subtags after the region are validated but not reported. Garbage — empty subtags, a primary that is not 2-3 ASCII letters, stray short subtags — is rejected (ok is false).

func ParseCompatible 

func ParseCompatible(raw string) (Tag, bool)

ParseCompatible parses a BCP-47 tag or a known display-name alias (such as "Brazilian Portuguese" or "Latin American Spanish") into a Tag. Undetermined ("und") and multiple ("mul") return ok = false.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.