Skip to content

fix(boxsets): fetch box sets in the library's metadata language - #4513

Merged
Quick104 merged 5 commits into
Silo-Server:mainfrom
Rhainland:fix/4485-box-set-language
Nov 18, 2026
Merged

Quick104 merged 5 commits into
Silo-Server:mainfrom
Rhainland:fix/4485-box-set-language

Conversation

@Rhainland

@Rhainland Rhainland commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Closes #4485
Related issue: N/A
Validation tasks: none

Other clients: Apple N/A (no client change; clients show the name and poster the server sends); Android N/A (same); Roku N/A (same)

Box sets built from TMDB collections always came in English, whatever the library's metadata language. A French or German movie library showed "Star Wars Collection" with the English poster and overview, while its movies, series and seasons were localized. The box set sync asked TMDB for each collection without a language parameter, so TMDB answered in English. Collections already stored would also stay English, because a stored collection was only fetched again when it went stale.

With this change the sync asks for each collection in its library's metadata language and stores which language it used. Collections stored in another language are fetched again on the next sync, so existing installs pick up the translation, and so does a library whose language changes later.

Approach

  • One stored collection serves every library, so it is fetched in the language of the first enabled library, in library order, that shows the box set: one with box sets on that holds at least its box set minimum of the collection's movies, or failing that the first that holds one. A deployment whose box set libraries use different languages gets the language of one of them. Per-profile metadata languages are not applied to box sets.
  • tmdb_movie_collections gains a language column. Rows stored before this change default to en, which is what TMDB returned for them, so English libraries do not refetch anything.
  • The language goes to TMDB the way the TMDB metadata plugin sends it: en as en-US, other codes as given. TMDB picks the matching poster itself.
  • TMDB leaves the overview empty where a collection has no translation for it, and may do the same for the name. Those fields are filled from TMDB's answer in the server's fallback metadata language (metadata.fallback_language), the way item metadata falls back, and stay empty when that setting is the original language. If that second request fails, the fetch fails: the stored row keeps its text and the next run tries again.
  • The box set architecture note describes the language rule and the new refetch condition.

Validation

  • Focused Go tests for the TMDB client, the box set sync and the box set repository, including the DB contract tests: pass.
  • go build ./..., gofmt, go mod tidy -diff, go vet ./..., make lint-changed, make lint-router-recovery: pass.
  • make verify-migrations, verify-local-paths, verify-bidi, verify-size-ratchet, verify-route-inventory: pass.
  • Local build against a fake TMDB that answers by language, with a German movie library holding two movies of one collection: reproduced on main, fixed on this branch (see Evidence).
  • Review fixes: TestBoxSetCollectionLanguageDB (a library below its box set minimum) and TestRunRetriesWhenTheFallbackFails fail on the commit before 45c12e0 and pass now; TestRunFillsNothingWhenTheFallbackIsOff covers the fallback setting.
  • Not run: the full make test-go suite and the web half of the gate; this change touches no web code.

Evidence

A local build with a movies library set to de and box sets on, two synthetic movies in TMDB collection 10, and a fake TMDB that answers /collection/10 in German only when asked for language=de.

Before, on main, the sync requests /3/collection/10 with no language and the API returns:

GET /api/v2/catalog/box-sets/10?library_id=1
{
  "title": "Star Wars Box Set",
  "overview": "An epic space saga.",
  "poster_url": "https://image.tmdb.org/t/p/original/en-poster.png"
}

After, on this branch, against the same database, the sync requests /3/collection/10?language=de and the API returns:

GET /api/v2/catalog/box-sets/10?library_id=1
{
  "title": "Star Wars - Sammlung",
  "overview": "Eine epische Weltraumsaga.",
  "poster_url": "https://image.tmdb.org/t/p/original/de-poster.png"
}

Switching the library to en and syncing again requests language=en-US and returns "Star Wars Box Set" with the English poster. When the German answer has no overview, the sync makes a second request without a language and stores the German name with the English overview. Box set search (GET /api/v2/catalog/box-sets?q=star) returns the same localized fields.

