---
title: "Translate a batch of strings"
method: POST
path: "/v1/translate/batch"
tags: ["Translation"]
---

# Translate a batch of strings

`POST /v1/translate/batch`

## Request

- Base URL: `https://hc.itsbaba.com`
- URL: `https://hc.itsbaba.com/v1/translate/batch`
- Auth: HTTP bearer

Translate up to 50 strings to one target language in a single call, for example the interface strings of a screen or the fields of a product. Results come back in input order. Every option of /v1/translate applies to all items.

With protection (any protection field, or account terms for Hebrew, English and Russian pairs), each item carries its own `protection` block and interface variables such as `{count}`, `{{name}}` and `%s` stay in place.

**Quota.** Consumes the monthly character quota: the total length of all items.

**Limits.** 1 to 50 items, each up to 5,000 characters. A protected batch carries at most 20,000 characters in total.

## Request body

- BatchTranslateRequest
  - `items` string[], required: 1 to 50 strings, each up to 5,000 characters. A protected batch carries at most 20,000 characters in total.
  - `target_lang` string, required: BCP 47 target language, applied to every item.
  - `source_lang` string: BCP 47 source language, or `auto` (default).
  - `transliterate` boolean: Include a Latin transliteration when the target is Hebrew.
  - `quality` 'fast' | 'balanced' | 'smartest': Quality tier, applied to every item.
  - `gender` 'male' | 'female' | 'general': Grammatical gender for the reader where the target language marks it.
  - `message_format` 'icu': `icu`: every item is an ICU MessageFormat message. Each result is a valid ICU message in the target language: arguments ({name}, {count, number}, {d, date, short}) and `#` are kept, plural and selectordinal branches are rewritten for the target language's CLDR categories (Hebrew one, two, other; Russian one, few, many, other; English one, other; exact matches such as =0 kept), and select keys are kept. A plural or select inside a sentence is moved to the top so every branch is a whole sentence; `protection.segments` lists each branch sentence. Always protected; Hebrew, English and Russian. Invalid ICU returns 400 `invalid_message_format`; a message that cannot be verified comes back unchanged with `protection.status: "fallback"`.
  - `protect` boolean: Keep prices, quantities, numbers, dates, codes, identifiers, product names, interface variables ({name}, %s) and <keep>…</keep> text exactly as written, and verify every sentence. Implied by any protection field. Hebrew, English and Russian. Account terms switch it on automatically for these pairs.
  - `domain` 'general' | 'clinical' | 'finance' | 'legal': `general` (default) for product, commerce, support and interface text. `clinical` adds clinical register and drug, dose, lab and abbreviation detection. `finance` adds a formal banking register, protects IBANs, SWIFT/BIC codes, bank account numbers (including Israeli bank-branch-account), Israeli ID numbers and card numbers (check digits verified; these values are never shown to the model), invoice, policy and transaction references, signed amounts, rates and basis points, and checks that every money direction (credit/debit, deposit/withdrawal, buy/sell, increase/decrease, gain/loss, who owes whom) is kept. `legal` adds a formal legal register, protects clause and section references (Section 4.2, Clause 7(b), סעיף 12(א), § 3) and case and statute citations, renders each defined term ("the Company") the same way throughout, and checks that modality (shall, may, shall not, is not required to) is kept. Any value implies `protect`.
  - `audience` 'clinician' | 'patient': Clinical domain register. `clinician` (default) keeps shorthand such as BID and PO; `patient` writes it as plain words.
  - `protected_terms` string[]: Terms kept exactly as written: product names, brand names, SKUs. Up to 500, each up to 200 characters. Added to the account terms list for this request.
  - `redact_terms` string[]: Kept exactly and never shown to the model: customer names and other personal data. Up to 200.
  - `glossary` object: Source term → required rendering in the target language. Up to 500 entries. Wins over an account term with the same text.
  - `listener_gender` 'male' | 'female': Gender of the reader ("you"): תרצי / תרצה. Hebrew and Russian mark it; English does not. Without it, Hebrew interface text uses neutral forms.
  - `speaker_gender` 'male' | 'female': Gender of the speaker ("I"), for an assistant or brand voice: מצאתי, я нашла / я нашёл.
  - `patient_gender` 'male' | 'female': Clinical domain: gender of a patient referred to in the third person.
  - `date_order` 'MDY' | 'DMY': How to read ambiguous numeric dates such as 04/03/2026. Default MDY for English sources, DMY for Hebrew and Russian.
  - `date_style` 'hebrew' | 'iso' | 'keep': `hebrew` (default) spells the month out in the target language ("4 במרץ 2026", "4 марта 2026 г."); `iso`; `keep` (unambiguous dates only).
  - `bidi` 'isolate' | 'none': `isolate` wraps protected values in Unicode isolates in Hebrew output. Default none; see /v1/wrap.

## Response `200`

Batch results (input order)

