diff --git a/README.md b/README.md index aa4ba97..af79da4 100644 --- a/README.md +++ b/README.md @@ -206,7 +206,7 @@ Configure API clients to use the pre-deployed instance: ### [DeepLX App](https://github.com/xixu-me/DeepLX-App) (Open-source web app) -A modern, free web-based translation app powered by DeepLX API. Features include: +A modern, free web-based translation app powered by the DeepLX API. Features include: - Multi-language auto-detection support - Real-time translation as you type @@ -216,24 +216,31 @@ A modern, free web-based translation app powered by DeepLX API. Features include **Live Demo**: [https://deeplx.xi-xu.me](https://deeplx.xi-xu.me) -### [Pot](https://github.com/pot-app/pot-desktop/blob/master/README_EN.md) (Open-source cross-platform Windows, macOS and Linux app) +### [Pot](https://github.com/pot-app/pot-desktop/blob/master/README_EN.md) (Open-source cross-platform Windows, macOS, and Linux app) 1. [Download and install Pot for your platform](https://github.com/pot-app/pot-desktop/releases/latest) -2. Open Pot settings and navigate to service settings -3. Configure DeepL service type as DeepLX and set custom URL to: `https://dplx.xi-xu.me/translate` +2. Open Pot settings and navigate to Service Settings +3. Configure the DeepL service type as DeepLX and set the custom URL to `https://dplx.xi-xu.me/translate` + +### [Zotero](https://www.zotero.org/) (Open-source reference management app) + +1. [Download and install Zotero for your platform](https://www.zotero.org/download/) +2. Download and install the [Translate for Zotero](https://github.com/windingwind/zotero-pdf-translate) plugin +3. Open Zotero settings and navigate to the Services section under Translation +4. Configure the translation service as DeepLX (API) and set the endpoint to `https://dplx.xi-xu.me/translate` after clicking the config button ### [Immersive Translate](https://immersivetranslate.com/) (Closed-source browser extension) 1. [Install Immersive Translate](https://immersivetranslate.com/download/) 2. Go to developer settings and enable beta testing features -3. Go to translation services and add custom translation service DeepLX, set API URL to: `https://dplx.xi-xu.me/translate` -4. Set the maximum requests per second and the maximum text length per request to appropriate values (e.g., `80` and `5000`) to ensure stability and performance +3. Go to translation services and add a custom translation service DeepLX, configure the API URL to `https://dplx.xi-xu.me/translate` +4. Configure the maximum requests per second and maximum text length per request to appropriate values (e.g., `80` and `5000`) to ensure stability and performance ### [Bob](https://bobtranslate.com/) (Closed-source macOS app) -1. [Download and install Bob from Mac App Store](https://apps.apple.com/app/id1630034110) -2. Download and install [bob-plugin-deeplx](https://github.com/missuo/bob-plugin-deeplx) plugin -3. Configure plugin to use `https://dplx.xi-xu.me/translate` +1. [Download and install Bob from the Mac App Store](https://apps.apple.com/app/id1630034110) +2. Download and install the [bob-plugin-deeplx](https://github.com/missuo/bob-plugin-deeplx) plugin +3. Configure the plugin to use `https://dplx.xi-xu.me/translate` ## 🚀 Self-deployment diff --git a/README.zh.md b/README.zh.md index 45b6316..763829d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -220,14 +220,21 @@ except Exception as e: 1. [下载并安装适用于您平台的 Pot](https://github.com/pot-app/pot-desktop/releases/latest) 2. 打开 Pot 设置并导航到服务设置 -3. 将 DeepL 服务类型配置为 DeepLX，并将自定义 URL 设置为：`https://dplx.xi-xu.me/translate` +3. 将 DeepL 服务类型配置为 DeepLX，并将自定义 URL 配置为 `https://dplx.xi-xu.me/translate` + +### [Zotero](https://www.zotero.org/)（开源文献管理应用） + +1. [下载并安装适用于您平台的 Zotero](https://www.zotero.org/download/) +2. 下载并安装 [Translate for Zotero](https://github.com/windingwind/zotero-pdf-translate) 插件 +3. 打开 Zotero 设置并导航到翻译中的服务部分 +4. 将翻译服务配置为 DeepLX（API），并点击配置按钮后将接口配置为 `https://dplx.xi-xu.me/translate` ### [沉浸式翻译](https://immersivetranslate.com/zh-Hans/)（闭源浏览器扩展） 1. [安装沉浸式翻译](https://immersivetranslate.com/zh-Hans/download/) 2. 进入开发者设置并开启 beta 测试特性 -3. 进入翻译服务添加自定义翻译服务 DeepLX，将 API URL 设置为：`https://dplx.xi-xu.me/translate` -4. 将每秒最大请求数和每次请求最大文本长度设置为合适的值（例如 `80` 和 `5000`），以确保稳定性和性能 +3. 进入翻译服务添加自定义翻译服务 DeepLX，将 API URL 配置为 `https://dplx.xi-xu.me/translate` +4. 将每秒最大请求数和每次请求最大文本长度配置为合适的值（例如 `80` 和 `5000`），以确保稳定性和性能 ### [Bob](https://bobtranslate.com/)（闭源 macOS 应用） diff --git a/scripts/complete-setup.js b/scripts/complete-setup.js index dbbb642..c76f241 100644 --- a/scripts/complete-setup.js +++ b/scripts/complete-setup.js @@ -220,7 +220,6 @@ function showSummary() { log(" npm run test:watch # Run tests in watch mode", "cyan"); console.log("\n" + colorize("📚 Documentation:", "bright")); - log(" • tests/README.md # Comprehensive test docs", "cyan"); log(" • TESTING.md # Quick start guide", "cyan"); log(" • DEPLOYMENT_GUIDE.md # Deployment help", "cyan"); log(" • README_TEST_SUITE.md # Complete overview", "cyan"); @@ -229,7 +228,6 @@ function showSummary() { log(' 1. Run "npm test" to execute all tests', "magenta"); log(' 2. Check coverage with "npm run test:coverage"', "magenta"); log(' 3. Use "npm run test:watch" for development', "magenta"); - log(" 4. Review the documentation in tests/README.md", "magenta"); console.log( "\n" + diff --git a/tests/README.md b/tests/README.md deleted file mode 100644 index 41c479d..0000000 --- a/tests/README.md +++ /dev/null @@ -1,254 +0,0 @@ -# DeepLX Test Suite - -This directory contains comprehensive tests for DeepLX. The test suite is designed to ensure reliability, performance, and security of the translation service. - -## Test Structure - -``` -tests/ -├── lib/ # Unit tests for library modules -│ ├── query.test.ts # Core translation functionality -│ ├── cache.test.ts # Caching system tests -│ ├── rateLimit.test.ts # Rate limiting tests -│ ├── proxyManager.test.ts # Proxy management tests -│ ├── circuitBreaker.test.ts # Circuit breaker tests -│ ├── retryLogic.test.ts # Retry mechanism tests -│ ├── security.test.ts # Security middleware tests -│ ├── validation.test.ts # Input validation tests -│ ├── textUtils.test.ts # Text processing utilities -│ ├── types.test.ts # Type definitions and utilities -│ └── errorHandler.test.ts # Error handling tests -├── integration/ # Integration tests -│ └── translation.test.ts # End-to-end translation workflows -├── performance/ # Performance and load tests -│ └── load.test.ts # Load testing and benchmarks -├── utils/ # Test utilities and helpers -│ └── testHelpers.ts # Common test utilities -├── setup.ts # Jest setup configuration -└── README.md # This file -``` - -## Test Categories - -### Unit Tests (`tests/lib/`) - -Unit tests focus on individual modules and functions in isolation: - -- **Query Module**: Tests core translation functionality, request building, and API communication -- **Cache Module**: Tests translation caching, cache key generation, and cache invalidation -- **Rate Limiting**: Tests token bucket algorithm, IP-based limiting, and rate limit recovery -- **Proxy Management**: Tests proxy selection, and failover logic -- **Circuit Breaker**: Tests failure detection, circuit states, and recovery mechanisms -- **Retry Logic**: Tests exponential backoff, retry conditions, and failure handling -- **Security**: Tests input sanitization, CORS handling, and IP validation -- **Validation**: Tests request validation, parameter sanitization, and error reporting -- **Text Utils**: Tests text chunking, payload estimation, and length validation -- **Error Handling**: Tests error response formatting and error categorization - -### Integration Tests (`tests/integration/`) - -Integration tests verify complete workflows and component interactions: - -- **End-to-end Translation**: Complete translation workflows with caching and rate limiting -- **Proxy Failover**: Proxy selection and automatic failover scenarios -- **Security Integration**: Input validation and sanitization in real workflows -- **Performance Integration**: Response time and resource utilization under load - -### Performance Tests (`tests/performance/`) - -Performance tests ensure the service meets performance requirements: - -- **Response Time Benchmarks**: Measure translation response times -- **Memory Usage**: Monitor memory consumption and leak detection -- **Concurrent Requests**: Test handling of simultaneous requests -- **Load Testing**: Stress testing with high request volumes -- **Resource Utilization**: CPU and memory usage under various loads - -## Running Tests - -### All Tests - -```bash -npm test -``` - -### Test Categories - -```bash -# Unit tests only -npm run test:unit - -# Integration tests only -npm run test:integration - -# Performance tests only -npm run test:performance - -# With coverage report -npm run test:coverage - -# Continuous integration mode -npm run test:ci -``` - -### Development Mode - -```bash -# Watch mode for development -npm run test:watch - -# Verbose output for debugging -npm run test:verbose - -# Debug mode with detailed output -npm run test:debug -``` - -## Test Configuration - -### Jest Configuration (`jest.config.js`) - -The test suite uses Jest with the following key configurations: - -- **Environment**: Miniflare for Cloudflare Workers simulation -- **TypeScript**: ts-jest for TypeScript support -- **Coverage**: Comprehensive coverage reporting -- **Mocking**: Extensive mocking of external dependencies - -### Environment Setup (`tests/setup.ts`) - -Global test setup includes: - -- Mock environment creation -- Global utilities and matchers -- Console output management -- Request/Response mocking - -## Writing Tests - -### Test Structure - -Follow this structure for new tests: - -```typescript -describe('Module Name', () => { - let mockEnv: Env; - - beforeEach(() => { - mockEnv = createMockEnv(); - }); - - afterEach(() => { - jest.clearAllMocks(); - }); - - describe('function name', () => { - it('should handle normal case', () => { - // Test implementation - }); - - it('should handle error case', () => { - // Error test implementation - }); - }); -}); -``` - -### Best Practices - -1. **Isolation**: Each test should be independent and not rely on other tests -2. **Mocking**: Mock external dependencies and focus on the unit under test -3. **Coverage**: Aim for high code coverage but focus on meaningful tests -4. **Error Cases**: Test both success and failure scenarios -5. **Edge Cases**: Include boundary conditions and edge cases -6. **Performance**: Include performance assertions where relevant - -### Custom Matchers - -The test suite includes custom Jest matchers: - -```typescript -expect(response).toBeValidTranslationResponse(); -expect(response).toBeValidErrorResponse(); -``` - -### Test Utilities - -Use the provided test utilities for common operations: - -```typescript -import { - createMockTranslationResponse, - createMockErrorResponse, - createTestEnvironment, - expectValidTranslationResponse -} from './utils/testHelpers'; -``` - -## Continuous Integration - -The test suite runs automatically on: - -- **Push to main/develop branches** -- **Pull requests to main branch** -- **Multiple Node.js versions** (18.x, 20.x) - -### CI Pipeline - -1. **Lint**: TypeScript type checking -2. **Unit Tests**: All library module tests -3. **Integration Tests**: End-to-end workflow tests -4. **Performance Tests**: Load and performance benchmarks -5. **Coverage**: Code coverage reporting - -## Coverage Requirements - -The test suite aims for: - -- **Line Coverage**: > 90% -- **Function Coverage**: > 95% -- **Branch Coverage**: > 85% -- **Statement Coverage**: > 90% - -## Debugging Tests - -### Common Issues - -1. **Async/Await**: Ensure all async operations are properly awaited -2. **Mocking**: Verify mocks are properly reset between tests -3. **Timeouts**: Increase timeout for slow operations -4. **Memory**: Clear references to prevent memory leaks - -### Debug Commands - -```bash -# Run specific test file -npm test -- query.test.ts - -# Run with debug output -npm run test:debug - -# Run single test -npm test -- --testNamePattern="should handle successful translation" -``` - -## Contributing - -When adding new features: - -1. **Write tests first** (TDD approach recommended) -2. **Update existing tests** if behavior changes -3. **Add integration tests** for new workflows -4. **Include performance tests** for performance-critical features -5. **Update documentation** including this README - -## Monitoring and Alerts - -The test suite includes monitoring for: - -- **Test execution time trends** -- **Flaky test detection** -- **Coverage regression alerts** -- **Performance regression detection** - -For questions or issues with the test suite, please refer to the main repository documentation or create an issue in the repository.