Initial jellyfin-multilang rewrite

2026-05-31 18:28:04 +00:00
commit 63dbc3a6d4
32 changed files with 9326 additions and 0 deletions
@@ -0,0 +1,138 @@
+# Jellyfin Multilang
+
+Multilang is a Jellyfin plugin that lets different users see different metadata
+languages without changing Jellyfin's stored metadata.
+
+The plugin is built for Jellyfin 10.11.9 and is currently early beta software.
+
+## What It Does
+
+Multilang can fetch and display metadata and artwork in chosen languages for:
+
+- Titles
+- Overviews
+- Taglines
+- Posters
+- Logos
+- Banners
+- Thumbnails
+- Backdrops
+
+In addition, it can translate genres into the user's Jellyfin display language.
+
+## Admin Features
+
+Admins configure the data that Multilang can use:
+
+- Choose which languages should be exposed for metadata and artwork fetching.
+- Configure TMDb and Fanart.tv provider keys.
+- Set metadata and artwork provider priority.
+- Configure leading articles for sorting, such as `the`, `a`, `an`, or
+  language-specific equivalents.
+- Configure scheduled refresh timing for missing and existing metadata.
+- Set thresholds for what requests to cache.
+- View cache and recent request diagnostics.
+- Enable logging when troubleshooting.
+
+## User Features
+
+Each user can enable or disable Multilang for themselves.
+
+Users can create classification rules that group items into categories. For
+example, a user can classify Finnish films, Swedish films, Spanish films, or
+movies produced in a specific country.
+
+For each category, the user can choose an ordered fallback list for each field.
+For example:
+
+- Use the Finnish title, then Swedish if that isn't available, then Jellyfin's default as the final fallback.
+- Use the original title instead of any set language.
+- Use a Swedish overview, then English if that isn't available.
+- Use an original-language poster, then Jellyfin's default poster if that isn't available.
+- Clear a field if no selected language has data.
+
+Title and poster always force Jellyfin as a final fallback so browsing remains
+usable.
+
+Users can also choose which language's alphabet and sorting rules should be used
+when Multilang sorts item lists.
+
+## How It Works
+
+The admin chooses which languages Multilang should make available. These
+languages decide what metadata and artwork the plugin fetches from providers.
+
+Each user then creates their own rules for what languages to display, when to
+display them, and which fields should use them. The available choices are:
+
+- Languages selected by the admin.
+- The `Original` language according to TMDb.
+- Jellyfin's own default metadata and artwork.
+
+Multilang keeps fetched text metadata in its own SQLite database. Downloaded or
+proxied artwork is handled by the plugin separately from Jellyfin's normal
+metadata storage. Jellyfin's own library metadata is not overwritten.
+
+The plugin changes the Jellyfin web UI by injecting JavaScript into Jellyfin's
+main web page. This works in a browser and in the official Jellyfin desktop app,
+because both use the Jellyfin web UI. It is not guaranteed to work in clients
+that do not use the web UI.
+
+The injected script makes selected UI requests go through Multilang's plugin API
+instead of directly to Jellyfin. The plugin fetches the original response from
+Jellyfin, applies the current user's rules, and returns a modified response to
+the UI.
+
+Some requests can be slow because Multilang may need to ask Jellyfin for a
+larger list than the UI will finally display. This is needed so the plugin can
+translate, filter, sort, and slice the list using the user's own rules.
+Multilang caches slow transformed responses for a configurable time and also
+uses a very short burst cache for repeated requests during navigation. Cache
+entries are invalidated when affected items are refreshed.
+
+## Original-Language Support
+
+Multilang stores metadata and artwork tagged as `Original`.
+
+This is useful when a user wants the original title and matching original poster
+for languages they do not otherwise want as their main metadata language.
+
+## Genres
+
+Jellyfin stores and displays genres by name. If metadata was fetched in English,
+the genre may be `Drama`; if it was fetched in Finnish, the genre may be
+`Draama`. Jellyfin treats those names as separate genres, and it displays the
+stored name regardless of the user's display language.
+
+Multilang avoids this by storing TMDb genre IDs for each item. The ID stays the
+same across languages, so the plugin can display the genre name in the user's
+current Jellyfin display language when a translation is available.
+
+## Debugging
+
+The plugin includes lightweight admin/debug tools:
+
+- Cache diagnostics
+- Recent request diagnostics
+- Refresh queue/provider diagnostics
+- Per-item debug view showing which category matched and which field action won
+
+These are intended for troubleshooting configuration or missing metadata, not
+for normal daily use.
+
+## Current Status
+
+This plugin is usable but still under active testing. The most important areas
+to test are:
+
+- Large library browsing
+- Sorting and filtering
+- Collections
+- Shows, seasons, and episodes
+- Scheduled scans
+- Complex per-user classification rules
+
+## AI Assistance
+
+This codebase was written with substantial help from AI tools, under human
+direction and testing.