Add translations and transliteration support to lyrics

[adaliea]

TL;DR

Adds a new Languages tab that lets users generate, edit, and import translations and transliterations for lyric lines, with full round-trip support through TTML export/import.

Transliterations show up in the timeline & synced tab (optional!)

What changed?

• A new Languages panel (src/views/languages.tsx) is introduced as a first-class tab between Edit and Sync. On entry it automatically calls the Google Translate API to generate transliterations and English translations for all lyric lines. Results are editable per-line and marked as stale when the source text changes.
• A LanguageProvider abstraction (src/services/language-provider.ts) and a googleLanguageProvider implementation (src/services/google-language-provider.ts) handle translation and transliteration requests with concurrency limiting, response caching, and non-Latin script detection/fallback.
• New domain types (TransliterationTrack, TranslationTrack, TranslationTracks) are added to the lyric line model. translations and transliteration fields are propagated through group templates, instance expansion, and the timeline fill/copy operations.
• A paste-import modal (src/views/languages/paste-import-modal.tsx) handles multi-line clipboard pastes into any language field, with automatic blank-line alignment strategies ("preserve", "compact", "manual") and per-line editable mapping before committing.
• Transliteration text is aligned to word timing slots via alignTransliterationToWords (src/domain/language/align.ts), which maps dash-separated syllables to split timing slots and space-separated words to canonical source-word boundaries.
• The syllable splitter (both Sync and Timeline variants) gains a paired transliteration split picker: when a word carries a transliteration field, a secondary character picker is shown for the romanized text, and both sets of split points are applied together via splitWordIntoSyllables.
• The Sync panel and Timeline each gain an "Original / Transliteration" toggle button (keyboard shortcut L) that switches all displayed word labels to their aligned transliteration equivalents without altering timing data. The toggle state lives in useTimelineStore.
• TTML export (src/utils/ttml.ts) now emits itunes:key attributes on <p> elements and writes an <iTunesMetadata> block containing <translations> and <transliterations> sidecars. Timed transliteration words are emitted as individual <span> elements with proportional timing; untimed syllables use single spaces and word boundaries use double spaces.
• TTML import (src/utils/lyrics-parsers/ttml-alternates.ts) parses the <iTunesMetadata> block and populates translations and transliteration on the corresponding lyric lines, including background text variants.
• The saved project format is bumped to version 2. Version 1 projects are migrated transparently on load; the new fields are optional so existing lyric objects remain valid.
• Keyboard shortcut global.goToLanguages is added as Mod+3, and the existing Sync/Timeline/Preview/Export shortcuts shift up by one.
• A languageSourceFingerprint utility produces a stable hash of a line's text and background text, used to detect when generated language content has gone stale.
• Script detection utilities (src/domain/language/script-detection.ts) identify non-Latin scripts by Unicode property and map them to BCP 47 language codes for use as transliteration source hints.

How to test?

1. Open the app with lyrics loaded and navigate to the new Languages tab (Mod+3). Verify that transliteration and English translation fields populate automatically.
2. Edit a transliteration field manually; confirm it is preserved on subsequent "Regenerate" clicks and marked with "Needs review" when the source lyric changes.
3. Paste more than three lines of text into any language field and confirm the paste-import modal opens with correct line mapping. Test all three alignment strategies by varying blank lines.
4. In the Sync or Timeline panel, click the Original / Transliteration toggle (or press L) and verify that word labels switch to romanized text while timing is unaffected.
5. Open the syllable splitter on a word that has a transliteration (e.g. a Korean word after generating transliteration). Confirm a secondary split picker appears for the romanized text and that splitting produces correctly paired transliteration fields on the resulting words.
6. Export a project with translations and transliterations to TTML, then re-import it and verify that translations and transliteration fields round-trip correctly, including background text.
7. Load a version 1 project file and confirm it opens without errors and is silently upgraded to version 2.

Why make this change?

Lyric files distributed through platforms like Apple Music carry translations and transliterations alongside the timed text. This feature closes that gap by giving authors a dedicated workflow to generate, review, and manually correct alternate-language content, and by ensuring that content survives the full edit → sync → export → import round-trip in the TTML format.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	composer	cd571e9	Commit Preview URL	Jul 20 2026, 07:11 AM

[adaliea]

• Add translations and transliteration support to lyrics #152 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

React Doctor found no new issues. 🎉

_{Reviewed by React Doctor for commit cd571e9.}