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/OwO-Network/DeepLX 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.

GO — Healthy across all four use cases

• Last commit 7w ago
• 13 active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 72% of recent commits
• ⚠ No test directory detected

_{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 OwO-Network/DeepLX repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/OwO-Network/DeepLX.

What it runs against: a local clone of OwO-Network/DeepLX — 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 OwO-Network/DeepLX | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 80 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of OwO-Network/DeepLX. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/OwO-Network/DeepLX.git
#   cd DeepLX
#
# 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 OwO-Network/DeepLX and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 80 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~50d)"
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/OwO-Network/DeepLX"
  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).

DeepLX is a free, token-free API wrapper for DeepL's translation service written in Go. It provides a Gin-based HTTP server that forwards translation requests to DeepL without requiring an API key, bundling advanced features like language detection (whatlanggo), compression (brotli), and CORS support. Flat modular structure: main.go is the entry point, service/ contains config (service/config.go) and HTTP routing (service/service.go), translate/ isolates translation logic (translate/translate.go with types and utilities in translate/types.go and translate/utils.go). Infrastructure code includes Docker support (Dockerfile, compose.yaml) and cross-compilation scripting (.cross_compile.sh).

Developers and DevOps engineers who need a self-hosted translation API without DeepL token costs; Docker users deploying containerized microservices; integrators building multilingual applications who want to avoid vendor lock-in and API quotas.

Production-ready and actively maintained. The project has recent commits (last edit November 2024), established CI/CD pipelines (GitHub Actions for release, Docker, and CI workflows), and published Docker images on Docker Hub (missuo/deeplx). It includes systemd service files (deeplx.service) and installation scripts for production deployment.

Moderate risk: DeepL is a third-party service and could change their API or block requests; the codebase has a small maintainer surface area (single primary author). Dependency surface is relatively small (~6 direct deps) but includes indirect transport-layer dependencies (quic-go, refraction-networking/utls for advanced HTTP client features) that may introduce subtle vulnerabilities. No visible test files in the file list raises coverage concerns.

Active maintenance focused on reliability and deployment: CI/CD workflows are defined (release.yaml, docker.yaml), Docker images are continuously published, and cross-platform compilation is automated. No recent breaking changes evident, suggesting stability focus.

Clone and build with Go 1.25+: git clone https://github.com/OwO-Network/DeepLX.git && cd DeepLX && go mod download && go build -o deeplx main.go. Or use Docker: docker run -p 8080:8080 missuo/deeplx. Then POST JSON to http://localhost:8080/translate with {"text": "hello", "target_lang": "DE"}.

Daily commands: go run main.go starts the HTTP server (default :8080). For production: go build -o deeplx main.go && ./deeplx, or use the systemd service: systemctl start deeplx. Docker Compose available: docker-compose up via compose.yaml.

• main.go: Entry point that initializes the Gin server and wires together service and translate modules
• service/service.go: Contains HTTP endpoint handlers and CORS configuration for the API routes
• translate/translate.go: Core translation logic that crafts DeepL API requests and handles responses
• translate/types.go: Defines request/response structs for type safety across the translation pipeline
• service/config.go: Parses environment variables and CLI flags for server configuration (port, timeout, etc.)
• translate/utils.go: Utility functions for language detection and text preprocessing before sending to DeepL
• Dockerfile: Defines the containerized build and runtime for DeepLX, used in CI/CD and Docker Hub releases
• .github/workflows/release.yaml: Automates cross-platform binary builds and release creation on GitHub

Translation logic goes in translate/translate.go (handles the DeepL API call); add new request parameters to translate/types.go; HTTP route handling lives in service/service.go; configuration parsing in service/config.go. Language detection and text preprocessing happen in translate/utils.go. For deployment changes, edit Dockerfile or compose.yaml; for CI/CD, modify .github/workflows/.

DeepL's API structure and anti-bot headers are reverse-engineered; DeepL could change response format or block requests (mitigated by imroc/req/v3 with TLS fingerprinting via refraction-networking/utls). No explicit environment variable documentation in the file list—check service/config.go for required vars. Brotli compression requires compatible client support. Language detection via whatlanggo may have accuracy limits for edge cases; fallback behavior not obvious from file names alone.

