fix: match ISO 639-2 bibliographic and terminological language codes

[chrisbenincasa]

Fixes #1960

Problem

ISO 639-2 assigns 20 languages two three-letter codes: a bibliographic (/B) code derived from the English name, and a terminological (/T) code derived from the native name. German is both ger and deu; French both fre and fra. Media servers and containers use them interchangeably.

A German audio preference never matched a Jellyfin track. From the reporter's troubleshooting log — preference [ger, eng], track tagged deu, English selected:

"rules": [{ "audioAction": "Select audio by language: [ger, eng]" }],
"selectedAudioStream": { "index": 2, "language": "eng" },
"subtitleReason": "No subtitle found for languages: ger"

English is unaffected (it has only one code), which is why this went unnoticed.

Root cause

Four defects, one of which is the origin of the other three:

1. LanguageService.getAlpha3TCode was broken for every /B code. Its /B branch called alpha3TToAlpha2 instead of alpha3BToAlpha2. alpha3TToAlpha2('ger') returns undefined, so the function returned undefined for all 20 bibliographic codes. This silently broke CelEvaluationService.matchLanguageInList, SubtitleStreamPicker, and LocalSubtitlesService — the last of which dropped the language of any sidecar subtitle named with a /B code (Movie.ger.srt), logging it as an unknown language.

2. StreamSelectionEvaluator never normalized at all. Both the audio and subtitle by_language paths compared codes with raw lowercased string equality, so 'deu' !== 'ger' fell through to the next preference.

3. SubtitleStreamPicker normalized only one side. It ran the stream's code through getAlpha3TCode but compared the result to a raw, unnormalized preference.

4. The two web language pickers disagreed. useLanguagePreferences (Settings → FFmpeg → Audio Language Preferences) emitted /B via alpha2ToAlpha3B, while LanguageAutocomplete (channel subtitle preferences) emitted /T via alpha2ToAlpha3T. The server normalizes all probed stream tags to /T, so the FFmpeg settings screen was writing codes that could never match.

Also fixed (not in the original report)

languageBy3LetterCode was keyed on /B codes but ChannelSubtitlePreferencesTable looks up values written by LanguageAutocomplete, which emits /T. The Language column rendered blank for all 20 affected languages.

Changes

• Fix the alpha3BToAlpha2 call in LanguageService.getAlpha3TCode.
• Add LanguageService.codesMatch, which normalizes both sides to /T and falls back to a case-insensitive exact comparison when either side can't be resolved — keeping private-use codes such as qaa working.
• Route all stream language matching in StreamSelectionEvaluator and SubtitleStreamPicker through codesMatch.
• Resolve a stream's language by tag precedence (ISO 639-2 > ISO 639-1 > free-form) rather than matching against any of the three fields. This is the precedence buildCelContext already uses in the same file, so the module is now self-consistent.
• Both web pickers emit /T; the display map indexes both code sets.
• Rename a misleading maybeLang3B local in LocalSubtitlesService — it holds a /T code.

No migration needed. Preferences already stored as /B keep matching through codesMatch, and still resolve a display name.

Note for reviewers

Two pre-existing tests began failing once matching actually worked. Their fixtures build a "French" stream that also carries languageCodeISO6391: 'en' and language: 'English' — an artifact of makeAudioStream's English defaults. The old code only avoided matching them by accident ('english' !== 'eng'). I made the fixtures internally consistent and added a test pinning the tag-precedence rule so the choice is tested rather than incidental.

Test plan

• New LanguageService.test.ts covers all 20 /B↔/T pairs in both directions, plus codesMatch — 74 tests
• New B/T matching suite in StreamSelectionEvaluator.test.ts for audio and subtitles, including preference ordering, preferChannels, tag precedence, and the unresolvable-code fallback
• New language-matching suite in SubtitleStreamPicker.test.ts
• B/T regression test added to CelEvaluationService.test.ts for hasAudioLang
• New web/src/helpers/language.test.ts pins that both pickers emit /T and that legacy /B values still resolve a display name
• Verified the new tests fail against the old code — reintroducing the LanguageService bug produces 12 failures across the three server suites
• pnpm turbo typecheck clean
• pnpm lint-changed clean
• pnpm turbo test — 1319 server tests, 87 web tests, all passing

🤖 Generated with Claude Code

[chrisbenincasa]

Added 2bc8be9c: the switch to terminological codes exposed a mismatch in LanguagePreferencesList — the options list deduped on iso6392 while isOptionEqualToValue compared iso6391, so a preference saved earlier as ger no longer suppressed the deu option and German could be added twice. Both now key on the ISO 639-1 code, which has no B/T split. Covered by a new component test.

A broader sweep for the same bug class turned up several more sites (troubleshoot subtitle matching, Meilisearch language filtering, and unnormalized writes at the Plex/Jellyfin/Emby boundary). Those are being handled separately to keep this PR focused.