深度翻译工作室

Prerequisites

• Node.js ≥ 18.18 (includes npm)
• Yarn 1.22.22 (optional; use corepack when you want the repository lockfile)
• Docker & Docker Compose (For services and deployment)
• Git

If dependencies are not installed yet, use either npm install or Yarn v1 above.

First-time setup: starts isolated dependencies, migrates only deeptrans_local,

require the Worker in another terminal

npm run worker

Required object storage settings for production:

Required when upgrading from a version that predates import receipts and

Installation

```bash

Option A: enable Corepack and install from the repository Yarn v1 lockfile

corepack enable corepack prepare yarn@1.22.22 --activate yarn install

Read-only readiness verification after setup

npm run local:check

Production Deployment

```bash

DEPLOY_ENV_FILE=.env until the complete production file has been copied and checked.

docker compose -p deeptrans-studio --env-file "$DEPLOY_ENV_FILE" -f docker-compose-prod.yml \ build db migrate app app_worker

Retain the audit output with the deployment record. Unresolved legacy jobs

🚀 Quick Start

Start the web app; demo sign-in uses test@example.com and the fixed

and creates the demo account

npm run local:setup

Option B instead of Option A: npm also supports the guarded local-development scripts

npm install ```

Generate a local-only AUTH_SECRET in every supported shell, then paste it into .env.local.

This command only prints a random value; it never reads or writes .env.local.

npm run local:secret

Optional: start the guarded Web app and Worker together in one terminal

npm run dev:all ```

For a first install, run local:setup before local:check: setup starts the owned dependencies itself, applies migrations, creates the demo account, and creates the owned local storage bucket. local:check is read-only and verifies that PostgreSQL, Valkey, and both MinIO ports belong to the deeptrans-local Compose project and map to the exact loopback ports, then checks local credentials, storage-bucket readiness, and migration status. Use local:up only to start already-initialized dependencies or while diagnosing startup; it never replaces setup. The guarded app and worker receive only the validated local profile, so shell variables or a production-style .env cannot re-enable remote services. SMTP, COS, and remote AI are disabled by default. The translation-memory vector contract is fixed at 2048 dimensions. Translation-memory imports, vector backfills, and other queued workflows require npm run worker; when it is unavailable, queued work remains durable and resumes after the Worker becomes ready. To use remote AI deliberately, set LOCAL_ALLOW_REMOTE_AI=yes and provide development-only credentials in .env.local.

The fixed test@example.com / 123456 demo credential is active only when IS_DEMO=yes; a normal runtime follows the regular mailbox-verification path and never creates or accepts that demo account.

npm run dev also refuses to start when port 3000 is already occupied on either loopback family. Do not rely on Next.js choosing 3001: the local profile deliberately keeps authentication and internal API URLs fixed at port 3000.

After the Web process starts, GET http://localhost:3000/api/health returns { "status": "ok", "scope": "web" } only when that process can serve a route. It deliberately does not claim that PostgreSQL, storage, Valkey, or the Worker is ready; use npm run local:check and the relevant workflow status for those checks.

Additional UIs:

• Studio: http://localhost:3000
• MinIO Console: http://127.0.0.1:59003
• Database readiness: Run npm run local:check. Direct Prisma CLI commands are intentionally not part of the safe local-start path.

Configure environment

cp .env.example .env.production

Edit .env.production with production values

#

Use one explicit Compose project and environment file. The same file is passed

When upgrading a host that only has the legacy .env, explicitly keep

Services will be available on configured domain with SSL via Traefik.

```

memory-import-upgrade-audit.ts refuses all database/Redis connections unless --live is supplied in this stopped deployment window. With --live, it is read-only by default and exits non-zero while legacy jobs still need gates. It cannot reconstruct jobs that Redis has already pruned, so --apply additionally requires a credential-free snapshot reference and its SHA-256; both are printed in the audit record and must be retained with the deployment. The generated gates do not declare old work successful; the current memory owner must review and release each one. An old job remains write-blocked if it is processed by the upgraded worker even if an administrator manually retries it. The barrier cannot retroactively control an old image or external queue consumer, so verify every old worker is stopped before the migration window.

Production service set:

• db: PostgreSQL 18 with pgvector and PGroonga
• valkey: Redis-protocol cache and BullMQ runtime
• migrate: one-shot Prisma migration gate, required before app startup
• app: DeepTrans Studio web application
• app_worker: background worker
• traefik: HTTPS reverse proxy
• Tencent COS: external object storage configured through environment variables

because the validated local auth and API URLs intentionally stay on 3000.

npm run dev

pruned history; provide its credential-free reference and SHA-256 below.

🔄 Workflow Automation

• Queue-Based Processing: BullMQ-driven asynchronous task processing
• Batch Operations: Bulk translation, evaluation, and quality checks
• Document Parsing: DOCX, PDF, TXT, and Markdown parsing with MinerU online PDF parsing
• Status Tracking: Complete translation lifecycle management

Core Components

Translation-memory imports, vector backfills, and other queued workflows

Development Workflow

1. Fork & Clone: Fork the repository and clone your fork 2. Create Branch: Create a feature branch from main 3. Code Changes: Make your changes following our coding standards 4. Quality Checks: Run linting and type checking

    yarn lint
    yarn type-check
    

    feat: add translation memory import
    fix: resolve authentication bug
    docs: update installation guide