• HTTP Client TLS Fingerprinting — DeepLX uses refraction-networking/utls to mimic browser TLS handshakes, avoiding anti-bot detection from DeepL; critical for understanding why the imroc/req/v3 client is used
• Language Detection via N-gram Classification — whatlanggo uses statistical language models to identify input language without explicit user hints; understand this to debug misdetection issues or add language-specific preprocessing
• Brotli Compression for HTTP Payloads — andybalholm/brotli enables efficient request/response compression in the HTTP layer; matters for bandwidth optimization and DeepL rate-limit avoidance
• CORS (Cross-Origin Resource Sharing) — gin-contrib/cors allows browser-based clients to call the API from different origins; essential for web frontend integration (e.g., DeepLXWeb)
• Reverse-Engineered API Endpoints — DeepLX bypasses official DeepL auth by mimicking internal API calls; understanding the request/response shape in translate/translate.go is critical for debugging when DeepL changes their API
• Stateless Microservice Pattern — DeepLX is horizontally scalable with no shared state; enables Docker multi-replica deployments and cloud-native orchestration (Kubernetes)
• JSON Query with tidwall/gjson — gjson efficiently parses DeepL's JSON responses without full unmarshaling; optimizes memory for high-throughput translation pipelines

• platonai/pla-assistant — Alternative translation microservice using similar reverse-engineering approach; reference implementation for token-free DeepL integrations
• openai-translator/openai-translator — Cross-platform translator using OpenAI API instead of DeepL; shows alternative backend abstraction patterns for multilingual apps
• OwO-Network/DeepLXWeb — Official web UI frontend for DeepLX API; demonstrates how to consume this service's endpoints in a production app
• gin-gonic/gin — Upstream HTTP framework powering DeepLX; understanding Gin middleware and routing directly improves contribution effectiveness
• deepseek-ai/DeepSeek-V3 — Shows how alternative translation/LLM backends abstract request/response handling; reference for adding backend flexibility to DeepLX

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 comprehensive unit tests for translate/translate.go

The translate package handles the core translation logic but has no visible test files. Given the complexity of handling multiple translation scenarios and edge cases (language detection, different translation types, error handling), adding unit tests for translate.go would improve code reliability and prevent regressions. This is critical for a free API wrapper that users depend on.

• [ ] Create translate/translate_test.go with tests for main translation functions
• [ ] Add tests for error handling scenarios (invalid language codes, network failures, empty input)
• [ ] Test language detection functionality from translate/utils.go
• [ ] Add benchmarks for translation performance
• [ ] Ensure tests mock external DeepL API calls to avoid flakiness

Add integration tests workflow in .github/workflows/

While ci.yaml, docker.yaml, and release.yaml exist, there's no dedicated integration test workflow. Currently, the repo lacks automated testing that validates the API endpoints work end-to-end. Adding a workflow that spins up the service and tests actual translation requests would catch breaking changes early.

• [ ] Create .github/workflows/integration-tests.yaml
• [ ] Use docker-compose.yaml to start the service in the workflow
• [ ] Add test cases against /translate endpoint with sample requests
• [ ] Test error scenarios (invalid input, unsupported languages)
• [ ] Run on pull requests and scheduled basis (e.g., daily) to catch upstream API changes

Add service configuration validation and tests in service/config.go

The service/config.go file exists but there's no visible validation logic or tests for configuration parsing. Given the multiple deployment options (Docker, systemd, macOS service via deeplx.service and me.missuo.deeplx.plist), validating config at startup would prevent misconfiguration issues. This is especially important for users deploying via install.sh and uninstall.sh scripts.

• [ ] Create service/config_test.go with tests for config loading and validation
• [ ] Add validation logic in service/config.go for required fields (port, API endpoint, etc.)
• [ ] Test edge cases: missing config file, invalid port numbers, malformed YAML/JSON
• [ ] Add tests that verify config works across different deployment methods (Docker, systemd, macOS)
• [ ] Document expected config format in README.md with examples

