# Contributing to Yoruba.ca

Yoruba.ca is an open, free resource for Yoruba language learning and cultural knowledge. Contributions are welcome from native speakers, heritage learners, teachers, translators, researchers, developers, artists, and careful readers.

The most valuable contribution is a well-sourced correction. You do not need to be a developer to help.

## Ways to help

- Correct Yoruba spelling, tone marks, translations, or explanations.
- Add a word, phrase, lesson example, or short dialogue with context.
- Record or review rights-cleared audio with speaker consent.
- Document a dialect or regional variation without presenting it as universal.
- Add a citation, archive link, textbook reference, or community source.
- Improve accessibility, keyboard navigation, mobile layout, tests, or documentation.
- Report a broken link, encoding problem, or content that needs review.

## Before submitting language content

1. Check the existing content and avoid duplicating an entry.
2. Use Unicode Yoruba characters such as `ẹ`, `ọ`, `ṣ`, `Ẹ`, `Ọ`, and `Ṣ`.
3. Keep tone marks exactly as supplied by the source or reviewer.
4. Record what the phrase means in context, not only a word-for-word gloss.
5. Add a source and explain whether the form is general, regional, family-specific, historical, or uncertain.
6. Ask a native speaker or qualified Yoruba teacher to review pronunciation, tones, and cultural usage where possible.
7. Leave `reviewStatus` as `needs-native-review` unless the review is documented.

## Content entry shape

Vocabulary lives in `content/vocabulary/`. Lessons live in `content/lessons/`. The JSON Schemas in `schemas/` describe the reusable fields used by the website, future flashcards, search, downloads, and APIs.

A vocabulary entry should include:

- `id`, `yoruba`, `english`, and a useful `category`.
- `literalMeaning` only when it helps and is supported by a source.
- `pronunciation` only when the guidance is sourced or explicitly marked as needing review.
- `audio` only for a rights-cleared file with consent and metadata.
- `reviewStatus`, contributors, and sources.

Do not invent translations, tones, pronunciations, etymologies, dialect claims, or cultural explanations to fill an empty field. A visible `null` or review label is better than false certainty.

## Audio

Audio must be recorded or shared with permission. Include the speaker's name or attribution, consent status, dialect or region when the speaker wants it recorded, recording date when useful, and the source file path. Do not copy recordings from another service without rights clearance.

## Pull requests

Keep pull requests focused. Explain what changed, which source or reviewer supports it, and what remains uncertain. Run:

```sh
npm run check
```

A content-only pull request should still pass JSON, Unicode, link, and test checks. Reviewers may ask for a native-speaker review before merging.

## Native-speaker review workflow

1. A contributor opens an issue or pull request and labels uncertain content `needs-native-review`.
2. A native speaker, teacher, or qualified linguist reviews the exact Yoruba text, tones, meaning, usage, and any dialect note.
3. The reviewer records their preferred attribution and the scope of their review in the pull request.
4. Maintainers update the entry status to `verified`, `disputed`, or `deprecated`, or keep it in the review queue.
5. The changelog or pull request records what was reviewed and what remains open.

Review is content-specific. A person may be able to verify a greeting but not an etymology or a regional claim.

## Suggested issue labels

Use these labels when opening or triaging work:

- `good first issue`
- `translation`
- `audio needed`
- `native review needed`
- `lesson content`
- `documentation`
- `accessibility`
- `data quality`

See the issue templates for beginner-friendly prompts.

## Attribution and conduct

Contributors are credited in content metadata when they choose to be named. Please read the [Code of Conduct](CODE_OF_CONDUCT.md) before participating. This project values correction, context, and respect across generations, regions, and levels of fluency.