Contributing to Jta

October 24, 2025 · View on GitHub

Thank you for your interest in contributing to Jta! This document provides guidelines and instructions for contributing.

🌟 Ways to Contribute

There are many ways to contribute to Jta:

🐛 Report bugs: Found an issue? Let us know!
💡 Suggest features: Have an idea? We'd love to hear it!
📖 Improve documentation: Help others understand Jta better
🔧 Fix bugs: Pick an issue and submit a PR
✨ Add features: Implement new capabilities
🧪 Write tests: Improve test coverage
🌍 Translate: Help translate Jta's own messages

🚀 Getting Started

Prerequisites

Go 1.25+: Install Go
Git: Install Git
AI Provider API Key: For testing (OpenAI, Anthropic, or Google)

Development Setup

Fork the repository

Click the "Fork" button on GitHub to create your own copy.

Clone your fork

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

Add upstream remote

git remote add upstream https://github.com/hikanner/jta.git

Install dependencies
```
go mod download
```

Set up environment variables

export OPENAI_API_KEY=sk-...
# Or use .env file (not tracked in git)
echo "OPENAI_API_KEY=sk-..." > .env

Run tests
```
go test ./...
```
Build the project
```
go build -o jta cmd/jta/main.go
```
Try it out
```
./jta examples/en.json --to zh
```

📝 Development Workflow

Creating a Feature Branch

Always create a new branch for your work:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
test/ - Test additions or modifications
refactor/ - Code refactoring
perf/ - Performance improvements

Making Changes

Write clean, readable code
- Follow Go conventions and best practices
- Use meaningful variable and function names
- Add comments for complex logic
- Keep functions focused and small
Add tests
- Write unit tests for new functions
- Ensure existing tests still pass
- Aim for high test coverage (target: 60%+)
Update documentation
- Update README.md if adding user-facing features
- Add godoc comments for exported functions
- Update CHANGELOG.md (if exists)

Code Style

We follow standard Go formatting:

# Format your code
gofmt -w .

# Run linter
golangci-lint run

# Check for common issues
go vet ./...

Testing

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with detailed coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific package tests
go test ./internal/translator/...

# Run with verbose output
go test -v ./...

Writing Tests

Follow these guidelines:

Test file naming: *_test.go
Test function naming: Test<FunctionName>
Table-driven tests for multiple scenarios:

func TestTranslate(t *testing.T) {
    tests := []struct {
        name     string
        input    string
        expected string
        wantErr  bool
    }{
        {
            name:     "simple translation",
            input:    "Hello",
            expected: "你好",
            wantErr:  false,
        },
        // More test cases...
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result, err := Translate(tt.input)
            if (err != nil) != tt.wantErr {
                t.Errorf("Translate() error = %v, wantErr %v", err, tt.wantErr)
                return
            }
            if result != tt.expected {
                t.Errorf("Translate() = %v, want %v", result, tt.expected)
            }
        })
    }
}

Committing Changes

We follow Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Adding or updating tests
refactor: Code refactoring
perf: Performance improvements
chore: Maintenance tasks
ci: CI/CD changes

Examples:

# Feature
git commit -m "feat(translator): add support for custom prompts"

# Bug fix
git commit -m "fix(format): preserve markdown bold syntax in translations"

# Documentation
git commit -m "docs(readme): add troubleshooting section"

# Multiple changes
git commit -m "feat(reflection): optimize quality check algorithm

- Reduce API calls by 30%
- Add batch processing for issues
- Improve error handling

Closes #123"

Submitting a Pull Request

Update your branch

git fetch upstream
git rebase upstream/main

Push to your fork

git push origin feature/your-feature-name

Create Pull Request
- Go to the original repository on GitHub
- Click "New Pull Request"
- Select your fork and branch
- Fill in the PR template
PR Checklist
- Tests pass (go test ./...)
- Code is formatted (gofmt -w .)
- Documentation is updated
- Commit messages follow conventions
- PR description explains changes clearly
- Linked to related issues (if any)

