How to use the tools
A guide to the siSwati
Diacritics tools
This site has three tools. Each one plays a different role in building a tonal record of siSwati. This guide explains what each tool does and how to use it step by step.
Contents
Word Database
A list of siSwati words that look identical when written but mean different things depending on tone. This database collects candidates for expert review.
What you see on the page
Stats row at the top shows a live count of all words, how many are Pending, Validated, and Rejected.
Search bar — type any part of a word or its meaning to filter the list instantly.
Filter buttons — narrow the list by validation status: Pending Validated Rejected
Word table — each row shows the base word, its tonal variants (accented forms), meanings, and status.
Adding a new word
Click the + Add word button in the top-right of the page. A panel will open.
Base word — type the word as it is normally written, without any accent marks. Example: bana
Validation status — leave this as Pending unless a siSwati linguistic expert has already reviewed it.
Source — note where the word came from, for example: "community suggestion" or "Doke & Vilakazi 1953".
Diacritic variants — this is the core of each entry. Add one row per tonal form of the word. Each row has four fields:
Form
The accented spelling, e.g. bána or banà. Use the Keyboard tool (Tool 2) to type these.
Tone
The tone pattern using H (high), L (low), F (falling). Example: HH, LF.
IPA
International Phonetic Alphabet transcription, if known. Example: /ɓána/. Leave blank if unsure.
Meaning
What this tonal form means in English. Example: children or theirs.
Click + Add variant to add more rows for words with more than two tonal forms.
Notes — optional. Add any context about the word, how it is used, or decisions made during validation.
Click Save word. The word appears in the table immediately.
Editing and managing words
Edit — click anywhere on a word row, or click the pencil icon on the right. The same panel opens with the word's current data pre-filled. Make your changes and click Save word.
Cycle status — click the circular arrows icon to move a word through the status sequence: Pending → Validated → Rejected → back to Pending. Only mark a word as Validated after an expert linguist has reviewed it.
Delete — click the bin icon. You will be asked to confirm before the word is permanently removed.
Exporting and importing data
Export CSV — downloads the entire database as a spreadsheet-compatible file. Useful for sharing with a linguist or opening in Excel.
Export JSON — downloads the data as a structured JSON file. Used by the pipeline software.
Import JSON — load a previously exported JSON file back into the database. New words are added; existing words with the same base form are updated.
Diacritics Keyboard
A text editor that lets you type siSwati words with the correct tone marks (acute, grave, circumflex) that standard keyboards cannot produce easily.
Understanding the tone marks
Acute accent ( ´ ). Marks a rising or high-pitched syllable.
Grave accent ( ` ). Marks a falling or low-pitched syllable.
Circumflex ( ^ ). Used for mid or falling-rising tones in Bantu notation.
Method 1 — Click to insert
The simplest method. No keyboard shortcuts to learn.
Click in the large white text area (the editor) and position your cursor where you want the character.
Find the vowel you want in the Character palette below the editor. Each vowel (A, E, I, O, U, N) has a row with its plain form and tonal variants.
Click the character. It is inserted into your text at the cursor position.
Method 2 — Compose mode (keyboard shortcuts)
For faster typing once you are comfortable with the shortcuts.
Click the Compose mode button in the toolbar. It turns gold when active.
Type a trigger key, then immediately type the vowel you want to accent:
Apostrophe + vowel = high tone
Backtick + vowel = low tone
Caret + vowel = mid / circumflex
Toolbar buttons
Copies everything in the editor to your clipboard so you can paste it elsewhere.
Saves the editor contents as a .txt file to your device.
Removes all text from the editor. You will be asked to confirm first.
Highlight a word or phrase in the editor, then click this button to save it to your Saved words list on the right side of the page.
Toggles between lowercase and uppercase for the character palette buttons.
Saved words panel
The Saved words panel appears on the right side on wider screens (on mobile it is hidden). It stores words or phrases you have saved from the editor.
To save a word: highlight it in the editor with your mouse, then click Save selection.
To re-insert a saved word: click its name in the panel. It will be inserted at your cursor in the editor.
To export your saved words as a text file, click Export glossary (.txt) at the bottom of the panel.
Contribute Your Voice
Record yourself reading 10 siSwati words aloud. Your recordings are saved on your device and can be shared with the initiative to help train AI pronunciation systems.
Before you start
Use a modern browser: Chrome, Firefox, Edge, or Safari 15+.
Allow microphone access when the browser asks. Without it, recording will not work.
Find a quiet space. Background noise affects recording quality.
The whole session takes about 3 minutes.
Fill in the short form
Before recording begins, you are asked four quick questions. This information helps researchers understand the diversity of speakers in the dataset.
Optional. You can leave this blank or use a first name only.
Select the range that applies to you: Under 18, 18–35, 36–55, or 56+.
Select your region: Hhohho, Manzini, Shiselweni, Lubombo, or Diaspora.
Is siSwati your first language? If you select No, a field appears asking what your first language is.
Once all questions are answered, click Start recording →
Record each word
You will go through 10 words one at a time. A progress bar at the top shows how far along you are.
Read the large word displayed on the card. Say it naturally and clearly, the way you would in normal speech.
Tap the large red microphone button to start recording. The button pulses red and a timer appears while it is active.
Tap the button again (it now shows a stop square) to stop. Recording also stops automatically after 10 seconds.
A playback bar appears. Listen to your recording. If it sounds good, click Next → to move to the next word.
Re-record
Not happy with the recording? Click Re-record to discard it and try again.
Skip
Don’t know a word or prefer not to record it? Click Skip to move on without recording.
Next
Appears after a successful recording. Click to save this recording and go to the next word. On the last word it becomes Finish.
Download and share
After the last word, a completion screen shows how many words you recorded.
Click Download ZIP. A compressed file downloads to your device containing all your audio files and a metadata summary.
Click Send to mseshov@gmail.com to open your email app with the address pre-filled. Attach the ZIP file and send it to contribute your recordings to the initiative.
Want to do another session? Click Record another session to go back to the start.
siSwati Diacritics Initiative — helping AI speak siSwati correctly.