Endpoint
POST/api/translate
Translate text with explicit validation and source-language reporting.
The translation route accepts JSON input, validates language codes, calls Google's public translate endpoint, and returns translated text with the detected or supplied source language.
Send JSON with text, target language code, and an optional source language code. If source is omitted, the route uses automatic detection.
Input type
JSON body
Target validation
2-12 chars
Auto detection
Enabled by default
Request payload
#- text is required and trimmed before dispatch.
- to is required and must match a simple lowercase language-code pattern.
- from is optional; when absent, the route uses auto detection upstream.
- Invalid JSON returns a 400 response before any translation work starts.
POST body
Success payload
#200 response
Common failure modes
#| Code | Cause | Suggested handling |
|---|---|---|
| INVALID_TEXT | The text field is missing or blank. | Block submission and prompt the user for content. |
| INVALID_LANGUAGE | Source or target language code is missing or malformed. | Fix the payload before retrying. |
| UPSTREAM_TIMEOUT | Translation provider exceeded the timeout window. | Retry with backoff if the user flow permits. |
| UPSTREAM_BAD_RESPONSE | Provider returned a non-200 response. | Degrade gracefully or queue for retry. |
| UNPARSEABLE_RESPONSE | Provider JSON could not be parsed into translated text. | Alert and fall back to the original text. |
Usage notes
#- Preserve the original text in your own data model so editors can compare source and translated copy later.
- Cache your own successful translations when reuse is acceptable; the route itself intentionally does not cache responses.
- Prefer explicit source language codes in batch workflows where you already know the input language.
- Use sourceLanguage from the response to flag unexpected detection outcomes in moderation or support tools.