यदि x + y = 10 और x - y = 2, तो x का मान क्या है?
", "question_type": "multiple_choice", "marks": 4, "time": 180, "options": [ { "id": 1, "name": "A", "value": "6
" }, { "id": 2, "name": "B", "value": "5
" }, { "id": 3, "name": "C", "value": "8
" }, { "id": 4, "name": "D", "value": "7
" } ], "solution": "समीकरणों को जोड़ने पर: 2x = 12, इसलिए x = 6
", "translated": true } ] } } ``` --- ### 3. Get Test Questions in Selected Language Fetch questions for a test in a specific language. **Endpoint:** `GET /api/v2/student/test/{id}/questions?language=hi` **Authentication:** Required (Bearer Token) ```bash curl -X GET "http://localhost:8000/api/v2/student/test/123/questions?language=hi" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_AUTH_TOKEN" ``` **Response:** ```json { "success": true, "data": { "test_id": 123, "language": "hi", "total_questions": 20, "questions": [ { "id": 456, "question_text": "यदि x + y = 10 और x - y = 2, तो x का मान क्या है?
", "question_type": "multiple_choice", "marks": 4, "time": 180, "options": [ { "id": 1, "name": "A", "value": "6
" }, { "id": 2, "name": "B", "value": "5
" } ], "solution": "समीकरणों को जोड़ने पर: 2x = 12, इसलिए x = 6
", "translated": true, "fallback": false } ] } } ``` --- ## Day 5: Batch Translation Endpoints ### 4. Start Batch Translation Initiate batch translation for an entire test series into multiple languages. **Endpoint:** `POST /api/v2/teacher/test-series/{id}/translate-batch` **Authentication:** Required (Teacher Bearer Token) ```bash curl -X POST "http://localhost:8000/api/v2/teacher/test-series/123/translate-batch" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" \ -d '{ "target_languages": ["hi", "mr", "ta"] }' ``` **Response:** ```json { "success": true, "message": "Batch translation job started successfully", "data": { "job_id": 456, "test_series_id": 123, "test_series_name": "Math Unit Test - Chapter 1", "total_questions": 50, "target_languages": ["hi", "mr", "ta"], "estimated_cost": "₹250.00", "estimated_time": "15 minutes", "status": "queued" } } ``` --- ### 5. Check Translation Job Progress Monitor the progress of a batch translation job. **Endpoint:** `GET /api/v2/teacher/translation-jobs/{id}` **Authentication:** Required (Teacher Bearer Token) ```bash curl -X GET "http://localhost:8000/api/v2/teacher/translation-jobs/456" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" ``` **Response (Processing):** ```json { "success": true, "data": { "job_id": 456, "test_series_id": 123, "test_series_name": "Math Unit Test - Chapter 1", "status": "processing", "formatted_status": "In Progress", "progress": { "total_questions": 150, "translated": 95, "failed": 2, "percentage": 63 }, "target_languages": ["hi", "mr", "ta"], "current_language": "mr", "started_at": "2025-01-15 10:00:00", "completed_at": null, "estimated_completion": "2025-01-15 10:15:00", "estimated_cost": "₹250.00", "actual_cost": null, "total_characters": 0 } } ``` **Response (Completed):** ```json { "success": true, "data": { "job_id": 456, "test_series_id": 123, "test_series_name": "Math Unit Test - Chapter 1", "status": "completed", "formatted_status": "Completed", "progress": { "total_questions": 150, "translated": 148, "failed": 2, "percentage": 99 }, "target_languages": ["hi", "mr", "ta"], "current_language": null, "started_at": "2025-01-15 10:00:00", "completed_at": "2025-01-15 10:14:32", "estimated_completion": "2025-01-15 10:15:00", "estimated_cost": "₹250.00", "actual_cost": "₹245.67", "total_characters": 123450 } } ``` --- ### 6. List All Translation Jobs Get a list of all translation jobs for the authenticated teacher. **Endpoint:** `GET /api/v2/teacher/translation-jobs?status=completed&per_page=10` **Authentication:** Required (Teacher Bearer Token) ```bash curl -X GET "http://localhost:8000/api/v2/teacher/translation-jobs?status=completed&per_page=10" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" ``` **Response:** ```json { "success": true, "data": [ { "job_id": 456, "test_series_id": 123, "test_series_name": "Math Unit Test - Chapter 1", "status": "completed", "formatted_status": "Completed", "progress_percentage": 99, "target_languages": ["hi", "mr", "ta"], "translated_count": 148, "failed_count": 2, "total_questions": 150, "estimated_cost": "₹250.00", "actual_cost": "₹245.67", "created_at": "2025-01-15 10:00:00", "completed_at": "2025-01-15 10:14:32" }, { "job_id": 455, "test_series_id": 122, "test_series_name": "Physics Unit Test", "status": "completed", "formatted_status": "Completed", "progress_percentage": 100, "target_languages": ["hi"], "translated_count": 30, "failed_count": 0, "total_questions": 30, "estimated_cost": "₹75.00", "actual_cost": "₹72.34", "created_at": "2025-01-14 15:30:00", "completed_at": "2025-01-14 15:35:45" } ], "pagination": { "total": 25, "per_page": 10, "current_page": 1, "last_page": 3 } } ``` --- ### 7. Cancel Translation Job Cancel an in-progress translation job. **Endpoint:** `DELETE /api/v2/teacher/translation-jobs/{id}` **Authentication:** Required (Teacher Bearer Token) ```bash curl -X DELETE "http://localhost:8000/api/v2/teacher/translation-jobs/456" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" ``` **Response:** ```json { "success": true, "message": "Translation job cancelled successfully", "data": { "job_id": 456, "status": "cancelled" } } ``` --- ## Day 6: Translation Dashboard Endpoints ### 8. Get Translation Dashboard Get comprehensive translation coverage dashboard for the teacher. **Endpoint:** `GET /api/v2/teacher/translations/dashboard` **Authentication:** Required (Teacher Bearer Token) ```bash curl -X GET "http://localhost:8000/api/v2/teacher/translations/dashboard" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" ``` **Response:** ```json { "success": true, "data": { "summary": { "total_questions": 500, "fully_translated": 350, "partially_translated": 100, "untranslated": 50, "total_cost_spent": "₹1,250.00" }, "by_language": [ { "code": "hi", "name": "Hindi", "translated": 450, "percentage": 90 }, { "code": "mr", "name": "Marathi", "translated": 380, "percentage": 76 }, { "code": "ta", "name": "Tamil", "translated": 200, "percentage": 40 } ], "by_test_series": [ { "test_id": 123, "test_name": "Math Unit 1", "questions": 50, "languages_available": ["en", "hi", "mr"], "completion_percentage": 93 }, { "test_id": 124, "test_name": "Physics Unit 2", "questions": 30, "languages_available": ["en", "hi"], "completion_percentage": 100 } ], "recent_jobs": [ { "job_id": 456, "test_name": "Math Unit 1", "status": "Completed", "languages": ["hi", "mr"], "progress": 100, "completed_at": "2025-01-15 10:30:00" } ] } } ``` --- ### 9. Get Missing Translations Report Get a list of questions that don't have translations in a specific language. **Endpoint:** `GET /api/v2/teacher/translations/missing?language=hi` **Authentication:** Required (Teacher Bearer Token) ```bash curl -X GET "http://localhost:8000/api/v2/teacher/translations/missing?language=hi" \ -H "Accept: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" ``` **Response:** ```json { "success": true, "data": { "language": "hi", "missing_translations": [ { "question_id": 789, "test_series_id": 125, "test_series_name": "Chemistry Unit 3", "question_preview": "What is the chemical formula for water? The molecular structure consists of...", "question_type": "multiple_choice" }, { "question_id": 790, "test_series_id": 125, "test_series_name": "Chemistry Unit 3", "question_preview": "Calculate the molar mass of H2SO4. Given: H = 1, S = 32, O = 16...", "question_type": "multiple_choice" } ], "total_missing": 50, "total_questions": 500, "coverage_percentage": 90 } } ``` --- ### 10. Bulk Delete Translations Delete all translations for a specific language in a test series (useful for re-translation). **Endpoint:** `DELETE /api/v2/teacher/translations/bulk-delete` **Authentication:** Required (Teacher Bearer Token) ```bash curl -X DELETE "http://localhost:8000/api/v2/teacher/translations/bulk-delete" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" \ -d '{ "test_series_id": 123, "language": "hi" }' ``` **Response:** ```json { "success": true, "message": "Translations deleted successfully", "data": { "test_series_id": 123, "language": "hi", "deleted_count": 50 } } ``` --- ### 11. Translation Quality Check Check translations for issues like broken HTML, missing LaTeX, or empty fields. **Endpoint:** `POST /api/v2/teacher/translations/quality-check` **Authentication:** Required (Teacher Bearer Token) **Check specific test series:** ```bash curl -X POST "http://localhost:8000/api/v2/teacher/translations/quality-check" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" \ -d '{ "test_series_id": 123, "language": "hi" }' ``` **Check all translations:** ```bash curl -X POST "http://localhost:8000/api/v2/teacher/translations/quality-check" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TEACHER_TOKEN" \ -d '{}' ``` **Response:** ```json { "success": true, "data": { "total_checked": 150, "issues_found": 5, "quality_score": 96.67, "problematic_translations": [ { "question_id": 456, "language": "hi", "issues": [ "Broken HTML tags in question_text", "Possible missing LaTeX formulas in solution" ], "question_preview": "यदि x + y = 10 और x - y = 2, तो x का मान क्या है?..." }, { "question_id": 457, "language": "mr", "issues": [ "Incomplete option translations" ], "question_preview": "What is the value of x if 2x + 3 = 11?..." } ] } } ``` --- ## Error Responses ### Authentication Error ```json { "success": false, "message": "User not authenticated" } ``` **HTTP Status:** 401 ### Validation Error ```json { "success": false, "message": "Validation failed", "errors": { "language": [ "The language field is required." ] } } ``` **HTTP Status:** 422 ### Permission Denied ```json { "success": false, "message": "You do not have permission to translate this test series" } ``` **HTTP Status:** 403 ### Language Not Supported ```json { "success": false, "message": "Selected language is not available for this test", "available_languages": ["en", "hi", "mr"] } ``` **HTTP Status:** 400 ### Server Error ```json { "success": false, "message": "Failed to start batch translation", "error": "Detailed error message here" } ``` **HTTP Status:** 500 --- ## Complete Workflow Examples ### Workflow 1: Student Taking Test in Hindi ```bash # Step 1: Check available languages curl -X GET "http://localhost:8000/api/v2/test/123/languages" \ -H "Accept: application/json" # Step 2: Start test in Hindi curl -X POST "http://localhost:8000/api/v2/student/test/123/start" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer STUDENT_TOKEN" \ -d '{"language": "hi"}' # Step 3: Get questions (if needed separately) curl -X GET "http://localhost:8000/api/v2/student/test/123/questions?language=hi" \ -H "Accept: application/json" \ -H "Authorization: Bearer STUDENT_TOKEN" # Step 4: Submit answers (existing endpoint - language independent) # ... ``` ### Workflow 2: Teacher Translating Test Series ```bash # Step 1: Start batch translation curl -X POST "http://localhost:8000/api/v2/teacher/test-series/123/translate-batch" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer TEACHER_TOKEN" \ -d '{"target_languages": ["hi", "mr", "ta"]}' # Returns job_id: 456 # Step 2: Monitor progress (poll every 10 seconds) curl -X GET "http://localhost:8000/api/v2/teacher/translation-jobs/456" \ -H "Accept: application/json" \ -H "Authorization: Bearer TEACHER_TOKEN" # Step 3: Check translation quality after completion curl -X POST "http://localhost:8000/api/v2/teacher/translations/quality-check" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer TEACHER_TOKEN" \ -d '{"test_series_id": 123}' # Step 4: View dashboard curl -X GET "http://localhost:8000/api/v2/teacher/translations/dashboard" \ -H "Accept: application/json" \ -H "Authorization: Bearer TEACHER_TOKEN" ``` ### Workflow 3: Re-translating with Better Quality ```bash # Step 1: Delete existing translations curl -X DELETE "http://localhost:8000/api/v2/teacher/translations/bulk-delete" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer TEACHER_TOKEN" \ -d '{"test_series_id": 123, "language": "hi"}' # Step 2: Re-translate curl -X POST "http://localhost:8000/api/v2/teacher/test-series/123/translate-batch" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer TEACHER_TOKEN" \ -d '{"target_languages": ["hi"]}' ``` --- ## Notes 1. **Authentication**: All authenticated endpoints require a valid Bearer token in the Authorization header. 2. **Rate Limiting**: Translation API calls are rate-limited to prevent API quota exhaustion. 3. **Caching**: Dashboard data is cached for 1 hour to improve performance. 4. **Background Jobs**: Batch translations run in the background queue. Monitor progress using the job ID. 5. **Cost Calculation**: Costs are estimated based on character count at ~₹5 per 10,000 characters. 6. **LaTeX Preservation**: All CKEditor HTML content with LaTeX formulas is preserved during translation. 7. **Fallback**: If translation is missing, the system automatically falls back to English. --- ## Support For issues or questions, contact the development team or refer to the main API documentation. **Version:** 1.0 **Last Updated:** January 2025