Skip to main content

Overview

Translate an array of text segments from one language into another with fine-grained control over tone (formality), grammatical gender, audience age, and domain-specific terminology (chosen_dictionaries). Translation is ideal for localizing user content, documents, support replies, marketing copy, or any batch of strings that needs to read naturally in another language. The translation pipeline is asynchronous: you submit a job with one or more texts, poll until it completes, then retrieve the translations in the same order as the inputs.

Prerequisites

1

Create an account

Sign up at CAMB.AI Studio if you haven’t already.
2

Get your API key

Go to Settings → API Keys in Studio and copy your key. See Authentication for details.
3

Install the SDK

Skip this step if you’re using the direct API.
4

Set your API key to use in your code


Code


Customization options

Formality

Adjust the formality level to fit the context. This affects pronoun choice (e.g. tú vs usted in Spanish, du vs Sie in German) and overall register.
ValueMeaningBest for
1FormalBusiness communications, official documents, customer support
2InformalCasual chat, social posts, friendly marketing

Gender

In many target languages, adjectives, articles, and past participles agree with gender. Use the gender parameter to tell the engine which grammatical forms to prefer.
ValueMeaning
0Unspecified / neutral
1Masculine forms
2Feminine forms
9Other

Age

Pass an integer (e.g. 12, 30, 65) to bias vocabulary and idioms toward an audience age range. Useful when translating content meant for kids or for very formal/elder audiences.

Chosen dictionaries

Pass an array of dictionary IDs via chosen_dictionaries to apply specialized vocabulary (medical, legal, technical, etc.). Manage your dictionaries with the Dictionaries API.

Parameters

Required

ParameterTypeDescription
textsstring[]Array of text segments to translate. Each item is translated independently and returned in the same order.
source_languageLanguages enumSource language (e.g. Languages.EN_US). The raw API also accepts locale-tag strings like "en-us"; numeric IDs still work but are deprecated.
target_languageLanguages enumTarget language (e.g. Languages.ES_ES).

Optional

ParameterTypeDescription
formalityinteger1 for formal, 2 for informal
genderintegerGrammatical gender hint: 0, 1, 2, or 9 (see table above)
ageintegerTarget audience age, used to adapt vocabulary
chosen_dictionariesinteger[]Dictionary IDs to apply specialized vocabulary
project_namestringLabel for the job in your dashboard
project_descriptionstringAdditional notes for the job
folder_idintegerPlace the run inside a specific folder

Result shape

get_translation_result returns a TranslationResult with a single field:
FieldTypeDescription
textsstring[]Translated outputs, in the same order as the input texts. Pair index-by-index with the original array.

Languages

Translation requires both a source_language and a target_language. The Python and TypeScript SDKs expect the Languages enum:
LanguageEnumLocale (raw API)
English (US)Languages.EN_USen-us
Spanish (Spain)Languages.ES_ESes-es
French (France)Languages.FR_FRfr-fr
German (Germany)Languages.DE_DEde-de
Mandarin ChineseLanguages.ZH_CNzh-cn
Japanese (Japan)Languages.JA_JPja-jp
ArabicLanguages.AR_SAar-sa
If you’re calling the API directly (not via the SDK), pass the locale tag. Numeric language IDs still work but are deprecated.

Full list of supported source languages.

Full list of supported target languages.

Tips

  • Batch in one call: Pass multiple strings in a single texts array instead of submitting one task per string — it is faster and uses fewer credits.
  • Preserve order: result.texts[i] always corresponds to texts[i] from the input. Pair them with zip (Python) or index-by-index access (TypeScript).
  • Polling cadence: Translation is usually quick; a 1-2 second polling interval works well. Cap the total wait time (for example, 5 minutes) so your code never hangs forever.
  • Pick the right register: Setting formality and gender on customer-facing translations dramatically improves how natural the output reads in languages like Spanish, French, German, and Italian.
  • Domain accuracy: For medical, legal, or technical content, define a dictionary first and pass its ID in chosen_dictionaries so jargon is translated consistently across runs.

Next Steps

Create Translation API

Full API reference for the translation endpoint.

Poll Translation Status

Status polling endpoint reference.

Get Translation Result

Retrieve the translated texts for a completed run.

Fetch Multiple Runs

Batch-fetch results for several translation run IDs in one call.