waazaafr/sonarr-metadata-localizer repository overview

⁠Sonarr Metadata Localizer

Translate the metadata of your TV shows into your language, for Jellyfin.

Sonarr writes its NFO files in English. This image rewrites the titles and plots of your series and episodes with localized metadata from TMDb⁠, and can download localized artwork (poster, backdrop, logo, episode thumbnails) with Jellyfin-friendly file names.

It works instantly through a Sonarr webhook, and with a scheduled scan of your whole library as a safety net.

⁠Features

• 🌍 Localized series plot, episode titles and plots from TMDb, in the language of your choice
• 🖼️ Localized artwork: poster, cover, backdrop, logo and episode thumbnails
• ⚡ Sonarr webhook: a series is updated as soon as an episode is imported or renamed
• 🧺 Events are grouped: importing a full season triggers a single update of the series
• 🕒 Scheduled scan of the whole library
• 💾 Backup of every modified NFO (.bak), cleaned up automatically after 7 days
• 🧪 Dry-run mode to preview changes
• 🖥️ Multi-arch: linux/amd64 and linux/arm64

⁠How it works

1. A series folder is detected by its tvshow.nfo, which provides the TMDb ID of the series.
2. The app fetches the localized metadata from TMDb and updates:
   • tvshow.nfo: the plot, and optionally the title;
   • each episode .nfo: the title and plot, when the episode number can be read from the file name (S01E02, 1x02).
3. Before a file is modified for the first time, the original is kept next to it (*.bak).
4. If enabled, artwork is downloaded into the series folder:

Images that were already downloaded are not downloaded again (tracked in .tmdb-art-state.json in each series folder).

⁠Quick start

You need a free TMDb API key: themoviedb.org/settings/api⁠.

services:
  sonarr-metadata-localizer:
    image: waazaafr/sonarr-metadata-localizer:latest
    container_name: sonarr-metadata-localizer
    restart: unless-stopped
    ports:
      - "8787:8787"
    environment:
      TZ: "Europe/Paris"
      TMDB_API_KEY: "your-tmdb-api-key"
      AUTH_TOKEN: "a-long-random-secret"
      TMDB_LANGUAGE: "fr-FR"
      TMDB_IMAGE_LANGUAGE: "fr,null"
      SONARR_ROOT_FOLDER: "/tv"
    volumes:
      # Must be the SAME path as your series folder inside Sonarr (e.g. /tv)
      - /your/series/folder:/tv:rw

⁠Sonarr webhook

In Sonarr, go to Settings → Connect → + → Webhook:

Click Test: Sonarr should report a success.

What happens when Sonarr calls the webhook:

• Events of the same series are grouped for DEBOUNCE_SECONDS (30 s): importing a full season updates the series once.
• The app waits for Sonarr to write tvshow.nfo and the .nfo of the imported episodes before updating them.
• Upgrades are sent by Sonarr as Download events, so they are handled too.
• On Series Add is ignored when Sonarr has not created the series folder yet: the series is handled at its first import.

A health endpoint is available at http://<container-ip>:8787/health.

⁠Configuration

⁠TMDb & metadata

⁠Artwork

⁠Scheduled tasks

A scan never starts while the previous one is still running.

⁠Webhook

⁠Changelog

⁠1.1.0 — 2026-10-22

• Multi-arch image: linux/amd64 and linux/arm64.
• Webhook: events of a same series are grouped (DEBOUNCE_SECONDS), so a season import updates the series once instead of once per episode.
• Webhook: waits for the .nfo of imported episodes (WAIT_FOR_EPISODE_NFO_SECONDS), which Sonarr may write after calling the webhook.
• Webhook: Sonarr's Test always succeeds; On Series Add no longer fails when the series folder does not exist yet.
• Webhook: retries no longer block a worker.
• ALLOWED_EVENT_TYPES now defaults to Download,Rename,SeriesAdd (Upgrade and SeriesEdit are not sent by Sonarr; upgrades arrive as Download).
• The original NFO is now really backed up to .bak before the first change.
• The webhook and the scheduled scan can no longer update the same series at the same time, and scans can no longer overlap.
• Episode files with 4-digit seasons (S2024E05) are now recognized.

⁠1.0.1 — 2026-02-24

⁠1.0.0 — 2026-02-23

• First releases.

⁠Links

• Source code: codeberg.org/waazaa/sonarr-metadata-localizer⁠
• Docker image: hub.docker.com/r/waazaafr/sonarr-metadata-localizer⁠
• 💬 Discord: discord.gg/p9xkjEw8ts⁠
• ☕ Buy me a coffee: buymeacoffee.com/waazaa⁠
• ☕ Ko-fi: ko-fi.com/waazaa⁠
• UnRAID license: unraid.net⁠