# Japanese Bible Translator

A machine-assisted Bible translation system that generates modern Japanese translations from original Greek (New Testament) and Hebrew (Old Testament) source texts using Claude AI.

> **Disclaimer**: This project produces AI-generated translations for experimental and educational purposes. These translations are not endorsed by any religious organization and should not be used as authoritative scripture. Always consult established translations and qualified scholars for serious biblical study.

## Features

- **Full Bible Support**: Translate all 66 books (39 OT + 27 NT)
- **Source Text Fidelity**: Works directly from MorphGNT (Greek) and MorphHB (Hebrew) morphologically-tagged texts
- **Parallel Processing**: Fault-tolerant orchestration with multiprocessing for efficient batch translation
- **Translation Memory**: Maintains consistency across translations with segment reuse
- **Pericope-Based Translation**: Translates coherent narrative units for better contextual accuracy
- **Configurable Style**: Adjust equivalence approach, formality, gender language, and theological tradition
- **Automatic Evaluation**: Quality scoring based on configurable criteria
- **Progress Tracking**: SQLite-based job state with crash recovery and resume capability
- **Rich CLI**: Progress bars, status displays, and interactive TUI viewer

## Requirements

- Python 3.11+
- [uv](https://github.com/astral-sh/uv) (recommended) or pip
- [Claude CLI](https://claude.ai/claude-code) with active Anthropic subscription

> **Note**: This project requires the Claude CLI binary (`claude`) which requires an Anthropic subscription. API costs will apply for translations.

## Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/j-t-bible-translator.git
cd j-t-bible-translator

# Install dependencies
uv sync

# Install dev dependencies (for testing)
uv sync --extra dev
```

## Quick Start

### 1. Download Source Texts

```bash
# Download all Bible source texts (Greek NT, Hebrew OT, reference translations)
uv run python scripts/download_sources.py --all
```

### 2. Translate a Single Verse

```bash
uv run python main.py verse john:1:1
```

### 3. Translate a Chapter

```bash
uv run python main.py chapter john 1
```

### 4. Translate an Entire Book

```bash
uv run python main.py book john
```

### 5. Full Bible Translation (Parallel)

```bash
# Translate all 66 books with 4 parallel workers
uv run python main.py bible --parallel 4

# NT only
uv run python main.py bible --nt-only

# OT only
uv run python main.py bible --ot-only

# Specific books
uv run python main.py bible --books john matthew genesis psalms
```

### 6. Resume Interrupted Translation

```bash
# Resume the most recent incomplete job
uv run python main.py resume

# Resume a specific job
uv run python main.py resume --job-id <job-id>
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `verse <ref>` | Translate a single verse (e.g., `john:1:1`) |
| `chapter <book> <num>` | Translate a chapter |
| `book <name>` | Translate an entire book |
| `bible` | Full Bible translation with parallel processing |
| `resume` | Resume an interrupted translation job |
| `job-status <id>` | Check status of a translation job |
| `jobs list` | List all translation jobs |
| `jobs clean` | Clean old jobs from database |
| `jobs stats` | Show database statistics |
| `status <book>` | Show translation progress for a book |
| `export <book> <formats>` | Export translations (json, text, html) |
| `style show` | Show current translation style settings |
| `style edit` | Modify translation style settings |
| `evaluate <book> --chapter <n>` | Evaluate translation quality |
| `pericope list <book>` | List pericopes for a book |
| `pericope translate <id>` | Translate a specific pericope |
| `tm status` | Show translation memory statistics |
| `tui` | Launch interactive TUI viewer |

## Translation Style Configuration

Configure translation approach via CLI or `data/config/style.json`:

```bash
# Show current style
uv run python main.py style show

# Edit style settings
uv run python main.py style edit --equivalence dynamic --formality standard
```

### Available Options

| Setting | Options |
|---------|---------|
| Equivalence | `formal`, `dynamic`, `optimal` |
| Gender Language | `traditional`, `moderate_inclusive`, `fully_inclusive` |
| Readability | `scholarly`, `general_public`, `children` |
| Theological Tradition | `evangelical`, `catholic`, `orthodox`, `ecumenical` |
| Term Consistency | `strict`, `balanced`, `contextual` |
| Formality | `casual`, `standard`, `formal` |

## Project Structure

```
j-t-bible-translator/
├── main.py                 # CLI entry point
├── src/
│   ├── context/           # Context building (glossary, pericopes, TM)
│   ├── data/              # Data loading and storage
│   ├── evaluation/        # Translation quality evaluation
│   ├── models/            # Data models
│   ├── orchestration/     # Parallel job orchestration
│   ├── output/            # Export formatters
│   ├── pipeline/          # Translation pipeline
│   ├── tui/               # Terminal UI
│   └── validation/        # Translation validation
├── data/
│   ├── sources/           # Downloaded source texts (gitignored)
│   ├── output/            # Generated translations (gitignored)
│   ├── config/            # Style configuration
│   ├── memory/            # Translation memory
│   └── metadata/          # Glossary, pericopes, book context
├── scripts/               # Utility scripts
└── tests/                 # Test suite (98%+ coverage)
```

## Data Sources and Attribution

This project uses the following open-licensed source texts:

| Source | Description | License |
|--------|-------------|---------|
| [MorphGNT](https://github.com/morphgnt/sblgnt) | Greek NT (SBLGNT) with morphological tagging | CC-BY-SA 4.0 |
| [MorphHB](https://github.com/openscriptures/morphhb) | Hebrew OT (Westminster Leningrad Codex) with morphology | CC-BY 4.0 |
| [OpenBible](https://github.com/churchstudio-org/openbible) | Reference translations (KJV, Kougo, etc.) | MIT |

### Reference Translations

- **KJV (King James Version)** - Public domain
- **ASV (American Standard Version)** - Public domain
- **Kougo-yaku (口語訳)** - 1955 Japanese translation
- **Meiji-yaku (明治訳)** - 1887 Japanese translation
- **Taisho-yaku (大正訳)** - 1917 Japanese translation

## Translation Memory

The system maintains a translation memory (`data/memory/segments.json`) that stores previously translated segments for consistency. This file contains AI-generated translations and is included in the repository for development purposes.

> **Note**: All translations in this repository are machine-generated and should be treated as experimental output, not authoritative translations.

## Testing

```bash
# Run all tests with coverage
uv run pytest tests/ --cov=src --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_pipeline.py -v
```

The project maintains 98%+ test coverage.

## Job Management

Translation jobs are tracked in a SQLite database (`data/jobs/state.db`) for fault tolerance:

```bash
# List recent jobs
uv run python main.py jobs list

# Show database statistics
uv run python main.py jobs stats

# Clean completed jobs (keep latest 2)
uv run python main.py jobs clean --keep-latest 2

# Delete jobs older than 30 days
uv run python main.py jobs clean --older-than-days 30

# Delete a specific job
uv run python main.py jobs clean --job-id <job-id>
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

This software is provided for experimental and educational purposes only.

**Important notices:**

1. **Not Authoritative Scripture**: Translations produced by this software are AI-generated and have not been reviewed by qualified biblical scholars or endorsed by any religious organization.

2. **Use at Your Own Risk**: These translations may contain errors, inaccuracies, or theological interpretations that differ from established translations.

3. **For Study and Research**: This tool is intended for exploring machine translation capabilities and should not replace established Bible translations for worship, teaching, or personal devotion.

4. **API Costs**: Using this software incurs costs through the Anthropic API. Users are responsible for their own API usage and associated charges.

5. **No Warranty**: The software and its output are provided "as is" without warranty of any kind.

For serious biblical study, please consult established translations and qualified scholars.

## Contributing

Contributions are welcome! Please ensure:

1. All tests pass (`uv run pytest`)
2. Coverage remains at 98%+
3. Code follows existing patterns

## Acknowledgments

- [Anthropic](https://anthropic.com) for Claude AI
- [MorphGNT](https://github.com/morphgnt/sblgnt) project for Greek NT texts
- [OpenScriptures](https://github.com/openscriptures/morphhb) for Hebrew OT texts
- [OpenBible](https://github.com/churchstudio-org/openbible) for reference translations

## Verify 日常訳第1版 before migration

Run these read-only, standard-library scripts from the repository root with
Python 3.11+. Defaults resolve relative to the scripts, so another working
directory also works. Neither script edits the translations or site assets.

```sh
python3 cli/translate-bible/scripts/verify_output.py --report /tmp/nichijo-v1-verification.json
python3 cli/translate-bible/scripts/review_output.py --report /tmp/nichijo-v1-review.csv
python3 -m unittest discover -s cli/translate-bible/tests -p test_output_audit.py
```

Both scripts accept `--source /path/to/output` and `--baseline /path/to/JapKougo.csv`.
The default source is `cli/translate-bible/data/output/`; the baseline is
`web/japanbible-net/web/public/JapKougo.csv`.

- `verify_output.py` checks JSON syntax and duplicate keys, canonical paths,
  chapter metadata, verse keys, nonempty text, CSV-incompatible control characters,
  markup/code fences/replacement characters, and furigana base-text agreement.
  It compares every reference against the main site's 66-book, 1,189-chapter corpus,
  including baseline rows with empty text. Missing/extra references require
  versification review; matching references do **not** prove matching verse content.
  Empty/absent furigana uses the existing exporter's plain-text fallback.
  The JSON report contains all findings and SHA-256 hashes of the scanned files.
- `review_output.py` writes a CSV queue with the translation, corresponding Kougo
  text, and heuristic flags for source scripts, Latin text, commentary/placeholders,
  repetition, identical verses within a chapter, and extreme length differences.
  Repeated verses and length differences may be legitimate. This is a review aid,
  not a semantic or theological accuracy check. Length comparisons skip empty
  baseline text. It scans valid text records even when structural findings exist.

Exit codes for both scripts: `0` means no structural/reference findings, `1` means
findings need resolution, and `2` means an input/report could not be processed.
Heuristic flags alone do not cause a nonzero exit. The structural check is deliberately
strict about raw newlines even though the experimental exporter flattens them:
review them before deciding whether to normalize or correct the source.

The initial working-copy findings are recorded in
[reports/nichijo-v1-initial-audit.md](reports/nichijo-v1-initial-audit.md).
Run against a stable output directory (pause translation writes or use a snapshot)
when preparing a release; file hashes identify the data read, but the scan is not
an atomic snapshot of a live translation job.

The subsequent [correction review](reports/nichijo-v1-correction-review.md)
records 147 applied fixes, all Opus 5 review decisions, reported usage, validation,
and the remaining source-numbering alignment work. Exact original/corrected text
and hashes are preserved in its linked correction manifest.

### Reviewed numbering and original-language parallels

Run these offline commands from `cli/translate-bible`:

```sh
uv run python main.py audit-alignment
uv run python main.py build-originals
uv run pytest tests/test_alignment.py tests/test_versification.py --cov=src.output.alignment --cov=src.output.originals --cov=src.data.versification --cov-fail-under=100
```

`audit-alignment` applies the reviewed routes to a candidate report, leaving the
harness's source-numbered JSON intact. It rejects changes to the reviewed input
snapshot or Kougo text. Sentence splits must retain every character exactly once;
joins and duplicate selections require explicit, snapshot-bound decisions.
The report includes aligned changes, all 206 extra references, rejected variants,
conflicting candidates, and missing passages. Exit `1` means numbering work remains;
it is not permission to publish a partial translation. See the
[numbering review](reports/nichijo-v1-numbering-alignment.md).

`build-originals` writes 66 lazy-loaded book assets to the main site's
`web/public/originals`. The source map, reviewed word boundaries, language tags,
Psalm headings, and source omissions are checked independently of the Japanese
translation. Its manifest records source and asset hashes; `NOTICE.txt` records
attribution. The chapter and passage readers offer a saved original-language
toggle, with Hebrew/Aramaic rendered right-to-left and Koine Greek left-to-right.
Run the website's normal build after regenerating these assets.

### Importing verified passage repairs and exporting 日常訳第1版

The completed [repair round](reports/numbering-repairs/README.md) resolves the
128 missing passages, 249 duplicate choices and six ambiguous records. Its 379
repairs include Opus 5 subscription CLI proposals, local comparisons and exact
final-text hashes. Before-review inputs and rejected candidates remain in the
audit. Reproduce the offline import, audit and export from this directory:

```sh
uv run python main.py import-alignment-repairs --review reports/numbering-repairs/before-review.json --bundle reports/numbering-repairs/repair-bundle.json --out /tmp/nichijo-reviewed.json
uv run python main.py audit-alignment --review /tmp/nichijo-reviewed.json --out /tmp/nichijo-aligned.json
uv run python main.py export-aligned --audit /tmp/nichijo-aligned.json --out /tmp/nichijo-release
uv run python scripts/verify_aligned_release.py --audit /tmp/nichijo-aligned.json --release /tmp/nichijo-release
```

Use an empty export destination. Import rejects incomplete verification, changed
candidate text, mismatched source selections and changed input review hashes.
Audit checks the raw translation, reference and original-source snapshots. Export
requires zero unresolved queues and leaves raw translation files intact. The
verification script checks every exported reference and text against the audit,
all repair texts, JSON keys, asset hashes and invalid text characters. These
commands make no model calls. The release is plain Japanese text without furigana;
website publication is a separate integration step.