A Better Translation Guide for AI Agents: Phrases, Figures of Speech and System-1 Filtering

The Jafar report used to answer one question well: how did Shoghi Effendi render this word? Ask it about a 12-word Persian line and you got every occurrence of every root in that line. That was 1.5 MB of JSON, most of it about other senses of the same letters.

That’s a fine research tool for a person with time. For an AI agent writing a translation it’s noise. The agent needs to know which sense this passage uses, what Shoghi Effendi usually wrote for it, and, most of all, how he rendered the phrase, not just the words.

So we rebuilt the report around three things: a phrase index, a cheap System-1 sense filter, and a compact output shape. It’s one free report now. There used to be a free concordance lookup and a paid AI-filtered one; that split is gone.

Why phrases matter more than words in Shoghi Effendi’s translations

Here is a line from the Epistle to the Son of the Wolf, §111:

حقّ جلّ جلاله هر حين بمظاهر نفسش ظاهر با علم يفعل ما يشاء و يحکم ما يريد آمده

Look up علم word by word and the concordance is right that it usually means knowledge: 209 times. Our sense filter agrees, at 99% confidence. And it’s wrong. Shoghi Effendi wrote:

He came unto men with the standard of “He doeth what He willeth, and ordaineth what He pleaseth.”

علم here is a banner, and you only see that from the words around it. The phrase علم يفعل ما يشاء occurs three times in the corpus, and every time he rendered it as a standard or banner raised over “He doeth whatsoever He willeth.” No single-word lookup finds that. A phrase lookup finds it in under 2 ms.

Building the phrase and figure-of-speech index

The index is built when the dictionary compiles, from the same aligned corpus described in Building the Jafar dictionary. Nothing calls an AI when you query it.

Every 2–4-word run of source text is a candidate, function words included. That matters: لا يزال and يفعل ما يشاء are made of the little words a root-based concordance throws away.
The English is taken for the whole span. Every word already carries its position in Shoghi Effendi’s English, so the phrase’s rendering is the stretch of English its words cover, snapped to whole words.
A phrase must recur in at least two paragraphs. One-off word pairs are left out.
Duplicates collapse. A shorter phrase that only ever appears inside a longer one is dropped, and so are copies with a stray “and” on the edge.
Each phrase keeps up to three real examples, one per distinct rendering first. Each has the source clause and his English clause, with the phrase marked ⟦like this⟧ and a link to the paragraph.

That gives 7,432 phrases. Then each one gets a kind: formula (جلّ جلاله, “exalted be His glory”), idiom (امر بمقامی رسید, “things have come to such a pass”), metaphor (سبحات جلال, “veils of glory”; سکر خمر, “inebriated with the wine”), title, or plain collocation. Formulas come from a curated list. Idioms are phrases whose English shares no word with their parts’ usual renderings. A one-time System-1 pass labelled the 3,210 most frequent phrases for 3.9 cents total, and only confident labels are kept. That pass found 336 metaphors I’d never have listed by hand.

Out of 20 idioms and formulas I checked (لم يزل, لا يزال, سدرة المنتهى, الملأ الأعلى, ما کان و ما یکون and so on), 19 come back with Shoghi Effendi’s rendering. The miss, عزّ ذکره, doesn’t recur in the corpus.

Choosing the right sense with System-1, not Haiku

The old paid report ran each result list through Claude Haiku and asked it to score every row. It cost about $0.003 a report and took 3 seconds. Worse, Haiku never saw context: our rows held the bare word and its rendering, so it was guessing.

The new filter works from the data. Each occurrence in the dictionary has a short gloss, so a word’s possible senses fall out of its own occurrences. For example, امر glosses as matter, command or Cause. One System-1 call per report then answers a typed multiple-choice question for each ambiguous word: which of these senses does the passage use? Every answer carries a confidence. Examples are kept when they carry that sense.

On a 25-passage test set (13 Persian, 12 Arabic, 900 hand-labelled example pairs):

	Precision	Recall	F1	Cost per report	Time
