Introduction

Members of a language team can add words and phrases to a spreadsheet and upload them to your language site dictionary in batches. This allows your team to work offline to prepare new dictionary entries and media files for upload, instead of using the FirstVoices website. This page is about how to structure your language data into a spreadsheet that will be accepted by the batch uploader.

An alternative to preparing a batch upload is to add and edit dictionary entries on the FirstVoices website. Check out our information about adding entries from the Dashboard.

Accepted columns in the spreadsheet

When creating a batch spreadsheet, all information that you wish to upload must be listed in a column with a header exactly matching the options below. Most headers match the fields in the “Create a Word/Phrase” form in the Dashboard.

The "intended use" for each column is just a guide for what the field should be used for. You and your team can make decisions together about how these fields are used for your language site. We recommend trying to maintain consistency across your entire dictionary.

Language entry columns

Header	Required?	Intended use	Example	Multiple columns allowed?
`TITLE`	♦ Required ♦	The word or phrase in the language, using the language site’s alphabet.	duus	❌
`TYPE`	♦ Required ♦	Choose one of two options: `word` or `phrase` . Determines whether this row is uploaded as a word or phrase.	`word` `phrase`	❌
`TRANSLATION`	Recommended	An explanation or definition, in English, of what the word/phrase means or how it is used. The translation can be literal or non-literal.	cat I have a cat.	✅
`CATEGORY`	Recommended	A descriptive grouping related to the word or its meaning. The text you enter should match the name of a category on your language site. Learn more about adding and editing categories to your language site. The text you enter must exactly match an existing category on your language site (e.g. it is case sensitive). If the category does not exist on the language site, the row will not upload.	Mammals Essential Phrases	✅
`PART_OF_SPEECH`	Recommended	The grammatical category that best describes the way the word is used in a sentence. The text you enter should match the name of a part of speech used on FirstVoices. Find the list here. This information is only relevant for words. It will not display for phrases.	Noun Transitive Verb	❌
`NOTE`	Optional	Any notes about the word/phrase or its meaning beyond its definition. Can include notes about what the word/phrase does or does not convey, cultural information about usage, literal translations, or information about the history of the word/phrase.	This word is only used when talking to small children. Literal translation: “Something that makes noise”	✅
`ACKNOWLEDGEMENT`	Optional	If the word/phrase is sourced from a dictionary, wordlist, or other reference, you can make a note of it here. It could be a citation, a link, or other information. You may also choose to include information about who was involved in contributing or compiling the word, instructions on reuse, or copyright.	Boas’s 1905 Dictionary, page 42 Compiled by Jane Doe, 1975 notes	✅
`PRONUNCIATION`	Optional	The pronunciation of a word in a linguistic or sound-it-out format that may not be a real spelling.	hi-tin-qis /speʔəθ/	✅
`ALTERNATE_SPELLING`	Optional	Indicate more possible spellings of the word that people will be able to search.	xsi ksi ksii	✅

How to add multiple translations, categories, etc.

Batch upload spreadsheets support adding multiple translations, categories, and other information, just like the website. For these “multiple” fields, you can add up to 5 columns. The additional columns should be followed by _2 , then _3, _4, _5 .

Example: To add 5 categories to the same word, you can create five different columns:

CATEGORY  CATEGORY_2  CATEGORY_3  CATEGORY_4  CATEGORY_5
Nature    Environment Games       Animals     Cultural Practices

Note: To add multiple columns, first column with no variation is required to recognize the rest of the columns.
e.g. CATEGORY is required in the above example for the rest of the columns to be recognized and imported.

Privacy columns

In addition to this basic information, further details can be added to both words and phrases:

Header

Required?

Intended use

Example

VISIBILITY

Optional

Who can see your language entry immediately after it is uploaded? If left blank, the content will be visible to the team only after uploading. It will need to be reviewed and published.

Choose from: team, members, public. Defaults to team.

team

members

public

INCLUDE_ON_KIDS_SITE

Recommended

Is the content suitable for young children? If so, the entry will be added to the Kids Area on your language site. If left blank, the content will be added to the Kids Area.

For “no”, write N, False, or 0. For "yes", write Y, True, or 1. Defaults to "yes".

Y

N

INCLUDE_IN_GAMES

Optional

Should the content be used in FirstVoices Games? If so, the entry may appear in games on your language site. If left blank, the content will be used in games.

For “no”, write N, False, or 0. For "yes", write Y, True, or 1. Defaults to "yes".

Y

N

Media columns

This feature is still under construction. Media files are not processed by the FirstVoices batch uploader at this time and will be skipped. Check back later!

For media files to be successfully uploaded and linked to words in the spreadsheet when the batch is processed, you'll also need to add the following columns. Here, “required” means what is necessary for the file to upload successfully.

Use AUDIO columns for an audio file, IMG columns for an image file, and VIDEO columns for a video file. Check here for the list of accepted media file types.

