Skip to content

Contributing ​

Local Development ​

Install dependencies:

bash
npm install

Create a local environment file:

bash
cp .env.example .env

Set JWT_SECRET, then run:

bash
npm start

The app builds before it starts. During frontend work, rerun npm run build after changing React or Tailwind files.

Build Commands ​

CommandPurpose
npm run build:cssBuild Tailwind CSS into static/tailwind.css
npm run build:jsBundle React into static/bundle.js
npm run build:versionUpdate version.txt
npm run buildRun all app build steps
npm run docs:devStart the VitePress docs dev server
npm run docs:buildBuild the static docs site
npm run docs:previewPreview the built docs site

Translations ​

UI chrome for Discover, Request, and Home Wrap-Up is translated via TypeScript catalogs under client/discovery/i18n/. The language selector stores the choice in the user's preferences when available and keeps localStorage (discoverUiLocale) as a compatibility fallback. Missing keys fall back to English, so a partially translated locale still works — unfinished screens stay in English until strings are added.

Current locales: English (en), French (fr), German (de), Spanish (es), Brazilian Portuguese (pt-BR), Italian (it), Japanese (ja), Polish (pl), Dutch (nl), and Russian (ru).

FileRole
client/discovery/i18n/en.tsSource catalog (complete English strings)
client/discovery/i18n/fr.tsFrench (fr) locale overlay (DeepPartial of English)
client/discovery/i18n/de.tsGerman (de) locale overlay (DeepPartial of English)
client/discovery/i18n/es.tsSpanish (es) locale overlay (DeepPartial of English)
client/discovery/i18n/pt-BR.tsBrazilian Portuguese (pt-BR) locale overlay (DeepPartial of English)
client/discovery/i18n/it.tsItalian (it) locale overlay (DeepPartial of English)
client/discovery/i18n/ja.tsJapanese (ja) locale overlay (DeepPartial of English)
client/discovery/i18n/pl.tsPolish (pl) locale overlay (DeepPartial of English)
client/discovery/i18n/nl.tsDutch (nl) locale overlay (DeepPartial of English)
client/discovery/i18n/ru.tsRussian (ru) locale overlay (DeepPartial of English)
client/discovery/i18n/types.tsDISCOVER_LOCALES list for the language menu
client/discovery/i18n/index.tsxCatalog registry + t('dot.path') helper

Much of the wider portal (Scanner, Settings, admin dashboards, etc.) is still English-only. Prefer extending these catalogs and wiring useDiscoverI18n() / t('…') where new chrome is needed, rather than inventing a second system.

Improve an existing language ​

  1. Fork / clone the repo and open a branch.
  2. Diff en.ts against your locale file (e.g. fr.ts).
  3. Add or fix strings using the same nested keys as English.
  4. Keep placeholders intact: {count}, {days}, {name}, {pct}, {time}, etc.
  5. For plurals, add a sibling key with _plural when English has one (e.g. episodeCount / episodeCount_plural). The translator picks _plural when |count| !== 1.
  6. Run npm run build (or at least npm run build:js) and spot-check Discover + Home Wrap-Up with that language selected.
  7. Open a pull request — partial passes are welcome.

You do not need a translation platform. Edited .ts catalogs + a PR is enough. If you cannot open a PR, paste suggested strings (key → translation) in an issue or Discord and maintainers can land them.

For the full localization workflow and current project coverage, see the Localization Guide and Localization Status.

Add a new language ​

  1. Add a locale overlay such as it.ts under client/discovery/i18n/ and translate the strings (you may copy an existing overlay or start from a minimal subset — English fills gaps).
  2. Register the locale code in DISCOVER_LOCALES inside types.ts (code, label, nativeLabel).
  3. Import the catalog in index.tsx and add it to the catalogs map.
  4. Build and verify the new option appears in the language menu and Discover metadata requests send the right locale header.

Conventions ​

  • Prefer natural UI phrasing over word-for-word English.
  • Do not translate product names unless there is an established local form (e.g. leave “Discover”, “Plex”, “Seerr” as-is when that reads better).
  • Do not change key names in locale files — only values.
  • When adding new English UI chrome, add the key to en.ts first, then optionally seed other locales in the same PR.

Pull Request Checklist ​

  • Keep runtime secrets out of git.
  • Avoid committing generated runtime data from config/ or backup/.
  • Run the relevant build command before opening a pull request.
  • Update docs when behavior, setup, configuration, or deployment changes.
  • Add focused tests or manual verification notes when touching shared flows.
  • For translation PRs: keep placeholders, match en.ts keys, and note which screens you checked.

Release Notes ​

User-facing changes belong in CHANGELOG.md. Merges to main are versioned by Release Please from Conventional Commits on the PR title / squash commit.

Commit messages (release-please) ​

Use a type and optional scope, then a clear summary:

text
feat(spotify-sync): add Compose supervisord mount for portal-managed sync schedule
fix(docker): mount spotify-to-plex env_file from portal-generated config
TypeWhen
featNew capability
fixBug fix
perfPerformance
docsDocs only
choreTooling, deps, no user impact

Docker / Compose wording (for changelog and operator-facing text):

PreferInstead of
spotify-to-plex container or Compose servicesidecar
image (jjdenhertog/spotify-to-plex)app binary
env_file / config/spotify-to-plex.envhost .env credentials
bind mount / volume (config/spotify-to-plex)config folder (vague)
supervisor sync-scheduler processsidecar cron (in logs)
restart the containerrestart the sidecar
Docker network service URL (http://spotify-to-plex:9030)internal URL (in docs, clarify)

Internal config keys (e.g. spotifyToPlexScheduleMode: sidecar) stay as-is for compatibility; user-facing copy and commit summaries should use the terms above.

Scopes that match the repo: spotify-sync, docker, compose, collexions, settings, ui, etc.

Built for the self-hosting community.