Raw report	0.33	1.00	0.50	—	—
Haiku prompt (5 passages)	0.58	0.53	0.55	$0.0031	3.0 s
Senses + one System-1 choice	0.73	0.89	0.81	$0.00003	0.4 s
Same, System-1 unavailable (most common sense)	0.72	0.85	0.78	$0	—

The answers are cached for 30 days, so a repeated question costs nothing. If System-1 is down the report falls back to each word’s most common sense, never to a paid model.

A compact report sized for an AI agent’s context window

Filtering alone still left about 200,000 tokens per passage, because it kept every relevant row. The compact report keeps what a translator uses:

per phrase: Shoghi Effendi’s rendering, his other renderings with counts, and up to three examples
per term: the sense chosen here with its confidence, an uncertain flag when the model isn’t sure, the top five renderings with counts, the three best examples, and a more.url for everything else

Examples that sit inside a matched phrase rank first. I labelled every example the compact report actually shows (310 labels) to check that the ranking holds up:

	First example relevant	Top-3 precision
Filter order	82%	83%
Phrase-backed first	89%	85%

And the size, averaged over the same 25 passages, with exact token counts:

Report	Tokens
Raw concordance	436,472
Filtered, every row	202,617
Compact guide (JSON)	5,244
Compact guide as plain text	1,551

That’s small enough to drop straight into a translation prompt.

How AI agents call the Jafar translation guide

Create a free key at the dashboard, then:

curl -X POST https://ctai.info/api/v1/jafar \
  -H "Authorization: Bearer ctai_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"text": "هر حين بمظاهر نفسش ظاهر با علم يفعل ما يشاء و يحکم ما يريد آمده", "source_lang": "fa", "format": "text"}'

You get the usual enriched_terms, plus phrases, plus guide (the compact JSON) and guide_text (the same thing as prompt-ready text). Part of the text for that line:

PHRASES (Shoghi Effendi's rendering of the whole phrase):
- علم يفعل ما يشاء → "the standard of "He doeth what He willeth" (collocation, 3×; also "banner of "He doeth whatsoever He willeth")
    Epistle to the Son of the Wolf §111: …He came unto men with ⟦the standard of "He doeth what He willeth⟧, and ordaineth what He pleaseth.
- يحکم ما يريد → "ordaineth whatsoever He pleaseth" (collocation, 8×; …)
TERMS:
- حین [ḥ-y-n] sense here: time (73%) — renderings: "times"×21, "moment"×15, "hour"×6, …
- یرید [r-y-d] sense here: want; desire (37%) UNCERTAIN — renderings: "wish"×9, "desire"×8, "pleaseth"×7, …

/api/v1/concordance returns the same compact guide without the enrichment block. Add "detail": "full" for every row, or "filter": false to skip the sense choice. The full spec is at /api/v1. People can try the same report by hand on the Jafar page, where phrases now show above the word list.

If you’re already sending filter: false to /api/v1/jafar, you get the phrases anyway. They’re appended to enriched_terms with is_phrase: true, so an existing client picks up “the standard of ‘He doeth what He willeth’” without changing a line. One more fix went in along the way: /api/v1/jafar used to come back empty for passages over about 50 words, because its lookups ran one at a time into a timeout. They run in parallel now.

What the Jafar translation guide still gets wrong

A single word’s sense can still be wrong. The filter chose knowledge for علم at 99% in the example above. The phrase is what saved it. With no matching phrase, a short, genuinely ambiguous line can get the commoner sense. Watch the uncertain flag and the phrase list.
Near matches are limited to figures of speech. The same roots in another form (سبحاته جلاله for سبحات جلال) only match idioms, metaphors, formulas and titles. For ordinary word pairs, matching by root alone found too many different phrases.
The labels are mine alone. One annotator, a strict “same word, same sense” rule, and I tuned the phrase-first ranking while looking at these same 25 passages. Treat 89% as a good sign, not a benchmark.
Phrases must recur. A phrase Shoghi Effendi translated once isn’t in the index. For a passage that’s already in the corpus, /api/v1/passages gives his exact rendering.