The review fixes change no UI; their tests and a query timing are on the evidence page.

Evidence: https://evidence.siloserver.org/r/silo-server/pr-4513-review/

Risks

  • Migration: one ADD COLUMN ... NOT NULL DEFAULT 'en' on tmdb_movie_collections, a metadata-only change in PostgreSQL. An older node that runs the sync during a rolling update still fetches stale collections in English without touching the column, so such a row can hold English text while recorded as another language until it goes stale again (7 days).
  • After updating, a non-English box set library refetches each of its collections once on the next sync, within the existing TMDB rate limit.
  • Box set search matches "box set" and "collection" against names ending in "Collection". A localized name such as "Star Wars - Saga" is found by its own words, not by those English suffix words.

Checklist

  • I read and can explain the complete diff.
  • This pull request addresses one concern.
  • Each test this pull request adds meets "Decide what to test" in CONTRIBUTING.md.
  • The Evidence section shows every change a user can see, or how I checked a change nobody sees.

AI Disclosure

  • Harness: Claude Code (via T3 Code); Codex CLI for code review
  • Tool(s): Claude Code, Codex CLI
  • Model(s): claude-opus-5-5; gpt-6.2-sol, gpt-6.2-astra, claude-fable-5-2 (code review)
  • Involvement: Fully AI-generated, human verified
  • Maintainer review fixes (4ab7be8, 45c12e0): Claude Code (claude-opus-5-5)
  • Adversarial review: four independent reviews of the full diff (two GPT models via Codex CLI, two Claude models) on correctness, repository standards and the issue's requirements, then a two-reviewer pass over the follow-up commits. Fixed: TMDB's empty fields for untranslated collections now fall back to English, and a failed fallback no longer drops the translation; the fetch and cleanup queries share one membership rule; the stored language is read back; the language mapping was simplified; a fixture that made a staleness test pass regardless was corrected; the architecture note was updated. Dismissed: a 404 marking the requested language (the row is still refetched when stale, as before); English "box set" suffix words not matching localized names (expected, noted under Risks).

Note

Fetch movie box sets in the library's metadata language

  • Box-set collections are now fetched in the metadata language of the first qualifying enabled box-set library, chosen in catalog.BoxSetRepository.CollectionsNeedingFetch (box_sets.go). Collections stored in a different language are scheduled for a refetch.
  • tmdb.Client.GetCollection accepts a language parameter, and the syncer fills missing name or overview text from the metadata service's configured fallback language via the new Syncer.WithFallbackLanguage setter (sync.go).
  • The stored collection language persists in the new language column, added by 20261118183932_box_set_collection_language.sql with an English default for existing rows.
  • Behavioral Change: a collection whose due-language response is missing text now triggers a second fallback-language request, and a failed fallback request leaves the collection unstored and counted as a failure. CollectionsNeedingFetch and TouchCollection signatures changed, and MetadataService.FallbackLanguage is now exported.

Macroscope summarized 45c12e0.

The box set sync asked TMDB for each collection without a language, so
box set names, overviews and posters were always English. It now asks in
the metadata language of the first box set library holding one of the
collection's movies, records that language with the stored collection,
and fetches a collection again when the language it is due in changes.

Closes Silo-Server#4485
TMDB leaves a collection's name or overview empty where its translation
lacks them, so the sync now takes those from TMDB's English answer, as
item metadata falls back. Also share the box set membership SQL between
the fetch and cleanup queries, read the stored language back, simplify
the TMDB language mapping, and record the language rule in the box set
architecture note.
A failed English request no longer holds back a collection TMDB already returned in the library's language; it is stored as translated unless it has no name.
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

This organization requires a seat for paid usage-based reviews, including automatic and on-demand reviews. Ask an admin to assign a seat or enable paid usage-based reviews for users without a seat in Billing.

Next included review available in 52 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 93e4cf2f-0923-4eed-8263-45e4d4cee78a
Commits

Reviewing files that changed from the base of the PR and between e8de111 and 45c12e0.

