Branch: master
Find file Copy path
155 lines (97 sloc) 6.39 KB

Contributing to Common Voice

🎉 First off, thanks for taking the time to contribute! This project would not be possible without people like you. 🎉

Code of Conduct

By participating in this project, you're agreeing to uphold the Mozilla Community Participation Guidelines. If you need to report a problem, please see our guide.

How Can I Contribute?

Add More Sentences

Help us add more sentences for other volunteers to read. See this topic for details.

Bug Fixes and Feature Enhancements

All of our current issues can be found here on GitHub. Anything with a help wanted tag is definitely up for grabs. If you're interested in an issues without this tag, best to ask first to make sure our vision of it aligns.

Project requirements

Docker setup

We provide a docker-compose setup to orchestrate the local development environment configuration using docker.


Fork and clone the repository onto your computer. Then run the following commands to spin off voice-web:

> cd voice-web
> docker-compose up

This is going to:

  • Launch a mysql instance configured for voice-web
  • Launch an s3proxy instance to store files locally and avoid going through setting up AWS S3.
  • Mount the project using a docker volume to allow reflecting changes to the codebase directly to the container.
  • Launch voice-web server

You can visit the website at http://localhost:9000.

Local setup


Fork and clone the repository onto your computer.

Either create a MySQL root user that conforms to the default DB_ROOT_USER and DB_ROOT_PASS in /server/src/config-helper.ts or create your own config.

Then cd into the project directory and enter the following commands:

yarn start

This will:

  1. Install all JavaScript dependencies.
  2. Build and serve files located in the web folder on localhost.
  3. Save uploaded voice clips onto Amazon's S3.
  4. Lint and rebuild all js files on every change.

You can then access the website at http://localhost:9000.


You can find configurable options, like the port CommonVoice is running on, in /server/src/config-helper.ts. Just create a /config.json with the config you want to override.

If you want to work with login-related features (Profile, Dashboard, Goals, ...) you'll need to create an Auth0 account and put the data you get from it into the config (the keys are AUTH0: { DOMAIN, CLIENT_ID, SECRET }).

Setting up Amazon S3 for development

The Common Voice project uses S3 for voice clip storage. If you need help configuring S3, check out

Adding migrations

We use db-migrate for running database migrations.

To add a migration run: yarn migrate create <MIGRATION_NAME>. At the moment you manually have to change the migration file extension to .ts. A migration has to expose the following API:

export const up = async function(db: any): Promise<any> {
  return null;

export const down = async function(): Promise<any> {
  return null;

Migrations are always run when the server is started.

Making Strings localizable

We're using Fluent to localize strings. You can find examples all over the frontend code. Strings that appear in the english message files, can then be translated on Pontoon. Some things to note regarding string changes are documented on MDN.

Import languages

To update the list of locales run:

yarn import-locales

This creates/updates files in /locales:

  • fetch locale codes & names from Pontoon and save them in all.json
  • based on Pontoon translated data and a threshold defined in the script, save "completed" locales to completed.json
  • add codes that have a sentence folder in /server/data to contributable.json

Need Help?

For more options, just type:

yarn run

Project Directory Structure

The project is organized into the following directories:

  • android: The Android app, a simple webview wrapper of This app is currently not published.
  • docs: Design and data specifications for Common Voice.
  • ios: The iOS app. This is a simple wrapper app for the website, as a workaround for a microphone issue in Safari.
  • nubis: Configuration files for Nubis, our deployment tool.
  • server: The server-side app logic, written in TypeScript.
  • tools: Some scripts for managing data.
  • web: The Common Voice website files, written in TypeScript. We use React to build the website.

Submitting an Issue

Did you notice a bug? Do you have a feature request? Please file an issue here on GitHub.

Something Else?

Want to talk about something but can't find a home for it here? Head to our Discourse Category to discuss everything from feedback and ideas to questions and random musings.