- BatchTranslateResponse
  - `results` TranslationBlock[], required: One translation per item, in input order.
    - `dir` 'ltr' | 'rtl', required: Paragraph base direction. With `base: "auto"` this follows the Unicode first-strong rule, matching CSS `dir="auto"`.
    - `mixed` boolean, required: True when the text contains both strong right-to-left and strong left-to-right letters. Digits and invisible marks do not count.
    - `lang` string, required: Dominant BCP 47 language, from the dominant script.
    - `script` string, required: Dominant ISO 15924 script.
    - `runs` DirectionRun[], required: Runs exactly as the Unicode Bidirectional Algorithm resolves them.
      - `text` string, required: The run text. Equals `input.slice(start, end)`.
      - `dir` 'ltr' | 'rtl', required: Resolved direction of the run.
      - `script` string, required: ISO 15924 script of the run: `Hebr`, `Latn`, `Cyrl`, `Arab`, or `Zyyy` for digits and punctuation only.
      - `lang` string, required: Best-effort BCP 47 language of the run, from its script. `und` when undetermined (numbers, symbols).
      - `start` integer, required: UTF-16 offset of the first character, inclusive.
      - `end` integer, required: UTF-16 offset after the last character, exclusive.
    - `display_runs` DirectionRun[]: Runs for display: every left-to-right unit (a Latin term, a number with its unit, a range, a date, a percentage, a comparison such as <5) is one run, so it never splits or mirrors. Render these, or use /v1/wrap.
      - `text` string, required: The run text. Equals `input.slice(start, end)`.
      - `dir` 'ltr' | 'rtl', required: Resolved direction of the run.
      - `script` string, required: ISO 15924 script of the run: `Hebr`, `Latn`, `Cyrl`, `Arab`, or `Zyyy` for digits and punctuation only.
      - `lang` string, required: Best-effort BCP 47 language of the run, from its script. `und` when undetermined (numbers, symbols).
      - `start` integer, required: UTF-16 offset of the first character, inclusive.
      - `end` integer, required: UTF-16 offset after the last character, exclusive.
    - `text` string, required: The translation, or the source text for sentences that fell back.
    - `transliteration` string, nullable, required: Latin transliteration of a Hebrew result when `transliterate` was true, otherwise null.
    - `protection` Protection: Present when the request used protected translation.
      - `status` 'ok' | 'retried' | 'fallback' | 'passthrough', required: Worst sentence status. `ok`: verified first time. `retried`: a sentence was retried with a stronger model and then passed. `fallback`: at least one sentence could not be verified and is returned in the source language. `passthrough`: no model was needed.
      - `source_lang` string, required: Source language used for protection (detected when `source_lang` is `auto`).
      - `spans` object[], required: Every protected value, in source order.
        - `type` string, required: What was protected: `term`, `glossary`, `number`, `ordinal`, `date`, `identifier`, `email`, `url`, `template` (interface variables), `keep`, `markup`, `code_inline`, `name` (redacted); in the clinical domain `drug`, `dose`, `abbreviation`, `code`; in the finance domain `account` (IBAN, BIC, bank account), `id_number`, `card` (all three redacted), `reference`; in the legal domain `clause`, `citation`, `defined_term` (its `render` is the rendering used throughout).
        - `value` string: The protected source value. Omitted for redacted values.
        - `render` string: How the value was written in the translation, when it was rewritten (dates).
        - `ambiguous_date` boolean: True when a numeric date could be read two ways and `date_order` decided it.
      - `issues` object[], required: Problems found by the checks. Empty when every sentence passed.
        - `code` string, required: Check that failed, e.g. `term_missing`, `date_missing`, `number_added`, `digits_added`, `negation_lost`, `laterality_lost`, `gender_mismatch`, `meaning`, `placeholder_missing`; finance: `direction_swapped` (error), `direction_lost` (warning); legal: `modality_changed`, `defined_term_changed`.
        - `severity` 'error' | 'warning', required
        - `detail` string, required
      - `segments` object[], required: Per-sentence result, in order.
        - `source` string, required
        - `text` string, required
        - `status` 'ok' | 'retried' | 'fallback' | 'passthrough', required
  - `usage` object, required: What this request consumed.
    - `characters` integer, required: Characters charged to the monthly quota for this request.

## Other responses

- `400`: Invalid request: the body failed validation or a value is out of range.
- `401`: Missing, malformed, invalid or revoked API key.
- `402`: A new self-serve account must save a card in the console before it can use the API. Adding a card is free.
- `403`: The connection used TLS older than 1.2.
- `429`: Too many requests this minute (`rate_limited`), or the monthly character quota is used up (`quota_exceeded`). Retry `rate_limited` after a short wait; `quota_exceeded` lasts until the quota resets or the plan changes.
- `500`: Unexpected server error. Safe to retry.
- `502`: The model provider failed or returned an empty result. Nothing was charged. Safe to retry.
- `503`: A model feature is temporarily unavailable.

---

[API](https://skmtc.dev/itsbaba/apis/hebrewcore-api.md) · [All operations](https://skmtc.dev/itsbaba/apis/hebrewcore-api/llms.txt) · [OpenAPI document](https://skmtc.dev/itsbaba/apis/hebrewcore-api/revisions/f54229695236?raw)