{
  "openapi": "3.1.0",
  "info": {
    "title": "PDF Language Translator API",
    "version": "1.0.0",
    "description": "Official REST API for PDF Language Translator (https://www.pdflanguagetranslators.com). Translate text and documents with layout awareness, tone selection, and 120+ language support.",
    "contact": {
      "name": "PDF Language Translator Support",
      "url": "https://www.pdflanguagetranslators.com/contact",
      "email": "support@pdflanguagetranslators.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://www.pdflanguagetranslators.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://www.pdflanguagetranslators.com",
      "description": "Production Server"
    },
    {
      "url": "http://127.0.0.1:3000",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/translate": {
      "post": {
        "summary": "Translate document or text content with layout awareness",
        "description": "Submits text or document extracts for translation using Google Gemini 3.5 Flash intelligence layer with support for 120+ languages and tone selection.",
        "operationId": "translateDocumentText",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranslationRequest"
              },
              "examples": {
                "hindiTranslation": {
                  "summary": "Translate English text to formal Hindi",
                  "value": {
                    "text": "The annual audit report confirms 100 percent compliance with privacy guidelines.",
                    "targetLanguage": "Hindi",
                    "sourceLanguage": "English",
                    "tone": "formal"
                  }
                },
                "spanishTranslation": {
                  "summary": "Translate English text to Spanish",
                  "value": {
                    "text": "Welcome to PDF Language Translator.",
                    "targetLanguage": "Spanish",
                    "tone": "simple"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful translation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing or invalid text or targetLanguage parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Server busy or rate limited - retry after indicated seconds",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Wait time in seconds before retrying"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server processing pause",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TranslationRequest": {
        "type": "object",
        "required": ["text", "targetLanguage"],
        "properties": {
          "text": {
            "type": "string",
            "description": "The text or markdown document extract to be translated."
          },
          "targetLanguage": {
            "type": "string",
            "description": "Target language name or standard ISO code (e.g. 'Hindi', 'hi', 'Bengali', 'es')."
          },
          "sourceLanguage": {
            "type": "string",
            "default": "auto",
            "description": "Source language name or ISO code. Defaults to 'auto' for automatic detection."
          },
          "tone": {
            "type": "string",
            "enum": ["simple", "formal", "academic", "casual"],
            "default": "simple",
            "description": "Tone and phrasing register for translation."
          },
          "targetLanguageNative": {
            "type": "string",
            "description": "Optional native script name for the target language (e.g. 'हिन्दी')."
          },
          "apiKey": {
            "type": "string",
            "description": "Optional custom Google Gemini API key for private dedicated quota."
          }
        }
      },
      "TranslationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "originalText": {
            "type": "string"
          },
          "translatedText": {
            "type": "string"
          },
          "targetLanguage": {
            "type": "string"
          }
        }
      },
      "RateLimitResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "isBusy": {
            "type": "boolean",
            "example": true
          },
          "retryAfter": {
            "type": "integer",
            "example": 5
          },
          "message": {
            "type": "string",
            "example": "The translation server is briefly busy. Pausing for a few seconds before retrying..."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "success": {
            "type": "boolean",
            "example": false
          }
        }
      }
    }
  }
}