Developer example · Python + TypeScript

Translate Darija text with context

Use Tarjamli for translation, Arabic ↔ Latin Darija, and instructions for address, gender and tone. Start from checked outputs and a Python + TypeScript starter.

Resources

Run it with your own text ↓

One message, two ways to address the reader.

Informal · tu

ary_Arab → fra_Latn

واش تقدر تصيفط ليا الدوسي؟

Instruction: Address one person informally using tu.

Peux-tu m'envoyer le dossier ?

Formal · vous

ary_Arab → fra_Latn

واش تقدر تصيفط ليا الدوسي؟

Instruction: Address one person formally using vous.

Pourriez-vous m'envoyer le dossier ?

Saved Mini v4 responses captured on 8 November 2026. The source text stays the same. The instruction supplies the address form that Darija leaves open. These are selected examples, not a benchmark or a live request.

Use context where the source leaves a choice.

For developers localizing messages, support tools or content workflows, a target-language code is only part of the request. The reader, speaker and tone can change how a translation should be written. Tarjamli Mini v4 accepts an optional instruction alongside the text and explicit source and target codes.

  1. 01Text + language/script codes
  2. 02Optional context
  3. 03Tarjamli Mini v4
  4. 04Review the translation

Send text, source and target to POST /v1/language/translate. Add instructions when needed. The SDK verifies response completeness and the returned model and language codes before returning the text.

Translation and script conversion are different tasks.

Darija → English

ary_Arab → eng_Latn

واش نقدر نحجز جوج بلايص لغدا؟

Can I reserve two seats for tomorrow?

Darija → Turkish

ary_Arab → tur_Latn

واش نقدر نحجز جوج بلايص لغدا؟

Yarın için iki yer ayırtabilir miyim?

Darija · Arabic script → Latin script

ary_Arab → ary_Latn

سلام، واش نقدر نحجز جوج بلايص لغدا؟

Salam, wach nqder n7jez jouj blayes lghda?

Darija · Latin script → Arabic script

ary_Latn → ary_Arab

Salam, wach n9der n7jez jouj blayes lghdda?

سلام، واش نقدر نحجز جوج بلايص غدا؟

Use ary_Arab and ary_Latn for the same Darija variety in different scripts. Latin-script Darija is often called Arabizi. Converting the script does not translate the message into another language. These two saved directions use separate inputs; they are not a round-trip fidelity test.

Choose address, speaker gender and tone explicitly.

Speaker gender · female

eng_Latn → fra_Latn

I am happy to be here.

Instruction: The speaker is female. Use the corresponding grammatical gender. Return only the translation.

Je suis heureuse d'être ici.

Speaker gender · male

eng_Latn → fra_Latn

I am happy to be here.

Instruction: The speaker is male. Use the corresponding grammatical gender. Return only the translation.

Je suis heureux d'être ici.

Casual tone

eng_Latn → fra_Latn

We need your reply by tomorrow.

Instruction: Use a casual tone. Preserve the deadline and meaning. Return only the translation.

On a besoin de ta réponse pour demain.

Formal tone

eng_Latn → fra_Latn

We need your reply by tomorrow.

Instruction: Use a formal tone. Preserve the deadline and meaning. Return only the translation.

Nous avons besoin de votre réponse d'ici demain.

Mini v4 supports instructions. Nano does not. Do not send an instruction to Nano and assume it was applied. An instruction can help resolve a choice, but it does not replace a language review or guarantee that every constraint will be met.

Run it with your own text.

Use Python 3.10+ and a Sawalni account. Create an API key, enable Tarjamli access and add enough API credits. The package calls the hosted service. It does not run a translation model locally.

Create a key · Check access · Check credits.

1. Install the pinned starter

Set up translation
git clone https://github.com/omneity-labs/starter-translation.git
cd starter-translation
git checkout 97b45ad270947784d86e3d8041f5d02d168e4364
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt
export SAWALNI_API_KEY="your-key"

2. Replace the text and language codes

Translate your text
python python/run.py --text 'واش تقدر تصيفط ليا الدوسي؟' --source ary_Arab --target fra_Latn --instructions 'Address one person formally using vous.'

Remove --instructions for a standard translation. Use python python/run.py --languages to list the starter’s supported language/script codes. Keep the API key in the same terminal environment. The scripts do not load .env automatically.

3. Inspect saved examples without a key

Inspect a saved translation
python python/run.py --saved french-vous-darija
Prefer TypeScript?

Use Node 20+ from the starter root.

TypeScript translation
npm ci
export SAWALNI_API_KEY="your-key"
npm run example -- --text 'واش تقدر تصيفط ليا الدوسي؟' --source ary_Arab --target fra_Latn --instructions 'Address one person formally using vous.'
Use the package directly in Python
Python SDK
from tarjamli import Tarjamli

client = Tarjamli()
result = client.translate(
    "واش تقدر تصيفط ليا الدوسي؟",
    source="ary_Arab",
    target="fra_Latn",
    instructions="Address one person formally using vous.",
)
print(result.text)

The SDK also exposes the full response through result.raw. Keep this call on your server or in a local script.

Use the language and script code you need.

Tachelhit · Latin script

ary_Arab → shi_Latn

الما

Aman

Standard Moroccan Tamazight · Tifinagh

fra_Latn → zgh_Tfng

eau

ⴰⵎⴰⵏ

These short vocabulary examples show shi_Latn and zgh_Tfng. They do not establish sentence-level translation quality. Amazigh is a language grouping; Tachelhit is a variety, while Tifinagh is a script. Arabic script and Latin script are also writing systems. A registry entry is not a promise of equal quality across language pairs.

Language identifiers are specific to each API. Tarjamli’s shi_Latn translation code does not make shi an accepted forced hint for Daktilo transcription.

Handle incomplete output before publishing.

  • The API requires explicit source and target codes. The text limit is 262,144 UTF-8 bytes. Mini v4 instructions are limited to 32,768 UTF-8 bytes.
  • The Python package is pinned to the checked Mini v4 model. The starter rejects incomplete responses and unexpected model or language identities.
  • HTTP errors stop the request. Calls are not automatically retried. Check access, credits and rate limits before deciding to retry.
  • Review names, numbers, omitted details, tone and script choice. Selected examples do not replace a review of your own text.

Keep the source and the next step together.

The published fixtures preserve the requests, model identities, capture dates and outputs used here. The starter code and fixtures use the repository’s MIT license. No outputs were regenerated for this article.

For an audio recording, first create and review its source transcript. The Darija captions example covers that step. Its optional translation extension translates text or SRT after review. ASAT speech generation is a separate operation.

Run it with your own text ↑