• Add unit tests for translate/utils.go language detection edge cases (short text, mixed languages, unknown scripts) since no test files appear in the repo.
• Document required environment variables and config flags by adding inline examples to service/config.go or creating a .env.example file.
• Extend translate/types.go with additional DeepL language codes or formality levels, then add integration tests in a new tests/ directory to verify they work end-to-end.

The DeepLX project demonstrates a reasonable security posture with a multi-stage Docker build and use of established Go frameworks. However, there are several areas requiring attention: (1) Docker image versioning should be pinned to avoid non-deterministic builds, (2) CORS and security headers configuration needs review and hardening, (3) HTTP client timeouts must be properly configured to prevent DoS, (4) Input validation in the translation module should be comprehensive, and (5) Rate limiting should be implemented to prevent API abuse. The application uses Go 1.25 and modern dependencies, but regular vulnerability scanning of transitive

• High · Use of Potentially Outdated Alpine Base Image — Dockerfile, line 8. The Dockerfile uses 'alpine:latest' without a pinned version. This can lead to unexpected behavior changes and potential security vulnerabilities if the base image is updated. Using 'latest' tag is not recommended for production deployments as it introduces non-deterministic builds. Fix: Pin the Alpine version to a specific stable release (e.g., 'alpine:3.20' or 'alpine:3.19') instead of 'latest' to ensure reproducible and secure builds.
• Medium · Missing Security Headers in Gin Framework Configuration — service/service.go (presumed). Based on the project structure using Gin framework (github.com/gin-gonic/gin v1.11.0), there is no visible configuration for security headers like Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, or Strict-Transport-Security in the provided code snippets. This could expose the API to XSS and clickjacking attacks. Fix: Implement middleware to add security headers. Use gin-contrib packages or custom middleware to set appropriate CORS and security headers before exposing the API.
• Medium · Permissive CORS Configuration Risk — service/service.go or service/config.go. The project includes 'github.com/gin-contrib/cors v1.7.6' dependency, which is commonly misconfigured. Without reviewing the actual configuration, permissive CORS settings could allow cross-origin requests from any domain, potentially enabling CSRF and data exfiltration attacks. Fix: Review and restrict CORS settings to only allow specific trusted origins. Avoid using wildcard '*' for AllowOrigins in production. Configure AllowMethods and AllowHeaders restrictively.
• Medium · Dependency on External HTTP Client Without Timeout Configuration — translate/translate.go (presumed). The project uses 'github.com/imroc/req/v3 v3.57.0' for HTTP requests to the DeepL API. If timeout configurations are not properly set, this could lead to hanging requests and potential DoS conditions. Fix: Ensure all HTTP requests using the req library have appropriate timeout configurations (e.g., 30-60 seconds) to prevent resource exhaustion from slow or unresponsive upstream services.
• Low · Go Version Compatibility Update Available — go.mod, line 1. The project specifies 'go 1.25.0' which appears to be a very recent version. While not necessarily a vulnerability, ensure that all dependencies are compatible with this version and that security patches for Go runtime are being tracked. Fix: Monitor Go security advisories at golang.org/security. Consider using go get -u to keep dependencies current and run 'go vulnerabilities' command regularly.
• Low · Missing Input Validation Visibility — translate/translate.go. The translate/translate.go module is responsible for handling user input for translation requests. Without reviewing the actual implementation, there is a risk of insufficient input validation that could lead to injection attacks or unexpected API behavior. Fix: Implement comprehensive input validation for all translation request parameters. Validate language codes, text length, and request format. Use allowlists for language codes rather than blocklists.
• Low · No Visible Rate Limiting Configuration — service/service.go (presumed). The API exposes a free translation service. Without rate limiting, the service is vulnerable to abuse and DoS attacks that could deplete resources or violate upstream DeepL API terms of service. Fix: Implement rate limiting middleware using tokens like github.com/juju/ratelimit or similar. Configure per-IP or per-request limits to prevent abuse.

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.