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.