@llm-translate/cli 1.0.0-next.1

package/.dockerignore

@@ -0,0 +1,51 @@
+# Dependencies
+node_modules
+
+# Build output (will be created during build)
+dist
+
+# Git
+.git
+.github
+.gitignore
+
+# Documentation (not needed in container)
+docs
+*.md
+!README.md
+
+# Test and coverage
+coverage
+.nyc_output
+*.test.ts
+*.spec.ts
+__tests__
+
+# Environment files (secrets should be passed via env vars)
+.env
+.env.*
+!.env.example
+
+# IDE and editor
+.vscode
+.idea
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+
+# Cache
+.translate-cache
+.cache
+
+# Misc
+.eslintcache
+.prettierrc
+tsconfig.tsbuildinfo

package/.env.example

@@ -0,0 +1,33 @@
+# ==============================================================================
+# llm-translate Server Configuration
+# Copy this file to .env and fill in your values
+# ==============================================================================
+
+# ------------------------------------------------------------------------------
+# Server Configuration
+# ------------------------------------------------------------------------------
+
+# Server port (default: 3000)
+TRANSLATE_PORT=3000
+
+# API key for authenticating requests to the translation API
+# Generate a secure random key: openssl rand -base64 32
+TRANSLATE_API_KEY=your-api-key-here
+
+# ------------------------------------------------------------------------------
+# LLM Provider API Keys
+# At least one provider key is required for translation to work
+# ------------------------------------------------------------------------------
+
+# Anthropic Claude API key (recommended)
+# Get your key at: https://console.anthropic.com/
+ANTHROPIC_API_KEY=sk-ant-xxxxx
+
+# OpenAI API key
+# Get your key at: https://platform.openai.com/api-keys
+OPENAI_API_KEY=sk-xxxxx
+
+# Ollama server URL (for self-hosted models)
+# Default: http://localhost:11434
+# Use http://ollama:11434 when running with docker-compose
+OLLAMA_BASE_URL=http://localhost:11434

package/.github/workflows/docs-pages.yml

@@ -0,0 +1,57 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package (docs config depends on dist)
+        run: npm run build
+
+      - name: Build docs
+        run: npm run docs:build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+        with:
+          enablement: true
+        continue-on-error: true # skip failure if repo doesn't allow auto-enablement; enable Pages manually in settings
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: github-pages
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

package/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write       # to be able to publish a GitHub release
+      issues: write         # to be able to comment on released issues
+      pull-requests: write  # to be able to comment on released pull requests
+      id-token: write       # to enable use of OIDC for npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0    # fetch all history for proper commit analysis
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm clean-install
+
+      - name: Verify integrity
+        run: npm audit signatures
+
+      - name: Build
+        run: npm run build
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.translaterc.json

@@ -0,0 +1,44 @@
+{
+  "version": "1.0",
+  "project": {
+    "name": "Example Project",
+    "description": "Example project configuration for llm-translate",
+    "purpose": "Technical documentation translation"
+  },
+  "languages": {
+    "source": "en",
+    "targets": ["ko", "ja", "zh-CN"],
+    "styles": {
+      "ko": "기술 문서로서 경어체(존댓말, ~습니다/~됩니다 체)를 사용하세요",
+      "ja": "技術文書として敬語(です・ます調)を使用してください"
+    }
+  },
+  "provider": {
+    "default": "claude",
+    "model": "claude-sonnet-4-20250514",
+    "fallback": ["openai"]
+  },
+  "quality": {
+    "threshold": 85,
+    "maxIterations": 4,
+    "evaluationMethod": "llm"
+  },
+  "chunking": {
+    "maxTokens": 1024,
+    "overlapTokens": 150,
+    "preserveStructure": true
+  },
+  "glossary": {
+    "path": "./glossary.json",
+    "strict": false
+  },
+  "paths": {
+    "output": "./docs/{lang}",
+    "cache": "./.translate-cache"
+  },
+  "ignore": [
+    "**/node_modules/**",
+    "**/*.test.md",
+    "**/drafts/**"
+  ]
+}

package/CLAUDE.md

