Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.camb.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

pip install camb-sdk
Skip this step if you’re using the direct API.
4

Set your API key to use in your code

export CAMB_API_KEY="your_api_key_here"

Code

import os
import time
from camb.client import CambAI

client = CambAI(api_key=os.getenv("CAMB_API_KEY"))

def translate_texts():
    source_texts = [
        "Thank you for your inquiry about our services.",
        "We would be happy to schedule a meeting next week.",
        "Please let us know what day works best for you.",
    ]

    # Step 1: Submit the translation job
    response = client.translation.create_translation(
        texts=source_texts,
        source_language=1,    # English
        target_language=54,   # Spanish (Spain)
        formality=1,          # Formal
        gender=1,             # Masculine grammatical forms when relevant
        age=30,
    )

    task_id = response.task_id
    print(f"Translation task created: {task_id}")

    # Step 2: Poll until complete
    while True:
        status = client.translation.get_translation_task_status(task_id=task_id)
        print(f"Status: {status.status}")

        if status.status == "SUCCESS":
            # Step 3: Retrieve the translated texts
            result = client.translation.get_translation_result(run_id=status.run_id)
            for src, dst in zip(source_texts, result.texts):
                print(f"EN: {src}\nES: {dst}\n---")
            break
        elif status.status in ("ERROR", "TIMEOUT", "PAYMENT_REQUIRED"):
            print(f"Translation failed: {status.status}")
            break

        time.sleep(2)

translate_texts()

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_languageintegerSource-language ID for the input texts (e.g. 1 for English).
target_languageintegerTarget-language ID for the output texts (e.g. 54 for Spanish).

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.

Language IDs

Translation requires both a source_language and a target_language ID. Some commonly used values:
LanguageID
English1
Spanish54
French76
German31
Mandarin Chinese139
Japanese88
Arabic4

Full list of supported source-language IDs.

Full list of supported target-language IDs.

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.