Files selected for processing: 14

  • cmd/silo/main.go
  • docs/architecture/movie-box-sets.md
  • internal/api/router.go
  • internal/boxsets/sync.go
  • internal/boxsets/sync_test.go
  • internal/catalog/box_sets.go
  • internal/catalog/box_sets_db_test.go
  • internal/metadata/language_fallback.go
  • internal/metadata/local_artwork_discovery.go
  • internal/metadata/service.go
  • internal/metadata/tmdb/client.go
  • internal/metadata/tmdb/client_test.go
  • migrations/sql/20261118183932_box_set_collection_language.sql
  • scripts/ci/db-contracts.txt
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@silo-triage silo-triage Bot added the size/L 200–499 added + deleted lines (all files); change volume, not priority. label Nov 18, 2026
@silo-kody

silo-kody Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

@silo-triage silo-triage Bot added bug Something isn't working go Pull requests that update go code impact: polish Annoyance, cosmetic, or nice-to-have priority: P2 Limited scope, workaround exists, or polish labels Nov 18, 2026
Comment thread internal/boxsets/sync.go Outdated
return nil, err
}
localized := *c
localized.Name = cmp.Or(c.Name, english.Name)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Kody Rules high

English fallback names lose their language provenance

An English fallback name becomes indistinguishable from one supplied in the requested language because the collection records only fetch.Language. Track and persist the provenance of localized.Name independently.

Also found in:

  • internal/boxsets/sync.go:234-234

Kody rule violation: Track localization provenance independently for each metadata field

Prompt for LLM
File internal/boxsets/sync.go, line 233:

English fallback names lose their language provenance

Preserve the name's language provenance when filling it from the English response. The stored collection records only `fetch.Language`, so an English fallback name becomes indistinguishable from a name supplied in the requested language. Track the name's provenance independently and persist it with the collection.

**Also found in:**
- `internal/boxsets/sync.go:234-234`

