Contributing to Speechify

July 13, 2025 · View on GitHub

Thank you for your interest in contributing to Speechify! This document provides guidelines and information for contributors.

🎯 Project Overview

Speechify is a VS Code extension that converts text to speech using Azure Speech Services. Our goal is to provide an accessible, high-quality, and user-friendly text-to-speech solution for developers and content creators.

🛠️ Development Setup

Prerequisites

Node.js: Version 16.x or higher
VS Code: Latest stable version
Git: For version control
Azure Account: For testing speech services (optional but recommended)

Getting Started

Fork and Clone

git clone https://github.com/YOUR_USERNAME/speechify.git
cd speechify

Install Dependencies
```
npm install
```

Set Up Development Environment

# Compile TypeScript
npm run compile

# Start watch mode for development
npm run watch

Create Test Configuration (Optional)

# Create test-config.json for Azure API testing
cp test-config.example.json test-config.json
# Edit with your Azure credentials (never commit this file!)

Run Tests
```
npm run test:integration
npm run lint
```

📁 Project Structure

speechify/
├── src/
│   ├── extension.ts          # Main extension entry point
│   ├── types/               # TypeScript type definitions
│   ├── utils/               # Utility functions
│   ├── services/            # Core business logic
│   ├── i18n/               # Internationalization
│   └── test/               # Test suites
├── .github/                # GitHub templates and workflows
├── package.json            # Extension manifest
└── README.md              # Documentation

🎨 Coding Standards

TypeScript Guidelines

Strict Mode: All code must compile with strict TypeScript settings
Type Safety: Use explicit types, avoid any when possible
Naming: Use camelCase for variables/functions, PascalCase for classes/types
Comments: Document complex logic and public APIs

Code Style

// ✅ Good
interface VoiceSettings {
    name: string;
    style?: string;
    role?: string;
}

async function convertTextToSpeech(text: string, settings: VoiceSettings): Promise<void> {
    // Implementation with proper error handling
}

// ❌ Avoid
function doStuff(data: any): any {
    // No error handling, unclear naming
}

Internationalization

Always use i18n: Never hardcode user-facing strings
Message Keys: Use hierarchical naming (e.g., commands.convert.success)
Placeholders: Use typed interpolation for dynamic content

// ✅ Correct
vscode.window.showInformationMessage(I18n.t('commands.convert.success', fileName));

// ❌ Wrong
vscode.window.showInformationMessage('Conversion completed');

🧪 Testing

Test Categories

Unit Tests: Test individual functions and classes
Integration Tests: Test VS Code extension integration
Azure API Tests: Test real Azure Speech Services (requires credentials)

Writing Tests

suite('Voice Configuration', () => {
    test('should validate voice settings', () => {
        const settings = { name: 'en-US-JennyNeural', style: 'friendly' };
        assert.ok(validateVoiceSettings(settings));
    });
});

Test Requirements

All new features must include tests
Tests should cover both success and error scenarios
Use descriptive test names and clear assertions
Mock external dependencies when possible

🌍 Internationalization

Adding New Languages

Create language file: src/i18n/[locale].ts
Implement the Messages interface
Add locale detection in src/i18n/index.ts
Update VS Code localization files: package.nls.[locale].json

Translation Guidelines

Maintain consistent terminology across languages
Consider cultural context and conventions
Use native speakers for review when possible
Test UI layouts with longer text strings

🔧 Pull Request Process

Before Submitting

Test Thoroughly

npm run compile
npm run lint
npm run test:integration

Update Documentation
- Update README.md if adding features
- Add/update code comments
- Update CHANGELOG.md

Follow Commit Convention

feat: add voice role selection feature
fix: resolve audio file naming issue
docs: update contributing guidelines
refactor: improve error handling logic
test: add integration tests for Azure API