spotifast/docs/_reference/translating.md

title, description, nav_order

title	description	nav_order
Translating Spotifast	Help translate Spotifast and preview the work so far.	6

Spotifast follows your computer's language when it has a translation for it, and uses English otherwise. Settings → Appearance → Language picks another language, listed under its own name, and applies it at once; System follows the computer again. This arrived in 0.10.0. Corrections from fluent speakers are welcome.

Translations are stored in .po files, a common format supported by editors such as Poedit and Weblate. They are included with Spotifast, so the app does not contact an online translation service.

Languages and coverage

Language	Tag	Coverage
English	en	Source language
Spanish	es	Complete
German	de-DE	Partial
Dutch	nl	Partial
Portuguese (Brazil)	pt-BR	Partial
Portuguese (Portugal)	pt-PT	Partial
French	fr	Partial
Swedish	sv	Partial
Polish	pl	Partial
Russian	ru	Partial
Italian	it	Partial
Japanese	ja	Partial
Chinese (Simplified)	zh-Hans	Partial
Chinese (Traditional)	zh-Hant	Partial
Turkish	tr	Complete

The interface is marked for translation throughout: navigation, Home, Search, Library and collection pages, menus, the player bar, Queue and Lyrics, dialogs, keyboard shortcuts, sign-in, Settings and notifications, including tooltips and screen-reader names. The partial catalogues translate the earlier pilot: navigation, Library controls, the player bar, Queue and Lyrics. Everything they do not translate yet appears in English. The tray menu, the macOS menu bar and Dock menu, and the Windows taskbar buttons are still English in every language, as are error details reported by Spotify, the network or the system.

A regional system language uses the closest catalogue: es-MX and es-419 use Spanish, de-AT uses German, pt-BR and a plain pt use Portuguese (Brazil), other Portuguese regions use Portuguese (Portugal), zh-CN and zh-SG use Simplified Chinese, and zh-TW, zh-HK and zh-MO use Traditional Chinese. When the system lists several preferred languages, the first one with a catalogue wins.

Song, album, artist and playlist names come from Spotify or their creators and are kept as provided, as are lyric lines and failure details. Generated queue playlist names translate the surrounding words while retaining the song title or the date in YYYY-MM-DD form.

Edit and preview

The repository's assets/i18n/spotifast.pot is the English source template. Open the PO for your language, such as assets/i18n/es.po, in your translation editor. Edit msgstr values; keep msgid, msgid_plural, msgctxt, and placeholders such as {count}, {date}, {track} and {error} unchanged. Translator comments explain the placeholders. Clear a fuzzy flag only after reviewing the translation against its current English source.

Build and preview your changes in demo mode, which uses sample music data and needs no Spotify account. --demo-language takes a tag from the table above and overrides both the setting and the system language:

cargo run --features demo -- --demo --demo-language es
cargo run --features demo -- --demo --demo-language es --demo-show light --demo-size 760x620
cargo run --features demo -- --demo --demo-language de-DE --demo-show playing-next
cargo run --features demo -- --demo --demo-language ja --demo-show lyrics-follow

Check a narrow and a normal window, light and dark themes, keyboard navigation, and screen-reader names. --demo-shot PATH saves the preview and exits. When automating screenshots, give the process its own XDG config, data and state directories on Linux so framework window and scroll state do not carry between captures.

Panel fixtures also include queue-empty, queue-loading, queue-error, recents-empty, recents-loading, recents-error, lyrics-empty, lyrics-loading, lyrics-error, lyrics-instrumental and lyrics-no-playback. Combine a lyrics fixture with lyrics-fullscreen first to preview that state in full screen, for example --demo-show lyrics-fullscreen,lyrics-error.

Update the template and check catalogs

Maintainers mark source phrases with gettext(locale, "English text") and whole counted phrases with ngettext(locale, "Singular", "Plural", count). Use pgettext(locale, "context", "English text") when the same English word has different meanings. For example, Follow in the lyrics context follows the current lyric line, so its translation can differ from following an artist. Interpolate with named placeholders, such as gettext(locale, "Added {name}") followed by .replace("{name}", &name), and explain each one in a // Translators: comment above the phrase. Add any new source file to assets/i18n/POTFILES. With GNU gettext tools that support Rust installed, run:

.github/scripts/update-translations.sh
.github/scripts/update-translations.sh --check
cargo test --locked --test localization

The update command extracts the template with xgettext and merges it into existing PO files with msgmerge. The check command verifies the template and uses msgfmt to check catalog syntax and marked format placeholders. The localization tests also check that every translated phrase preserves its named placeholders, including phrases filled by string replacement. Submit changed PO files and the template, together with any required source changes. Generated Rust catalogs stay in Cargo's build directory and are not committed.

Normal application builds need no external gettext tools. The build validates the PO files and compiles their translations and plural expressions to Rust. Missing, empty, fuzzy, or incomplete plural entries fall back to the full English phrase, so a catalogue can be published before it is complete. The localization test requires completeness only of catalogues that claim it (currently Spanish); every catalogue must keep the placeholders of what it translates. Each locale's Plural-Forms header determines its plural choices; languages are not restricted to two forms.

Another language or a correction

Create another PO from the template using your editor's new-translation command, or msginit. Set its language and plural rules and translate what you can. A maintainer must also register the locale in the app, including how system language tags map to it, and preview it before it becomes available. Adding a PO alone does not add a language to the Settings list.

Use the translation problem form for incorrect wording, missing translations or text that does not fit. Each report gets its own issue. Include the language, version, affected control, and the text you see; a suggested correction is welcome. The catalog headers link to this form too.