Kody rule violation: [Track localization provenance independently for each metadata field](https://kodus.siloserver.org/settings/code-review/1247142351/kody-rules/705436fb-f63f-4782-bc30-9184ebbd56df?teamId=ba9922fc-c0ea-4cf8-87bb-9d4f42ffc73e)

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this. The row is refetched every 7 days, and any time the language it is due in changes, so a translation TMDB adds later replaces the filled-in name or overview on the next refresh without per-field tracking. Nothing reads a separate language for a box set's name or overview. In practice TMDB fills a missing collection name with its default name itself (/collection/10?language=ta returns "Star Wars Collection"), so the fill mostly applies to the overview. The fill now uses the server's metadata.fallback_language rather than English (4ab7be8).

🤖 Claude Code (claude-opus-5-5)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense. The stored language tracks the requested collection language, not the provenance of every field. Since the collection is refreshed every seven days and when its requested language changes, a newly available translation can replace fallback text without per-field tracking.

I withdraw the suggestion for this PR. Using the configured metadata.fallback_language also makes “English fallback” an outdated description.

Comment thread internal/boxsets/sync.go Outdated
Comment on lines +225 to +228
if err != nil {
if c.Name != "" {
slog.WarnContext(ctx, "box sets: English collection fallback failed; storing the translation as it is", "component", "boxsets", "tmdb_collection_id", fetch.ID, "error", err)
return c, nil

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug high

A failed English fallback leaves the overview empty for seven days

Preserve the translated collection in c while tracking the failed fallback separately so it can be retried on the next run.

Prompt for LLM
File internal/boxsets/sync.go, lines 225-228:

A failed English fallback leaves the overview empty for seven days

A transient English fallback failure stores an empty overview as a successful, fresh collection, so the missing English text is not retried for seven days even if TMDB recovers immediately. Preserve the translated collection while tracking the failed fallback separately so it can be retried on the next run.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This holds up: a failed fallback request stored the translation with a blank overview, which overwrote any overview already stored and marked the row fresh for 7 days. Fixed in 45c12e0. A failed fallback answer now fails the fetch, so the stored row keeps its text and the collection is tried again on the next run. The error isn't wrapped as ErrNotFound, so a 404 on the fallback request can't mark the row fetched. TestRunRetriesWhenTheFallbackFails fails on the previous head (stored = true, failures = 0) and passes now.

🤖 Claude Code (claude-opus-5-5)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update. The reported fix addresses the retry issue: a failed English fallback leaves the existing collection unchanged and allows the next sync to retry. The regression test also covers the previously observed behavior.

Comment thread internal/boxsets/sync.go Outdated
Comment on lines +225 to +228
if err != nil {
if c.Name != "" {
slog.WarnContext(ctx, "box sets: English collection fallback failed; storing the translation as it is", "component", "boxsets", "tmdb_collection_id", fetch.ID, "error", err)
return c, nil

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Performance medium

Fallback failures bypass the TMDB outage circuit breaker

An English-endpoint outage triggers retries for every collection with a translated name instead of stopping the run. Count fallback failures toward res.Failures while preserving the translated data.

Prompt for LLM
File internal/boxsets/sync.go, lines 225-228:

Fallback failures bypass the TMDB outage circuit breaker

English fallback failures for collections with translated names bypass `res.Failures` and the 25-failure circuit breaker, so an English-endpoint outage triggers retries for every such collection instead of stopping the run. Count fallback failures toward the existing failure budget while still preserving the translated data.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed by the same change in 45c12e0. A failed fallback answer now counts as a failed fetch, so it counts toward the run's 25-failure limit (res.Failures); TestRunRetriesWhenTheFallbackFails checks for one failure.

🤖 Claude Code (claude-opus-5-5)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update. Based on your description, commit 45c12e082 addresses the circuit-breaker concern by counting fallback failures toward the 25-failure limit. I haven’t independently verified the change or test.

Quick104 and others added 2 commits November 18, 2026 20:12
Item metadata fills text a translation lacks from metadata.fallback_language
and leaves it empty when that setting is the original language. The box set
sync always asked TMDB for English instead. It now reads the same setting,
hot-reloaded through the metadata service.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A library holding fewer of a collection's movies than its box set minimum
does not show the box set, so it no longer picks the language the shared
row is fetched in while another library shows it.

A failed fallback-language answer now fails the fetch. Storing the
translation without it wrote a blank overview over the stored one, marked
the row fresh for a week, and kept the failure out of the run's budget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@Quick104 Quick104 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Claude Code (claude-opus-5-5)

Review of 1e8af96. Two new findings below, and two of the existing Kody threads hold up (answered in those threads). I'm fixing all of them in commits on this branch, so there's no need to change anything yourself.

Comment thread internal/boxsets/sync.go Resolved
Comment thread internal/catalog/box_sets.go Resolved
@silo-kody

silo-kody Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

ORDER BY m.tmdb_collection_id, count(*) >= GREATEST(lib.box_set_min_movies, $4) DESC, lib.sort_order, lib.id
) due
LEFT JOIN tmdb_movie_collections c ON c.tmdb_collection_id = due.tmdb_collection_id
WHERE c.tmdb_collection_id IS NULL OR c.fetched_at < $1 OR c.language <> due.language

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug high

Fallback language changes do not invalidate fresh collections

Changes to metadata.fallback_language can leave freshly fetched collections unchanged for up to seven days because the due predicate checks only the primary language and fetch time. Track the fallback language used for each collection or invalidate affected collections when the setting changes.

Prompt for LLM
File internal/catalog/box_sets.go, line 237:

Fallback language changes do not invalidate fresh collections

Changing `metadata.fallback_language` leaves freshly fetched collections unchanged for up to seven days because the due predicate only compares the primary language and fetch time. Track the fallback language used for each collection or invalidate affected collections when the setting changes.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this in this PR. metadata.fallback_language only fills a name or overview the collection's translation lacks. When an admin changes it, the affected collections pick up the new fallback on their next refresh, at most 7 days later. Item metadata works the same way: changing the fallback language doesn't refetch items either. Tracking the fallback language per collection would need another column and refetch rule for a rare settings change. If a refetch on change is wanted, it should apply to items and box sets together.

@Quick104

Copy link
Copy Markdown
Contributor

🤖 Claude Code (claude-opus-5-5)

Review summary

Reviewed 1e8af96. I pushed fixes 4ab7be8 and 45c12e0 on top, so the head is now 45c12e0. There was no rebase.

Fixed on this branch

  • Box set text missing from a translation is filled from the server's metadata.fallback_language, the same setting item metadata and the user manual use, instead of always English. When that setting is the original language, the text stays empty. (4ab7be8)
  • The language comes from the first library that shows the box set: one holding at least its box set minimum of the collection's movies. Before, a library holding a single member could decide the language for a box set only another library shows. (45c12e0)
  • A failed fallback request now fails the fetch. Before, the sync stored the translation with a blank overview, which overwrote any stored overview, kept the row fresh for 7 days, and didn't count toward the run's 25-failure limit. This answers two of the Kody threads. (45c12e0)
  • The architecture note and the PR body's Approach and Validation sections now describe these rules.

Verification

  • End to end against real TMDB, with the real syncer, repository, and client on a migrated Postgres and a German movies library holding two Star Wars films. On main, the row stores "Star Wars Collection" with the English overview and poster. At 45c12e0 it stores "Star Wars Filmreihe" with the German overview and poster. A row that main had stored in English seconds earlier was refetched in German on the first sync at the head.
  • TestBoxSetCollectionLanguageDB and TestRunRetriesWhenTheFallbackFails fail on 4ab7be8 and pass at 45c12e0. The PR's original tests don't build on main because they call the new signatures, so they don't count as proof of the fix. The end-to-end run above does.
  • Focused Go tests for boxsets, metadata, metadata/tmdb, and the box set DB tests pass; make lint-changed reports 0 issues.
  • A second-opinion review by another model (Codex, gpt-6.2-sol) ran on 1e8af96. Its fallback-language, library-minimum, and fallback-failure findings are fixed above. Its remaining points are listed below.

Left for the maintainers

  • Rolling updates (disclosed under Risks): while an older node and a newer node both run the sync, the older node can refresh a stale localized row in English and leave its language marker. The row then stays English for up to 7 days. This only happens during a mixed-version window.
  • Query cost: on a synthetic catalog with 40k collection memberships and 12k collections, the due-collection query takes about 125 ms per call at the head. On main it takes 20–30 ms. It runs hourly and after catalog changes, once per batch of 200 due collections.
  • ci / Go integration (on 1e8af96) and ci / Go vet and contracts (on 45c12e0) failed in their Set up Go step while installing packages. Both are CI setup failures, not failures caused by this branch.

Other checks

  • Validated features: Collections ([v1] Collections #192 and its tasks) covers server collections, not TMDB box sets, and no other validation task covers box sets or library metadata language. Validation tasks: none stands. I couldn't read recorded results from the board.
  • User manual: unaffected. It describes the library metadata language and the fallback language in general terms, which box sets now follow, and says nothing box-set-specific about language.
  • Other clients: N/A. Clients show the name, overview, and poster the server sends. The Jellyfin-compatible API doesn't expose TMDB box sets.

Evidence: https://evidence.siloserver.org/r/silo-server/pr-4513-review/

Fit: 9/10 · Readiness: 9/10 — ready (assuming CI is green)

Fit: box sets were the one part of a movie library that ignored its metadata language, and this fixes that inside the existing box set sync. The added column is internal and the API is unchanged. Readiness: the fix is shown end to end against real TMDB on main and on the head, and each review fix has a test that fails without it. The rolling-update window above is the only known gap, and it is disclosed.

@Quick104
Quick104 merged commit 4102bca into Silo-Server:main Nov 18, 2026
33 of 35 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working go Pull requests that update go code impact: polish Annoyance, cosmetic, or nice-to-have priority: P2 Limited scope, workaround exists, or polish size/L 200–499 added + deleted lines (all files); change volume, not priority.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bug] Box set (TMDB collection) names and posters ignore the library metadata language

2 participants