🦊 Mizuki Translate

Mizuki Translate is a local Translation web app that levarates LLMs to provide natural and good-sounding translation.

• Translate into 13 presets or enter any custom target language
• Choose between a thorough standard mode and a faster mode
• Verify names, idioms, and cultural references with web search in standard mode
• See response time and token usage after each translation
• Copy completed translations to the clipboard
• Run the React frontend and FastAPI backend locally with one command

React + Vite UI  ── POST /api/translate ──▶  FastAPI  ──▶  Claude
 localhost:5173                              127.0.0.1:8000

The frontend proxies /api requests to the FastAPI backend during development. The backend applies the translation prompt in backend/prompts/TranslatePrompt_v2.md and sends the request to claude-sonnet-5 through the Anthropic API.

Standard mode may take longer and consume more tokens. Both modes use the same translation prompt.

• uv and Python 3.12 or newer
• Node.js 20.19 or newer, with npm
• An Anthropic API key

Copy the example environment file at the repository root:

# Windows
Copy-Item .env.example .env

# macOS / Linux
cp .env.example .env

Then add your key to .env:

ANTHROPIC_API_KEY="sk-ant-..."

# Windows
.\launch.ps1

# macOS / Linux
chmod +x launch.sh
./launch.sh

The launcher installs the backend and frontend dependencies, starts the API at http://127.0.0.1:8000, and runs the Vite development server. Open the URL printed by Vite—normally http://localhost:5173.

Press Ctrl+C to stop the frontend and backend.

From the repository root, start the backend:

uv sync --project backend
uv run --project backend python backend/main.py

In a second terminal, start the frontend:

npm --prefix frontend install
npm --prefix frontend run dev

Useful frontend commands:

npm --prefix frontend run build   # Type-check and create a production build
npm --prefix frontend run lint    # Run Oxlint
npm --prefix frontend run preview # Preview the production build locally

MizukiTranslate/
├── backend/
│   ├── main.py          # FastAPI application and translation endpoint
│   ├── functions.py     # Anthropic request and error handling
│   ├── logger.py        # Loguru configuration
│   ├── prompts/         # Translation prompt templates
│   ├── pyproject.toml   # Python project and dependencies
│   └── uv.lock          # Locked Python dependencies
├── frontend/
│   ├── src/App.tsx      # Translation interface
│   ├── src/index.css    # Application styles
│   ├── vite.config.ts   # Vite config and API proxy
│   └── package.json     # Frontend scripts and dependencies
├── .env.example         # Environment variable template
├── launch.ps1           # Windows launcher
└── launch.sh            # macOS/Linux launcher

• uv or npm is not recognized: install the missing prerequisite, open a new terminal, and confirm it is on your PATH.
• ANTHROPIC_API_KEY is missing: make sure .env is in the repository root and contains a valid key.
• Port 8000 or 5173 is already in use: stop the process using that port, then run the launcher again.
• The UI opens but translation fails: check the backend terminal for the provider's error message and confirm that your Anthropic account has API access and available credits.

Licensed under the GNU General Public License v3.0.