PR Review Process

Automated checks run (tests, linting)
Maintainers review your code
Address feedback if requested
Approval by at least one maintainer
Merge by maintainer

🏗️ Project Structure

Understanding the codebase:

jta/
├── cmd/
│   └── jta/
│       └── main.go          # CLI entry point
├── internal/
│   ├── cli/                 # Command-line interface
│   │   ├── app.go           # Main application logic
│   │   └── root.go          # Cobra root command
│   ├── domain/              # Domain models
│   │   ├── language.go      # Language definitions
│   │   ├── terminology.go   # Terminology models
│   │   └── translation.go   # Translation models
│   ├── provider/            # AI provider implementations
│   │   ├── openai.go        # OpenAI integration
│   │   ├── anthropic.go     # Anthropic integration
│   │   └── google.go        # Google Gemini integration
│   ├── translator/          # Translation engine
│   │   ├── engine.go        # Core translation logic
│   │   ├── batch.go         # Batch processor
│   │   └── reflection.go    # Reflection mechanism ⭐
│   ├── terminology/         # Terminology management
│   │   ├── manager.go       # Terminology manager
│   │   ├── detector.go      # LLM-based detection
│   │   └── repository.go    # JSON storage
│   ├── format/              # Format protection
│   │   └── protector.go     # Format element preservation
│   ├── incremental/         # Incremental translation
│   │   └── translator.go    # Diff analysis
│   ├── keyfilter/           # Key filtering
│   │   ├── filter.go        # Filter logic
│   │   └── matcher.go       # Pattern matching
│   ├── rtl/                 # RTL language support
│   │   └── processor.go     # Bidirectional text handling
│   ├── ui/                  # Terminal UI
│   │   ├── styles.go        # Lipgloss styles
│   │   └── printer.go       # Styled output
│   └── utils/               # Utilities
│       └── json.go          # JSON helpers
├── examples/                # Example files
│   └── en.json              # Sample source file
├── go.mod                   # Go modules
├── go.sum                   # Dependencies
├── README.md                # Main documentation
├── CONTRIBUTING.md          # This file
├── LICENSE                  # MIT License
└── EXECUTION_PLAN.md        # Development roadmap

🎯 Areas Needing Help

Current priorities:

High Priority

Provider tests: Add unit tests for AI provider implementations
Terminology tests: Test terminology detection and management
Integration tests: End-to-end translation workflows
Error handling: Improve error messages and recovery

Medium Priority

Performance optimization: Profile and optimize hot paths
Memory efficiency: Reduce memory usage for large files
Better progress indicators: Real-time translation progress
Configuration file support: YAML/TOML config files

Low Priority

Additional providers: Azure OpenAI, local models
Alternative formats: YAML, XML, PO file support
Translation memory: TMX integration
Web UI: Browser-based interface

🐛 Bug Reports

Before Submitting

Search existing issues to avoid duplicates
Try the latest version to see if it's already fixed
Collect information:
- Jta version (jta --version)
- Go version (go version)
- Operating system
- Steps to reproduce
- Expected vs actual behavior
- Error messages and logs

Bug Report Template

## Bug Description
A clear description of what the bug is.

## To Reproduce
Steps to reproduce the behavior:
1. Run command '...'
2. With file '...'
3. See error

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Environment
- Jta version: x.y.z
- Go version: 1.25.0
- OS: macOS 14.0
- Provider: OpenAI GPT-4o

## Logs

Paste relevant error messages or logs here


## Additional Context
Any other context about the problem.

💡 Feature Requests

Before Requesting

Search existing issues to see if it's already requested
Consider if it fits the project's goals
Think about implementation complexity

Feature Request Template

## Feature Description
A clear description of the feature you'd like.

## Use Case
Explain why this feature would be useful.
Example scenarios where you'd use it.

## Proposed Solution
How you envision this working.

## Alternatives Considered
Other approaches you've thought about.

## Additional Context
Mockups, examples, or references.