Skip to content

feat: add seekValueText option to localize seek slider aria-valuetext - #13

Merged
arraypress merged 1 commit into
WaveformPlayer:mainfrom
jeryj:feat/seek-value-text-i18n
Jul 4, 2026
Merged

arraypress merged 1 commit into
WaveformPlayer:mainfrom
jeryj:feat/seek-value-text-i18n

Conversation

@jeryj

@jeryj jeryj commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Summary

The seek slider's spoken aria-valuetext is hardcoded to English `${formatTime(current)} of ${formatTime(duration)}` in updateSeekAccessibility(), so consumers (e.g. WordPress/Gutenberg, which needs to translate it) have no way to localize the connective word — the only supported accessibility option today is seekLabel.

This adds a small, opt-in seekValueText option (mirroring the existing seekLabel/errorText string options) that templates the value text. The library keeps formatting the times, so a consumer supplies only a translated string and does no time math of its own.

What changed

  • seekValueText option (themes.js DEFAULT_OPTIONS, default null), also settable via data-seek-value-text (parseDataAttributes).
  • formatSeekValueText(template, ...args) helper in utils.js — printf-style interpolation supporting positional (%1$s/%2$s), sequential (%s), and reordered args, so a translation can reorder the current time and duration. Unmatched placeholders are left intact.
  • updateSeekAccessibility() now interpolates this.options.seekValueText || '%1$s of %2$s'.
  • Types (index.d.ts) and CHANGELOG.md updated; dist/ rebuilt.

Backward compatibility

The default '%1$s of %2$s' produces byte-for-byte identical output to the previous hardcoded string. The pre-existing test asserting aria-valuetext === '0:30 of 2:00' still passes unchanged.

Accessibility note

aria-valuetext is screen-reader-announced, so the natural-language "of" connective (over a symbol like /) is intentional — this change makes that connective translatable rather than replacing it.

Tests

  • 3 integration tests (custom Spanish template, reordered positional args, data-* path) in test/player.test.js.
  • 4 unit tests for formatSeekValueText (positional, sequential, reorder, missing-arg passthrough) in test/utils.test.js.
  • Full suite: 89 passing.

Bundle size

+109 B gzip (12043 → 12152).

Example

new WaveformPlayer('#player', {
  url: '/track.mp3',
  seekValueText: '%1$s de %2$s', // Spanish → "0:30 de 2:00"
});

🤖 Generated with Claude Code

The seek slider's spoken `aria-valuetext` was hardcoded to English
`${current} of ${duration}`, leaving consumers no way to translate it.

Add a `seekValueText` option (and matching `data-seek-value-text`
attribute) that templates the value text with printf-style placeholders —
`%1$s` current time, `%2$s` total duration — interpolated by a shared
`formatSeekValueText` helper that supports positional, sequential (`%s`),
and reordered args for translation. It defaults to `'%1$s of %2$s'`, so
existing output is byte-for-byte unchanged. The library still formats the
times, so consumers only supply a translated string.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
jeryj added a commit to WordPress/gutenberg that referenced this pull request Jul 2, 2026
Expose the waveform player's seek control as a keyboard-operable ARIA
slider with a translated accessible label and value text, on both the
editor and the front end.

The strings are localized with @wordpress/i18n (and esc_attr_x on the
server) and handed to @arraypress/waveform-player through its native
`seekLabel` and `seekValueText` options via data attributes. The library
owns all time formatting and interpolates the current time and duration
into the slider's aria-valuetext; Gutenberg only supplies the translated
templates, with no client-side patching of library internals.

Consolidates the seek-accessibility work from #78980 using the library's
native seek options. Full non-English value-text localization depends on
the `seekValueText` option (WaveformPlayer/waveform-player#13), so bump
@arraypress/waveform-player once it is released.

Co-authored-by: Ben Dwyer <ben@scruffian.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@arraypress
arraypress merged commit 7b63126 into WaveformPlayer:main Jul 4, 2026
arraypress added a commit that referenced this pull request Jul 4, 2026
Follow-up to seekValueText (#13): the last hardcoded English strings are
now options (each also settable via data-*), so non-English UIs can
translate every screen-reader / lock-screen string.

- playPauseLabel   — play button aria-label     (default 'Play/Pause')
- speedLabel       — speed button + menu label   (default 'Playback speed')
- artworkAlt       — artwork <img> alt text       (default 'Album artwork')
- unknownTrackText — Media Session title fallback (default 'Unknown Track')

Rendered aria-labels/alt are escaped via escapeHtml. Defaults reproduce
the previous output, so existing behavior is unchanged. Updates
index.d.ts, CHANGELOG, and adds unit + integration tests (94 passing).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
scruffian added a commit to WordPress/gutenberg that referenced this pull request Jul 7, 2026
* Playlist: add localized, keyboard-accessible waveform seek control

Expose the waveform player's seek control as a keyboard-operable ARIA
slider with a translated accessible label and value text, on both the
editor and the front end.

The strings are localized with @wordpress/i18n (and esc_attr_x on the
server) and handed to @arraypress/waveform-player through its native
`seekLabel` and `seekValueText` options via data attributes. The library
owns all time formatting and interpolates the current time and duration
into the slider's aria-valuetext; Gutenberg only supplies the translated
templates, with no client-side patching of library internals.

Consolidates the seek-accessibility work from #78980 using the library's
native seek options. Full non-English value-text localization depends on
the `seekValueText` option (WaveformPlayer/waveform-player#13), so bump
@arraypress/waveform-player once it is released.

Co-authored-by: Ben Dwyer <ben@scruffian.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Update waveform player to 1.20

---------

Co-authored-by: Ben Dwyer <ben@scruffian.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
peterwilsoncc pushed a commit to peterwilsoncc/gutenberg-build that referenced this pull request Jul 7, 2026
* Playlist: add localized, keyboard-accessible waveform seek control

Expose the waveform player's seek control as a keyboard-operable ARIA
slider with a translated accessible label and value text, on both the
editor and the front end.

The strings are localized with @wordpress/i18n (and esc_attr_x on the
server) and handed to @arraypress/waveform-player through its native
`seekLabel` and `seekValueText` options via data attributes. The library
owns all time formatting and interpolates the current time and duration
into the slider's aria-valuetext; Gutenberg only supplies the translated
templates, with no client-side patching of library internals.

Consolidates the seek-accessibility work from #78980 using the library's
native seek options. Full non-English value-text localization depends on
the `seekValueText` option (WaveformPlayer/waveform-player#13), so bump
@arraypress/waveform-player once it is released.

Co-authored-by: Ben Dwyer <ben@scruffian.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Update waveform player to 1.20

---------

Co-authored-by: Ben Dwyer <ben@scruffian.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Source: WordPress/gutenberg@c4e7e5b
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants