If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/HIllya51/LunaTranslator shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 5 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live HIllya51/LunaTranslator repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/HIllya51/LunaTranslator.

What it runs against: a local clone of HIllya51/LunaTranslator — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in HIllya51/LunaTranslator | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of HIllya51/LunaTranslator. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/HIllya51/LunaTranslator.git
#   cd LunaTranslator
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of HIllya51/LunaTranslator and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "HIllya51/LunaTranslator(\\.git)?\\b" \\
  && ok "origin remote is HIllya51/LunaTranslator" \\
  || miss "origin remote is not HIllya51/LunaTranslator (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f ".github/workflows/buildluna.yml" \\
  && ok ".github/workflows/buildluna.yml" \\
  || miss "missing critical file: .github/workflows/buildluna.yml"
test -f "docs/.vitepress/config/index.mts" \\
  && ok "docs/.vitepress/config/index.mts" \\
  || miss "missing critical file: docs/.vitepress/config/index.mts"
test -f ".gitmodules" \\
  && ok ".gitmodules" \\
  || miss "missing critical file: .gitmodules"
test -f ".github/workflows/buildlunahook.yml" \\
  && ok ".github/workflows/buildlunahook.yml" \\
  || miss "missing critical file: .github/workflows/buildlunahook.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/HIllya51/LunaTranslator"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

LunaTranslator is a real-time text extraction and translation system for visual novels, primarily targeting Windows. It uses API hooking to intercept game text at runtime, applies OCR for UI text, and pipes everything through configurable translation engines (including LLMs and offline models) with optional embedded in-game translation overlays. Hybrid monorepo: C++ core (src/ presumed) implements HOOK and text extraction engines; Python layer (likely src/py or similar) wraps translation APIs and OCR; .github/workflows/ orchestrates CI builds for release. Vitepress-based docs in docs/ with translations per language folder (zh/en/cht/ja/ko/ru/vi/).

Visual novel enthusiasts and international players who want to play Japanese/Chinese games in their native language; contributors familiar with low-level Windows API hooking (HOOK systems), OCR pipelines, and translation APIs.

Actively developed and production-ready: the codebase is substantial (4.1M lines C++, 2.4M Python), GitHub workflows are fully automated (build, release, docs), multi-language documentation exists (zh/en/ja/ko/ru/vi/cht), and the project maintains a Discord/QQ community. Verdict: mature, actively maintained.

Single maintainer (HIllya51) is a risk vector for sustainability. Heavy reliance on external translation/OCR APIs means service outages cascade. Windows-only architecture limits portability. Large C++ codebase (4.1M LOC) without visible test suite in the file list suggests potential regression risk on refactors.

Active CI/CD with separate workflows for Luna (main app), LunaHook (hooking engine), and documentation builds. Recent focus on multi-language docs and emulator HOOK support (NS/PSP/PSV/PS2). Issue templates suggest ongoing game compatibility requests and bug triage.

git clone https://github.com/HIllya51/LunaTranslator.git
cd LunaTranslator
# Install Python deps (inferred from .py files)
pip install -r requirements.txt  # (file not listed, check root)
# Build C++ components via CMake (CMake files present)
cmake . && make
# OR use provided build scripts in .github/workflows/

Daily commands: No explicit dev server startup visible in package.json (it's docs-only). Likely the compiled binary runs standalone. For docs: npm run docs:dev (Vitepress) starts a local docs site on http://localhost:5173.

• .github/workflows/build.yml — Primary CI/CD pipeline that builds and packages the LunaTranslator application for distribution—defines all automated compilation and release steps.
• .github/workflows/buildluna.yml — Core application build workflow that compiles the main Luna translator executable—essential for understanding the build process.
• docs/.vitepress/config/index.mts — Central documentation site configuration that aggregates multi-language support and navigation—the entry point for the entire docs infrastructure.
• .gitmodules — Defines git submodule dependencies (likely for lunahook and other translation backends)—critical for cloning and building the complete project.
• .github/workflows/buildlunahook.yml — Specialized build pipeline for the lunahook component used for text extraction from games—separate compilation for the hooking mechanism.
• docs/.vitepress/theme/index.ts — VitePress theme entry point providing custom styling and components (including downloads, Giscus comments)—controls the entire documentation UI layer.
• .github/ISSUE_TEMPLATE/config.yml — Standardized issue templates for game requests, bugs, and feature requests—enforces communication structure for contributors and users.

• Lunahook (Text Extraction) (C++ (x86/x64), Windows API, memory manipulation) — DLL injection into game process to intercept and capture text before it renders; primary data source for translation pipeline
  • Failure mode: If hook fails to attach or text detection

Add a new translation engine integration

1. Review existing translation engine implementations in docs to understand the expected interface (API key handling, rate limits, language codes) (docs/en/useapis/tsapi.md)
2. Implement the new engine following the pattern used by other engines, then add configuration documentation in the appropriate language folder (docs/zh/guochandamoxing.html)
3. Add the engine to the list of supported translators in the main README snippets and update all language variants (docs/en/README.md)

Add support for a new visual novel game (HOOK configuration)

1. Reference the HOOK settings documentation to understand text extraction configuration (docs/en/hooksettings.md)
2. Create a new game profile with HOOK configuration parameters (text pointers, encoding, etc.) (docs/en/embedtranslate.md)
3. File a game request issue using the structured template for community and maintainer review (.github/ISSUE_TEMPLATE/01_game_request.yaml)

Add documentation for a new language or feature

1. Create a new markdown file in the docs folder (e.g., docs/en/myfeature.md for English) (docs/en/README.md)
2. Register the new document in the VitePress config for all language variants (en, zh, ja, ko, vi, ru, cht) (docs/.vitepress/config/index.mts)
3. Update the theme styling if introducing new markdown containers or special formatting (docs/.vitepress/theme/style.css)

Improve OCR accuracy or add a new OCR engine

1. Study the OCR API documentation and existing engine implementations (docs/en/useapis/ocrapi.md)
2. Review OCR parameter tuning guide to understand quality vs. speed tradeoffs (docs/en/ocrparam.md)
3. Implement the new OCR engine following the existing module pattern and add configuration options to the UI (docs/en/gooduse/gooduseocr.md)

• VitePress — Static documentation site generator with excellent multi-language support, fast builds, and built-in SSG for GitHub Pages hosting
• GitHub Actions — Native CI/CD automation for multi-platform builds (Windows, Linux, macOS), automated releases, and documentation deployment without external services
• Git submodules — Manages separate compilation units (lunahook, translation backends) with independent versioning while keeping them integrated in a single repository
• Vue.js (via Vitepress components) — Reactive UI components for documentation (tabs, downloads, comments) without a full framework overhead
• Giscus (GitHub Discussions) — Decentralized comments system leveraging GitHub infrastructure, eliminating need for external comment servers

• Monorepo with git submodules rather than separate repositories

  • Why: Simplifies user experience (single clone) and automates coordinated releases across translator, hook, and UI
  • Consequence: Slightly more complex CI/CD logic and potential merge conflicts when coordinating submodule updates

• Multi-language documentation as separate markdown trees rather than i18n framework

  • Why: Simpler maintenance for translators (edit .md directly), no runtime dependency, clear separation per language
  • Consequence: Content updates must be manually propagated to all 8 language folders; higher maintenance burden but better community translation workflow

• Static VitePress docs instead of dynamic wiki or CMS

  • Why: Fast, versioned with code, no server required, can be published directly from CI/CD to GitHub Pages
  • Consequence: Less interactive (no user-contributed snippets embedded), requires markdown fluency from contributors

• HOOK + OCR + multiple translation APIs as pluggable backends

  • Why: Maximizes game compatibility and handles text extraction failures gracefully (fallback to OCR if hook fails)
  • Consequence: Complex configuration surface for users; requires coordination of multiple third-party API keys

• Real-time collaborative editing or live multiplayer translation
• Web-based translator (desktop application only, per README 'visual novel translator')
• Support for non-CJK languages as primary targets (optimized for Japanese → Chinese/English)
• Native Linux/macOS game emulation (PSP/PSV/PS2 emulator hooking Windows-centric)
• Voice-based text input (visual novels are text-heavy, TTS for output only per README)

Windows-only deployment: HOOK system is tightly coupled to Windows API (ReadProcessMemory, CreateRemoteThread, etc.), making cross-platform porting non-trivial. Submodules (.gitmodules) must be cloned recursively (git clone --recurse-submodules). External API dependencies: translation/OCR engines require network or local service setup (no obvious config file in listing). Large binary artifacts in CI/CD may require GitHub token for releases.

• API Hooking / Code Injection — Core mechanism of LunaTranslator; intercepting Windows API calls (ReadProcessMemory, etc.) to extract game text at runtime without modifying game binaries
• Process Memory Introspection — Underlying technique for HOOK system to read text buffers from game process memory and identify text encoding/pointers dynamically
• OCR (Optical Character Recognition) Pipelines — Fallback mechanism for text extraction when HOOK fails (e.g., UI text in screenshots); LunaTranslator integrates multiple OCR backends (online/offline)
• Translation API Abstraction Layer — Enables pluggable translation backends (Google, Deepl, LLMs, offline models); prevents vendor lock-in and allows users to switch engines seamlessly
• Morphological Analysis / Segmentation — Japanese language learning feature (分词, 假名注音) requires tokenization and furigana injection; integrated with Yomitan plugin ecosystem
• Multi-Language Documentation Generation — Vitepress-based localization (8 languages) with separate config files per locale; demonstrates i18n patterns for open-source projects

• mempler/Textractor — Direct predecessor/alternative for Windows HOOK-based game text extraction; similar architecture for comparison
• ppy/osu — Reference for large C++/Python hybrid project with multi-platform CI/CD and community translation workflows
• Akebi-GC/Akebi-GC — Similar game modding tool using process hooking; demonstrates alternative patterns for runtime game patching
• hiroi-sora/Umi-OCR — Complementary OCR tool for Chinese; shares translation pipeline philosophy and offline model approach
• BalloonUpdate/Balloon — Auto-update framework used in translation tools; relevant for LunaTranslator's release/versioning strategy

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add multilingual documentation structure validation in CI/CD

The repo maintains documentation in 8 languages (zh, en, cht, ja, ko, vi, ru) across docs/ with consistent structure (e.g., docs//README.md, docs//basicuse.md, docs/*/useapis/). However, there's no CI workflow to validate that new doc files are present across all language variants. This prevents inconsistencies where a feature doc is added in English but forgotten in other languages. Add a GitHub Action that validates translation parity across all language directories.

• [ ] Create .github/workflows/docs-i18n-validation.yml to check that all markdown files in docs/en/ have equivalents in docs/zh/, docs/cht/, docs/ja/, etc.
• [ ] Parse the VitePress config files (docs/.vitepress/config/*.ts) to extract expected sidebar structures and validate against actual files
• [ ] Fail the workflow if a file exists in one language but is missing in others (with allowlist for language-specific content)

Create E2E test suite for VitePress docs build across all language configs

The documentation uses VitePress with 8 language-specific config files (docs/.vitepress/config/*.ts) but there's no test coverage ensuring all configs build successfully. A broken config in one language config file could go undetected until release. Add tests that validate each language config builds without errors and checks for common issues like broken sidebar links.

• [ ] Create docs/tests/ directory with a test file that runs 'vitepress build' for each language config variant separately
• [ ] Validate that generated .vitepress/dist contains expected language directories and index files
• [ ] Add GitHub Action .github/workflows/docs-build-test.yml that runs before docbuild.yml to catch config regressions early

Add API documentation for hooks system with auto-generated reference from source

The repo heavily features HOOK functionality (docs/*/hooksettings.md exists in all languages) but there's no structured API reference documentation. The file structure suggests multiple hook-related workflows (.github/workflows/buildlunahook.yml) and hook configuration, but new contributors can't easily understand the hook interface. Create a documentation template and update docs to include code examples from the actual hook implementation.

• [ ] Audit the main source code to locate hook interface definitions and hook examples
• [ ] Create docs/en/hooks-api-reference.md with function signatures, parameters, return types, and code examples from actual hook implementations
• [ ] Replicate this structure to docs/zh/, docs/cht/, docs/ja/ etc. using consistent translation markers that tools like VitePress can handle
• [ ] Add links to hook API reference from existing hooksettings.md files in all language variants

• Add automated test suite for Python translation wrapper layer (docs reference .py files but no tests/ visible in file list); start with unit tests for offline translation fallback logic
• Expand documentation for non-Chinese regions: docs/en/ exists but feature parity with docs/zh/ is unclear; audit missing .md files and translate core guides (e.g., docs/cht/gooduse/ folder completeness)
• Create CMake install target and packaging documentation: CMakeLists.txt exists but no visible INSTALL() directives; add one-command build+install for Windows developers to lower onboarding friction

The LunaTranslator documentation site (VitePress-based) has a relatively low attack surface as it's primarily a static site. Main concerns are: (1) dependency management and keeping packages updated, (2) third-party component security (Giscus), (3) missing explicit security headers configuration, and (4) potential markdown injection risks if content sources are untrusted. The codebase appears to be primarily documentation/UI focused with no apparent hardcoded secrets, SQL injection, or critical misconfigurations visible in the provided file structure. Regular dependency audits and security header implementation would improve the security posture.

• Medium · Outdated VitePress Dependency — package.json - devDependencies.vitepress. VitePress version 1.6.4 is pinned without a caret (^) constraint in the lock file scenario. While the package.json shows ^1.6.4, potential security updates in the 1.x range may not be automatically applied. VitePress is a static site generator and any vulnerabilities could affect the documentation site build process and output. Fix: Regularly update VitePress to the latest version. Consider using npm audit and npm update regularly. Monitor GitHub security advisories for VitePress vulnerabilities.
• Medium · Giscus Vue Component Security — docs/.vitepress/theme/giscus.vue and package.json. @giscus/vue@2.4.0 is a third-party component that enables GitHub Discussions on the documentation site. While Giscus itself is generally trustworthy, embedding third-party comment systems introduces potential XSS risks if not properly configured, especially if user-generated content is rendered without sanitization. Fix: Verify that Giscus is configured with proper content security policies. Ensure iframe sandboxing is properly applied. Keep Giscus dependency updated and monitor for security advisories.
• Low · Missing Security Headers Configuration — docs/.vitepress/config/index.mts and related config files. The VitePress documentation site configuration files (config/*.ts) are present but no explicit security headers configuration (such as CSP, X-Frame-Options, X-Content-Type-Options) is visible in the provided file structure. Fix: Implement security headers in the VitePress config or deployment configuration. Add Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and other protective headers.
• Low · Markdown Content Injection Risk — docs and package.json - dependencies.markdown-it-container. The project uses markdown-it-container@4.0.0 for markdown processing. If documentation content is dynamically generated from untrusted sources or user input, there could be potential XSS risks through markdown parsing. Fix: Ensure all markdown content is from trusted sources only. If any user-generated markdown is processed, implement HTML sanitization. Keep markdown-it-container updated.
• Low · No Dependency Lock File Visible — Repository root. While package.json is provided, no package-lock.json or yarn.lock file is shown in the provided file structure. This could indicate missing lock file in version control, which could lead to inconsistent dependency versions across builds. Fix: Ensure package-lock.json (or yarn.lock/pnpm-lock.yaml) is committed to version control to lock exact dependency versions and ensure reproducible builds.
• Low · Workflow Files Lack Security Context — .github/workflows/. GitHub Actions workflow files (.github/workflows/*.yml) are present but not provided for analysis. Workflows could potentially contain secrets exposure, insecure permission configurations, or supply chain risks. Fix: Review workflow files for: 1) Secrets not logged, 2) Minimal necessary permissions set, 3) Pin actions to specific commits (avoid @main), 4) No untrusted script execution.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.