# Translate one questionnaire field

Machine-translate one piece of questionnaire text into a target language.

`POST /supplier-assessment-templates/translate`

Scope `supplier_template:write` | Plan **Growth+**

Machine-translate one piece of questionnaire text into a target language. The call is stateless: it reads and saves nothing, and returns the text for the caller to write into a field with an edit operation. `sources` holds the text in the languages the caller has (`en`, `ru`, `he`, at most 2000 characters each, HTML is rejected) and `target` is the language wanted; a source in the target language is ignored. If no source in another language has text, the answer is 422 NOTHING_TO_TRANSLATE. The translation is produced by an AI provider: 503 AI_UNAVAILABLE when none is configured and 502 AI_FAILED when the provider fails or returns nothing (retry later). Count it as a field edit: 120 per token and hour. Requires the supplier_template:write scope (or a signed-in Owner, Manager or Contributor session).

## Request body

- `sources`: object The text to translate from, per language; at least one language other than `target` must have text.
  - `en`: optional string maxLength 2000
  - `ru`: optional string maxLength 2000
  - `he`: optional string maxLength 2000
  - No other fields.
- `target`: string
  - `en`
  - `ru`
  - `he`
- No other fields.

## Returns

The `data` field of the standard `{ data, error, meta }` envelope:

- `text`: string The translation. Nothing is saved.

## Errors

| Status | Code | Retry | Meaning |
|---|---|---|---|
| 400 | `VALIDATION_FAILED` | no | The JSON body does not match the request schema, or the revision is missing where required. code VALIDATION_FAILED. |
| 401 | `INVALID_TOKEN` | no | Missing (UNAUTHORIZED) or invalid, expired or revoked (INVALID_TOKEN) token. |
| 402 | `FEATURE_GATED` | no | The tenant plan does not include supply chain security. code FEATURE_GATED; args.feature, args.minTier, args.minTierName. |
| 403 | `INSUFFICIENT_SCOPE` | no | The token lacks supplier_template:write (INSUFFICIENT_SCOPE), has no accountable person (FORBIDDEN: this principal cannot edit questionnaires), or the target is the built-in questionnaire (BUILTIN_IMMUTABLE). |
| 413 | `PAYLOAD_TOO_LARGE` | no | The JSON body exceeds the size limit. code PAYLOAD_TOO_LARGE. |
| 422 | `NOTHING_TO_TRANSLATE` | no | No source text in a language other than the target. code NOTHING_TO_TRANSLATE. |
| 429 | `RATE_LIMITED` | yes | Too many failed authentication attempts from this address, or the token used its hourly write budget (30 structural, 120 field edits). code RATE_LIMITED; wait Retry-After seconds, also in error.args.retryAfterSeconds. |
| 500 | `DB_ERROR` | no | Unexpected server error. code DB_ERROR; quote error.id to support. |
| 502 | `AI_FAILED` | no | The AI provider failed or returned nothing. code AI_FAILED; retry later. |
| 503 | `AI_UNAVAILABLE` | yes | Billing is temporarily unavailable (BILLING_UNAVAILABLE), or no translation provider is configured (AI_UNAVAILABLE). Retry later. |

## Example

### curl

```bash
curl -X POST "https://api.autociso.io/api/v1/supplier-assessment-templates/translate" \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"sources":{"en":"Do you encrypt data at rest?"},"target":"ru"}'
```

### Python

```python
import requests

response = requests.post(
    "https://api.autociso.io/api/v1/supplier-assessment-templates/translate",
    headers={"Authorization": "Bearer <your-api-token>", "Content-Type": "application/json"},
    json={
        "sources": {
            "en": "Do you encrypt data at rest?",
        },
        "target": "ru",
    },
)
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.autociso.io/api/v1/supplier-assessment-templates/translate", {
  method: "POST",
  headers: { "Authorization": "Bearer <your-api-token>", "Content-Type": "application/json" },
  body: JSON.stringify({
    "sources": {
      "en": "Do you encrypt data at rest?"
    },
    "target": "ru"
  }),
});
console.log(await response.json());
```

## Response (200)

```json
{
  "data": {
    "text": "Шифруются ли данные в состоянии покоя?"
  }
}
```