fix(igdb): match ROMs by localized/alternative titles in scan

[Spinnich]

Summary

IGDB scans silently dropped games whose filename uses a localized (non-English) title — even when that exact title exists in IGDB's alternative_names or game_localizations.

The root cause was in _search_rom(): IGDB's alternative_name wildcard search did surface the correct game, but the handler then rebuilt its name -> game candidate dict using only the primary English name. The Jaro-Winkler re-check therefore scored the localized search term against the English title alone, fell below the similarity threshold, and discarded the match.

Example (issue #3435): the No-Intro filename 007 - Die Welt Ist Nicht Genug never matched James Bond 007: The World Is Not Enough, despite the German title being present in IGDB's alternative_names.

What changed

• Added _index_games_by_searchable_name(), which indexes each game by its primary name plus every alternative_names and game_localizations title IGDB returns.
• Both candidate-building passes in _search_rom() (the primary games-endpoint pass and the expanded /search pass) now use this helper, so find_best_match scores the localized filename against the localized titles too.
• Precedence preserved: primary names win (lowest-IGDB-id tiebreak); alternative/localization titles fill in only names not already claimed by a primary name.

No new IGDB requests — alternative_names.name and game_localizations.name were already requested in GAMES_FIELDS; this change just makes use of data already fetched.

Files modified

• backend/handler/metadata/igdb_handler.py — added the _index_games_by_searchable_name() helper and replaced the two inline name -> game dict builders in _search_rom() with it.
• backend/tests/handler/metadata/test_igdb_handler.py — added _make_game() helper and a TestSearchRomLocalizedTitleMatching suite covering alt-name matching on the primary pass, alt-name and localization matching on the expanded pass, a regression test that the primary English name still matches, and a precedence test that a primary-name owner beats another game listing the same string as an alt name.

Testing notes

• uv run pytest tests/handler/metadata/test_igdb_handler.py — 7 passed.
• Tests mock igdb_service.list_games/search, so no live API calls or new VCR cassettes are needed.

Reviewer notes

• Behavior change in the expanded pass: the shared helper now applies the lowest-IGDB-id tiebreak for primary names in the expanded-search index too (previously first-seen). Intentional, for consistency with the primary pass.
• Matched name remains the English primary title when a match is found via an alt/localization name — the ROM is matched to the correct game and keeps IGDB's canonical title rather than the localized filename. This is intended.
• Closes [Bug] IGDB scan(s) fail to match games with localized/non-English filenames #3435.

🤖 Written primarily by Claude Code (Opus 4.8), reviewed by the author.

[Copilot]

Pull request overview

Fixes IGDB scan matching when filenames use localized/alternative titles. The candidate-name index used for Jaro-Winkler matching now includes each game's alternative_names and game_localizations titles, not only the primary English name. Closes #3435.

Changes:

• Adds _index_games_by_searchable_name() that indexes games by primary name (lowest-id tiebreak) plus alt/localization titles (only when not already claimed).
• Replaces both inline name→game dict builders in _search_rom() with the new helper.
• Adds TestSearchRomLocalizedNames suite and extends _make_game() to populate alternative_names/game_localizations.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
backend/handler/metadata/igdb_handler.py	Adds the shared indexing helper and wires it into both candidate-building passes of _search_rom().
backend/tests/handler/metadata/test_igdb_handler.py	Extends _make_game and adds regression/precedence tests for localized-title matching.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.