Header	Required?	Intended use	Example
`AUDIO_FILENAME` `IMG_FILENAME` `VIDEO_FILENAME`	♦ Required ♦	The name of the media file that will be uploaded. Must exactly match the name of one of the media files included in your batch submission.	`20190521_PB_cat_01.mp3` `cat_blink_TM2023.jpg`
`AUDIO_TITLE` `IMG_TITLE` `VIDEO_TITLE`	Recommended	Web-friendly title for the media. This title will be displayed when a visitor plays the audio/video or clicks on the image. If blank, then the `FILENAME` information will be used.	Elder saying “neko” (cat) Picture of Guarani traditional lands
`AUDIO_DESCRIPTION` `IMG_DESCRIPTION` `VIDEO_DESCRIPTION`	Optional	A longer, user-friendly description of how the recording or image came to be. Can include recording location, conditions, date etc.	A recording of the word “neko”, spoken by Jane Doe. Recorded at the FPCC office, May 2019.
`AUDIO_SPEAKER`	Recommended	The person speaking in an audio file. Visitors will be able to see the Speaker name before they play the file. Must exactly match the name of a Speaker on your language site. The text you enter must exactly match an existing speaker (e.g. it is case sensitive). If the speaker does not exist on the language site, the file will not upload. Add multiple: You can additional speakers in extra columns `AUDIO_SPEAKER_2`, `AUDIO_SPEAKER_3`, etc.	Jane Doe
`AUDIO_ACKNOWLEDGEMENT` `IMG_ACKNOWLEDGEMENT` `VIDEO_ACKNOWLEDGEMENT`	Recommended	Information about where the media file has been sourced from. For images and videos, this field can be used to acknowledge the artist, photographer, or videographer who created it. For audio, you may wish to acknowledge people involved in recording or processing the file. Warning: The FirstVoices team does not monitor whether or not media content is sourced appropriately. If FirstVoices receives a copyright strike against content on your language site that isn’t properly sourced, we may be legally required to remove all content that does not have source information.	Video by Peter Brown Photo sourced from Wikimedia Commons
`AUDIO_INCLUDE_IN_KIDS_SITE` `IMG_INCLUDE_IN_KIDS_SITE` `VIDEO_INCLUDE_IN_KIDS_SITE`	Optional	Is the media suitable for young children? If so, this media file will be displayed in the Kids’ Area. For “no”, write `N`, `False`, or `0`. For "yes", write `Y`, `True`, or `1`. Defaults to "yes".	`Y` `N`
`AUDIO_INCLUDE_IN_GAMES`	Optional	Is the media suitable to be used in FirstVoices Games? If so, this media file may be used in games. For “no”, write `N`, `False`, or `0`. For "yes", write `Y`, `True`, or `1`. Defaults to "yes".	`Y` `N`
`VIDEO_EMBED_LINK`	Optional	If you wish to link a video from Youtube or Vimeo to your dictionary entry, add the video URL in this column. This column is not related to any other video columns.	`https://youtu.be/4RxNvoO7CMw`

How to add multiple media files

To add a second media file of the same kind, you can add an additional set of columns where _2 is written after the media type. For example, a first set of columns labeled AUDIO can be followed by a second set of columns labeled AUDIO_2.

File #1 headers: AUDIO_TITLE, AUDIO_FILENAME, AUDIO_SPEAKER, AUDIO_SPEAKER_2, etc.
File #2 headers: AUDIO_2_TITLE, AUDIO_2_FILENAME, AUDIO_2_SPEAKER, AUDIO_2_SPEAKER_2, etc.

Available options for PART_OF_SPEECH

At this time you are not able to enter a custom PART_OF_SPEECH. You can choose from a fixed set of options shown in the list below:

Click here to view accepted parts of speech

Adjective
Adverb
Affirmation
Article/Determiner
Auxiliary Verb
Command
Conjunction
Connective
Demonstrative
Entity (Noun-like word)
Event/Activity (Verb-like word)
Interjection
Intransitive Verb
Modal
Modifier
Name
Negation
Noun
Noun Modifier
Number
Particle
Personal Pronoun
Plural Marker
Postposition
Prefix
Preposition
Pronoun
Quantifier
Question Marker
Question Word
Reciprocal Pronoun
Reciprocal Verb
Reflexive Pronoun
Reflexive Verb
Relative Pronoun
Root
Suffix
Tense/Aspect
Transitive Verb
Verb
Verb Modifier
Word Piece/Affix

Common errors to double check for

There are a few common errors made during batch preparation. Here are some things to double check before sending a batch spreadsheet to the FirstVoices team:

Are all the column headings spelled correctly? (i.e. AUDIO_TITLE, not AUDIOTITLE or AUDIO TITLE)
Does every row have word or phrase listed in the TYPE field?
Are all of the categories and speakers you reference in your spreadsheet spelled the same on your FirstVoices site, including their capitalization? (e.g. The category "Food" is not accidentally spelt "food" in your spreadsheet.)
Have you already created any new custom categories or speakers that you reference in your spreadsheet?
Are all of the parts of speech that you reference spelled the same as in the Parts of Speech list above?
Did you write the .wav or .mp3 extension after your filenames in the AUDIO_FILENAME column? (i.e. my-great-sound.mp3, not just my-great-sound)
Have you added information in the AUDIO_SPEAKER , IMG_ACKNOWLEDGEMENT , and VIDEO_ACKNOWLEDGEMENT columns, as needed?