Skip to content

feat: an admin setting hides other-language Audible editions from search, series and home rows - #527

Merged
kikootwo merged 8 commits into
mainfrom
feat/259-language-filter
Nov 2, 2026
Merged

kikootwo merged 8 commits into
mainfrom
feat/259-language-filter

Conversation

@kikootwo

@kikootwo kikootwo commented Nov 2, 2026

Copy link
Copy Markdown
Owner

Closes #259

Clean-room re-land of #352 by @Eyji (setting, raw-page hasMore, settings route and toggle design), extended to series search, series pages, watched series and home rows, with the setting off by default; when it is on, every list is filtered unless the caller opts out (bulk import does).

What changed

  • Setting: audible.language_filter ('true' / 'false', absent = off), read through ConfigurationService.getAudibleLanguageFilter() and the 60 s config cache. A failed read counts as off. No schema change.
  • Library tab (Plex and Audiobookshelf): a checkbox under the Audible region, Only show books in {Language}, named after the region's language (AudibleLanguageFilterOption.tsx). Help text: "Search and series hide other-language editions and show how many they hid; the home page rows leave them out from their next refresh. Books with no language listed still show. BookDate, shelf sync and watched series skip other-language editions and request nothing for them. Books matched before you turn this on keep their match. Bulk import and requests made from a book page are not affected."
  • PUT /api/admin/settings/audible takes an optional boolean languageFilter (anything else is a 400 before any write; omitted keeps the stored value). GET /api/admin/settings returns audibleLanguageFilter.
  • One rule for every list: partitionByLanguage() (src/lib/constants/language-config.ts) on top of keepsLanguage. An accepted language or no language at all is kept. Both value forms are accepted: catalog names (german) and storefront labels (Deutsch).
  • Search (audibleService.search()): other-language products are hidden and counted; hasMore comes from the raw page, so a page whose books are all hidden is not the last one. GET /api/audiobooks/search adds hiddenCount and filterLanguage only while the filter is on. Bulk import's scan passes { ignoreLanguageFilter: true }.
  • Series pages (scrapeSeriesPage()): counts, hasMore and the layout drift warning come from the rows as listed, then the filter runs; it returns rawCount and the hidden count. The detail route adds hiddenCount and filterLanguage outside the series object.
  • Series search (searchSeries()): off, every series is kept with accepted-language series first (as before); on, other-language products are dropped before aggregation and hiddenCount counts the series listed only by hidden products. The ranking seam and its test are kept.
  • Watched series: the scan stops on a page with no rows, not on a page with no kept books, and the 200-book cap counts rows as listed, so a series never costs more fetches than before. A series whose books are all hidden is marked checked (lastCheckedAt) and logged as hidden, not as "No books found".
  • Home rows: the storefront parsers read each row's .languageLabel (Sprache: Deutsch → Deutsch); the nightly refresh leaves out rows in another language. A row without a label is kept.
  • BookDate and shelf sync turn one search into one book (pickSearchMatch(), src/lib/integrations/audible-language-filter.ts). The rule in one line: with the filter on, the first result is taken exactly as before when it is in the region's language or lists no language, and only when it is in another language is the first later result taken whose language is listed as accepted and whose title (plus subtitle) holds at least 80% of the requested title's words (bulk import's bar; only a trailing parenthetical group such as (Series, #1) is left out), otherwise none. BookDate then drops the recommendation and shelf sync records no match, so an edition with a translated title behind an other-language first result becomes no match. Shelf sync's retry without the series runs only when the search found nothing, as before.
  • UI: a "N in other languages hidden" line on search, /series and the series detail page. When a page shows nothing yet but Audible has more, search loads up to 4 more pages by itself (the count resets on a new query and on a click, and a new query ends the chain); then, like the series detail page, it shows the Load more bar with No results in {Language} so far. Empty results read No results in {Language} for "q" and No series in {Language} for "q". These states are decided from the list before "hide available". When "hide available" empties the loaded list and Audible has more, search and the series detail page keep the Load more bar with All results so far are already available / All books so far are already available; with nothing more, the usual No results found / No books found shows. With the filter off, both pages are as on main. With the filter on, the series detail header and bar count the books shown (for example 2 titles with 18 in other languages hidden), not Audible's series total, which includes other languages.
  • API token docs: the search entry notes hiddenCount / filterLanguage and that a page can be empty with hasMore true.
  • Docs: new documentation/integrations/audible-language-filter.md (rule, callers, opt-out, single-pick rule, limits), TOC entries, and short links from audible.md, audible-series-search.md, settings-pages.md, features/bookdate.md, features/watched-lists.md, features/home-sections.md, features/bulk-import.md, backend/services/goodreads-sync.md and the harness spec list.

Why

On a non-English store, Audible's catalog returns English and other-language editions mixed together, so search, series and the automatic requests from watched series, BookDate and shelf sync could land on an edition in a language the admin's users don't listen in. #352 proposed a filter for search; this extends it to every list that comes from Audible. Filtering a page can leave it empty while Audible has more, so paging is taken from the raw page everywhere. For the callers that pick a single book, "the first kept result" was often another book or a podcast in recordings from audible.it and audible.de (for example Red Rising Pierce Brown on audible.it, where no result is Italian, the first is English and the first one without a language is a podcast). So when the first result is in another language, those take a later result only when its language and its title both match; when it is in the region's language or lists none, they take it as before.

Limits (documented): shelf sync matches are shared per provider and book, so a match made before the filter was turned on stays; BookDate's cache-first match reads the home-row cache, which has no language; a language spelled in a way not in acceptedLanguageValues is hidden until added there; home rows are filtered after the 200-row scrape and are not topped up, so a row can hold fewer than 200 books; a no match recorded while the filter is on is retried after 7 days.

Evidence

  • Recordings (trimmed, no covers): catalog keyword pages for it Red Rising Pierce Brown, de Crooked Kingdom Leigh Bardugo, de Six of Crows Leigh Bardugo, fr Six of Crows, and the audible.de /adblbestsellers page (every row carries a language label).

  • tests/integrations/audible-language-single-pick.test.ts runs the real matchToAudnexus() and processShelfBooks() on those recordings: no pick and no request for Red Rising, Crooked Kingdom and Six of Crows with the filter on, the German King of Scars picked and requested, and the first result as before with it off. On synthetic audible.com pages with the filter on: The Hobbit, or There and Back Again takes an English first result The Hobbit as before, a first result with no language is taken as before, a German first result followed by the English edition picks the English one, a German first result followed by an unrelated English podcast picks nothing, and shelf sync searches once when results exist but none is taken.

  • tests/integrations/audible-search-language-filter.test.ts, audible-series-language-filter.test.ts, audible-series-search-language.test.ts and tests/processors/audible-refresh-language.test.ts run the real search, series page, detail route, watched scan, series search and nightly refresh. With the filter off, each result is deep-equal to the same call with the setting absent.

  • tests/lib/hooks/useSearch-language-filter.test.tsx (real SWR): a fully hidden page is loaded past, at most 4 pages in a row, a click allows 4 more, a new query sends nothing more for the old one. tests/app/language-filter.pages.test.tsx covers the page states.

  • Fails at 25ad327 src (with the test files as of aa7fb65): 13 failed, 46 passed, all 13 on an assertion: the first-result rule (5), the last-parenthetical strip (1), the single shelf sync search (1), "hide available" with the language states (3), the series detail counts (1), the all-hidden watched series (1) and the help text (1).

  • Fails at aa7fb65 src (with the test files as of b2a9d64): 3 failed, 22 passed, all 3 on an assertion: the Load more bar when "hide available" empties a page with more to come, on search (1) and the series detail page (1), and the help text (1).

  • Fails on main (ba411d3 src with this branch's test files as of 25ad327): 66 failed, 145 passed. 54 fail on an assertion: the helper with both value forms (10), search with raw hasMore (4), the BookDate and shelf sync pick (4), series page counts from raw rows and the watched-series stop and cap (7), the search auto-load and its cap (3), the settings route including the 400 (8), home rows (2), the bulk import opt-out (13), the saved settings body (2) and the series search hidden count (1). 12 fail because something new is missing: the page lines (6), searchSeries (3) and the config getter (3). The threshold unit tests and the settings control test don't load on main (new modules). The off-path tests pass on main.

  • On this branch: the 25 test files, 271/271 pass.

  • E2E (--offline-fixtures --overrides abs-fake-metadata, no real Audible host reached): the setting saved through the Library tab on the real path (label follows the region, PUT body {region, languageFilter: true}, checked after a reload, GET true, a string value refused with 400 and nothing written); labelled page.route replays of search with hidden results (the browser stops after page 1 plus 4 automatic loads), of search with "Hide Available" on and page 1 all owned (All results so far are already available with Load more, no automatic load, a click loads page 2) and of series search; the replays send only counts the real route sends (totalResults is the page's own result count). Snapshots at 1280 light, 1280 dark and 375: 1-settings-control-{1280-light,1280-dark,375-light}, 2-search-hidden-{1280-light,1280-dark,375-light}, 2-search-all-hidden-1280-light, 2-search-hide-available-more-1280-light, 3-series-hidden-{1280-light,1280-dark,375-light}, 3-series-all-hidden-1280-light. The series detail hidden states are covered by unit tests only.

  • Screenshots (all 12 in https://gist.github.com/kikootwo/2c3773574a8663a8eccc0d5561d3c56d):

    1-settings-control-1280-light 2-search-hidden-1280-light 2-search-hide-available-more-1280-light 3-series-hidden-1280-dark 2-search-hidden-375-light

Checks

Risk and rollback

  • Off by default. With it off, every search, series and home-row result and response, and every BookDate and shelf sync pick, is the same as before; the new search and series response fields appear only while it is on. GET /api/admin/settings always returns audibleLanguageFilter (false when unset).
  • Turning it on changes which edition BookDate and shelf sync can pick; books matched earlier keep their match.
  • Rollback: revert this PR. The stored setting key is ignored by the old code.

Follow-ups (not in this PR)

  • The Library tab needs Test Connection before Save for any change, the Audible region included; the new checkbox inherits that gate (as on main).
  • Search auto-load can run more than 4 pages when the user returns to an earlier query after clicking Load more on it (userPages keeps the last clicked query).
  • The search header's "N of M results" takes M from page 1's own result count (useAudiobooks.ts; the route sends totalResults as the page's count), so it can read "9 of 3 results" after Load more. Same on main; the filter makes it show more often.
  • Series search counts hidden series before its 15-result cap; audible.service.ts and bookdate/helpers.ts were over the file size limit before this PR.

Release note

🤖 Generated with Claude Code

kikootwo and others added 8 commits October 27, 2026 08:52
A Library tab setting, off by default, keeps Audible results in the region's
language: search, series search, series pages, watched series, the home rows,
BookDate and shelf sync. Books with no language listed are kept. BookDate and
shelf sync take one book only when its language is listed as accepted and its
title matches (80% of the requested words); otherwise no match. Bulk import
opts out. With the setting off, every list, pick and response is as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Eyji <10639815+Eyji@users.noreply.github.com>
…elect by its label

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Eyji <10639815+Eyji@users.noreply.github.com>
- BookDate and shelf sync take the first result as before when it is in the
  region's language or lists none; the title check runs only when the first
  result is in another language. Only the last parenthetical group is left
  out of the requested title.
- Shelf sync retries without the series only when the search found nothing.
- Search and series pages decide "nothing in the language yet" before
  hide-available; the series detail header and bar count the books shown.
- A watched series whose books are all hidden is marked checked and logged
  as hidden.
- Help text says what users see; e2e replays send the route's own counts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…not a missing element (#259)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ge, help text says what home rows do (#259)

With the language filter on and more pages on Audible, search and series
detail show the Load more bar with "All results/books so far are already
available" when hide-available hid every loaded item, instead of a dead-end
"No results found". Off: unchanged.

Help text: search and series show the hidden count; home rows leave
other-language editions out from their next refresh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ad more bar

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	src/lib/integrations/audible.service.ts
@kikootwo
kikootwo merged commit d034613 into main Nov 2, 2026
1 check passed
@kikootwo
kikootwo deleted the feat/259-language-filter branch November 2, 2026 15:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature request: Admin-configurable language filter for Search, BookDate, and Popular results

1 participant