@@ -0,0 +1,243 @@
+# Project Guidelines for llm-translate
+
+This document provides essential guidelines for AI assistants working on the llm-translate project. All implementations MUST adhere to the specifications defined in `RFC.md`.
+
+## Project Overview
+
+**llm-translate** is a CLI-based document translation tool powered by Large Language Models. It ensures translation consistency through glossary enforcement, context-aware chunking, and iterative quality refinement.
+
+## Core Principles
+
+1. **RFC.md is the source of truth** - All implementations must follow the RFC specification
+2. **Glossary enforcement is mandatory** - Domain-specific terminology must be translated consistently
+3. **Quality-aware refinement** - Use iterative Self-Refine loop until quality threshold is met
+4. **Structure preservation** - AST-based processing must maintain document formatting integrity
+5. **Provider-agnostic design** - Support Claude, OpenAI, Ollama via plugin architecture
+
+## Technology Stack (MUST use)
+
+| Component | Technology |
+|-----------|------------|
+| Runtime | Node.js 24+ |
+| Language | TypeScript 5.x |
+| CLI Framework | Commander.js |
+| Markdown Parser | unified/remark |
+| HTML Parser | cheerio |
+| LLM SDK | Vercel AI SDK |
+| Testing | Vitest |
+| Build | tsup |
+| Module System | ESM only |
+
+## Project Structure
+
+```
+src/
+├── cli/           # CLI entry point and commands
+│   ├── commands/  # file, dir, init, glossary commands
+│   └── options.ts # Shared CLI options
+├── core/          # Translation engine components
+│   ├── engine.ts  # Main translation engine
+│   ├── agent.ts   # Self-refine translation agent
+│   ├── chunker.ts # Semantic document chunker
+│   └── evaluator.ts # Quality evaluation
+├── parsers/       # Format-specific parsers
+│   ├── markdown.ts
+│   ├── html.ts
+│   └── plaintext.ts
+├── providers/     # LLM provider adapters
+│   ├── interface.ts # Provider interface (LLMProvider)
+│   ├── registry.ts  # Provider registry with fallback
+│   ├── claude.ts
+│   ├── openai.ts
+│   └── ollama.ts
+├── services/      # Supporting services
+│   ├── glossary.ts # Glossary loading and resolution
+│   ├── cache.ts    # Translation cache
+│   └── config.ts   # Configuration loader
+├── types/         # Shared type definitions
+│   ├── index.ts
+│   ├── mqm.ts     # MQM quality evaluation types
+│   ├── analysis.ts # Pre-translation analysis types
+│   └── modes.ts   # Translation mode configurations
+├── utils/         # Utilities
+│   ├── tokens.ts  # Token counting
+│   └── logger.ts  # Logging
+└── errors.ts      # Error types and codes
+```
+
+## Key Interfaces
+
+### LLMProvider Interface
+
+All providers MUST implement this interface:
+
+```typescript
+interface LLMProvider {
+  readonly name: ProviderName;
+  chat(request: ChatRequest): Promise<ChatResponse>;
+  stream(request: ChatRequest): AsyncIterable<string>;
+  countTokens(text: string): number;
+  getModelInfo(model?: string): ModelInfo;
+}
+```
+
+### Translation Agent Flow
+
+The translation pipeline follows research-backed multi-step approach:
+- **MAPS** (Multi-Aspect Prompting and Selection) - TACL 2024
+- **TEaR** (Translate, Estimate, Refine) - NAACL 2025
+- **MQM** (Multidimensional Quality Metrics) - WMT Standard
+
+**Pipeline Steps:**
+
+1. **PREPARE** - Load glossary, build context
+2. **ANALYZE** (Optional, MAPS-style) - Pre-translation analysis
+   - Extract key terms and potential challenges
+   - Identify ambiguous phrases
+   - Skip in `fast` mode
+3. **TRANSLATE** - Generate translation with glossary + analysis context
+4. **EVALUATE** (MQM-based) - Structured error annotation
+   - Error types: accuracy/fluency/style
+   - Severity: minor(1), major(5), critical(25)
+   - Score = 100 - Σ(error_weights)
+5. **REFINE** - Apply MQM error fixes directly
+6. **REPEAT** - Loop until quality >= threshold OR max iterations
+
+**Translation Modes:**
+
+| Mode | Analysis | MQM | Iterations | Threshold |
+|------|----------|-----|------------|-----------|
+| `fast` | ❌ | ❌ | 1 | 0 |
+| `balanced` | ❌ | ✅ | 2 | 75 |
+| `quality` | ✅ | ✅ | 4 | 85 |
+
+### Glossary Resolution
+
+When resolving glossary terms for a target language:
+
+- `doNotTranslate: true` - Keep source term for ALL languages
+- `doNotTranslateFor: ["ko", "ja"]` - Keep source for SPECIFIC languages
+- Otherwise use `targets[targetLang]` or fallback to source
+
+## CLI Commands
+
+```
+llm-translate file <input> [output]  # Single file translation
+llm-translate dir <input> <output>   # Batch directory translation
+llm-translate init                   # Initialize configuration
+llm-translate glossary <subcommand>  # Manage glossary (list, validate, add, remove)
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | File not found |
+| 4 | Quality threshold not met |
+| 5 | Provider/API error |
+| 6 | Glossary validation failed |
+
+## Configuration
+
+Configuration is loaded from `.translaterc.json` with this priority:
+1. CLI arguments (highest)
+2. Environment variables
+3. Config file
+4. Defaults (lowest)
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Claude API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `OLLAMA_BASE_URL` | Ollama server URL |
+
+## Quality Evaluation (MQM-Based)
+
+**MQM Error Types:**
+```
+Accuracy: mistranslation, omission, addition, untranslated
+Fluency: grammar, spelling, register, inconsistency
+Style: awkward, unidiomatic
+```
+
+**MQM Severity Weights:**
+| Severity | Weight | Description |
+|----------|--------|-------------|
+| Minor | 1 | Noticeable but doesn't affect understanding |
+| Major | 5 | Affects understanding or usability |
+| Critical | 25 | Completely wrong or unusable |
+
+**Score Calculation:** `score = max(0, 100 - Σ(error_weights))`
+
+**Default Thresholds:**
+- Quality threshold: 85/100 (quality mode), 75/100 (balanced), 0 (fast)
+- Max iterations: 4 (quality), 2 (balanced), 1 (fast)
+
+## Critical Rules
+
+1. **NEVER translate content inside code blocks**
+2. **ALWAYS apply glossary terms exactly as specified**
+3. **PRESERVE all formatting** (markdown, HTML tags, links, tables)
+4. **Keep URLs, file paths, and technical identifiers unchanged**
+5. **Maintain header hierarchy in chunking**
+
+## Testing Requirements
+
+- Unit tests for: chunker, glossary, markdown parser, providers
+- Integration tests for full translation pipeline
+- Test coverage target: > 80%
+- Use Vitest with ESM configuration
+
+## Error Handling
+
+Use the `TranslationError` class with appropriate `ErrorCode`:
+
+```typescript
+throw new TranslationError(ErrorCode.GLOSSARY_NOT_FOUND, {
+  path: glossaryPath,
+});
+```
+
+## Implementation Phases
+
+### Phase 1 (MVP)
+- Single file translation with Claude
+- Basic glossary support
+- Markdown parser
+- stdin/stdout support
+
+### Phase 2
+- OpenAI and Ollama providers
+- Quality evaluator with LLM scoring
+- Full Self-Refine loop
+- HTML parser
+- Cache manager
+
+### Phase 3
+- Batch directory processing
+- Parallel file translation
+- Progress reporting
+- Integration tests
+
+## Development Commands
+
+```bash
+npm run build      # Build with tsup
+npm run dev        # Watch mode
+npm test           # Run Vitest
+npm run typecheck  # TypeScript check
+npm run lint       # ESLint
+```
+
+## Code Style
+
+- Use strict TypeScript (strict: true in tsconfig)
+- Prefer async/await over callbacks
+- Use Zod for runtime validation of config/glossary
+- Export types from `src/types/index.ts`
+- All public APIs must have JSDoc comments

package/Dockerfile

@@ -0,0 +1,55 @@
+# ==============================================================================
+# llm-translate Docker Image
+# Multi-stage build for optimized production image
+# ==============================================================================
+
+# ==============================================================================
+# Stage 1: Build
+# ==============================================================================
+FROM node:24-alpine AS builder
+
+WORKDIR /app
+
+# Install dependencies first (cache layer)
+COPY package*.json ./
+RUN npm ci
+
+# Copy source and build
+COPY tsconfig.json tsup.config.ts ./
+COPY src ./src
+RUN npm run build
+
+# Prune dev dependencies for smaller image
+RUN npm prune --production
+
+# ==============================================================================
+# Stage 2: Production
+# ==============================================================================
+FROM node:24-alpine AS production
+
+# Security: run as non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S llmtranslate -u 1001
+
+WORKDIR /app
+
+# Copy only production artifacts
+COPY --from=builder --chown=llmtranslate:nodejs /app/node_modules ./node_modules
+COPY --from=builder --chown=llmtranslate:nodejs /app/dist ./dist
+COPY --from=builder --chown=llmtranslate:nodejs /app/package.json ./
+
+# Environment
+ENV NODE_ENV=production
+ENV TRANSLATE_PORT=3000
+
+# Switch to non-root user
+USER llmtranslate
+
+EXPOSE 3000
+
+# Health check for container orchestration
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD node -e "fetch('http://localhost:3000/health/live').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"
+
+# Start server with JSON logging for container environments
+CMD ["node", "dist/cli/index.js", "serve", "--json"]