SonicFrame v1.3.2

Languages

Every word SonicFrame says (the names of the controls, the wave's value, the announcements and the wave in words) comes in five languages, or in one you bring.

Built in

English is the default. A tag finds its language the BCP 47 way: the whole tag first, then shorter and shorter, so 'es-MX' speaks Spanish and 'pt-PT-x-old' European Portuguese. Any other tag speaks English.

Tag Language Also found by
'en' English, as spoken in the United States 'en-US', 'en-GB'…
'pt' Portuguese, as spoken in Brazil 'pt-BR' and every other pt- tag but 'pt-PT'
'pt-PT' Portuguese, as spoken in Portugal Its longer tags
'es' Spanish 'es-ES', 'es-MX', 'es-419'…
'fr' French 'fr-FR', 'fr-CA'…

LANGUAGE_NAMES lists them. Numbers are written the way the tag writes them ("1,5×" in Portuguese), and so are the lengths in the wave in words ("33 secondes").

Picking one

a11y.lang picks the language of each piece; 'auto' takes the page's. Given to the player, it also marks the player with lang, so a screen reader speaks with a voice of that language.

// The player, with its plugins and the wave in words.
createPlayer({ container, src, a11y: { lang: 'es' } });

// The tag: <sonic-player src="/note.ogg" a11y-lang="fr"></sonic-player>

// A wave of your own: its plugins speak its language.
new SonicFrame({ container, media, a11y: { lang: 'pt-PT' }, plugins: [regions()] });

// The recorder, and the player of its recording.
createRecorder({ container, onSend, a11y: { lang: 'fr' } });

// The controls on their own.
PlayButton.create({ container, media, a11y: { lang: 'auto' } });
VolumeControl.create({ container, media, a11y: { lang: 'auto' } });

// The wave in words, written ahead on a server.
describeSound(outline, { lang: 'fr' });

This player's buttons are named in Spanish: inspect them, or tab through them with a screen reader on.

Your own words

Any phrase can be replaced over the language's: the player's a11y.labels (see Screen readers), the controls' labels, and the words of the markers, the chapters, the regions (a11y.words), the minimap and the wave in words.

markers({ marks, words: { more: '+{count}' } });
regions({ a11y: { words: { loopOn: 'repeating' } } });

Bringing a whole language

registerLanguage(tag, words) teaches SonicFrame a language at run time, before the players are made; every piece whose tag finds it speaks it. The words must be whole, every phrase of English with the same marks, and each phrase is cleaned to one safe line. It returns false for a built-in tag, a tag that is not BCP 47, words with a problem, or past a hundred languages; languageProblems(words) says what is wrong.

import { languageProblems, registerLanguage, type Words } from 'sonicframe';

const ja: Words = {
    frame: { position: '…' },
    playButton: { play: '…', pause: '…' },
    // …every other group of English, each phrase in Japanese
};

if (!registerLanguage('ja', ja)) {
    console.warn(languageProblems(ja));
}

createPlayer({ container, src, a11y: { lang: 'ja-JP' } });

The groups and their phrases are those of the Words type; the English file, src/core/languages/en.ts, is the model.

A language written for 1.0 keeps working: the phrases added since (the player's previousTrack and nextTrack, and the playlist group) may be left out, and are then said in English until you add them; a phrase you do give is checked like the others. wordsFor(tag) gives every phrase, as the CompleteWords type.

Adding a language to SonicFrame

A language for everyone is one file and one line, sent as a pull request. The tests check it by themselves. Adding a language walks through it. These docs stay in English.

In a plugin

A plugin reads the frame's tag in host.lang ('en' unless the app picks one) to choose its own words. See the Plugin API.