Transform T4T into unfoldingWord Simplified Text (UST), communicating the original meaning in natural English. Use when asked to create UST, generate simplified text, or transform T4T.
In restricted runs, use workspace MCP tools instead of shell/python snippets:
mcp__workspace-tools__fetch_t4t, mcp__workspace-tools__fetch_door43mcp__workspace-tools__read_usfm_chapter — read a single chapter from a book file (use this instead of reading full books)mcp__workspace-tools__build_ust_indexmcp__workspace-tools__check_ust_passivesmcp__workspace-tools__curly_quotesIf --context <path> is provided, read the context.json file first. Treat it as authoritative.
Use these fields when present:
sources.ult — authoritative ULT for this chapter. In the normal pipeline this is the just-generated, issue-reviewed ULT. In UST-only runs the pipeline runner has already chosen between the freshest local generated ULT and freshly fetched en_ult master.sources.ultFull — full-book ULT file when the runner fetched onesources.hebrew — Hebrew source pathsources.issues — authoritative issues TSV path when availableWhen a context file is provided:
data/published_ult_english/The UST creation process starts with the T4T (Translation for Translators) as the base text. The goal is to modify T4T as little as possible while ensuring it is:
Do NOT start from scratch. Read the T4T first, verify it against Hebrew/ULT, then make targeted adjustments.
Note on published UST: The UST currently on Door43, if not from our recently published approved work, was adapted from T4T long ago by underskilled volunteers and should largely be ignored as a reference. Use T4T as your primary starting point.
The UST must be noticeably different from the ULT. If the only difference is removing "And" at the start, you haven't done enough.
The UST should:
Test: Read the ULT and UST side by side. If they sound nearly identical, rewrite the UST. In particular, when the ULT preserves figurative imagery (metaphors, yoke/burden language, body-part idioms), the UST should unpack the meaning rather than echo the same image.
| ULT | Bad UST (too similar) | Good UST (differentiated) |
|---|---|---|
| "He gave over their cattle to the hail" | "He gave over their cattle to the hail" | "He let the hail kill their cattle" |
| "and their livestock to the bolts of lightning" | "and their livestock to the bolts of lightning" | "and he let lightning strike their livestock" |
| "They tested God in their heart" | "They tested God in their heart" | "They challenged God to see if he would help them" |
| "by asking for food for their craving" | "by asking for food for their craving" | "by demanding the food they wanted" |
Prefer common words over formal/literary ones:
| ULT/Formal | UST/Simple |
|---|---|
| livestock | animals / herds |
| craving | desire / want |
| iniquity | sin / evil |
| transgressions | sins |
| rebuke | correct / scold |
| wrath | anger |
| affliction | suffering / trouble |
| insolent | proud / arrogant |
| abhor | hate / reject |
| slumber | sleep |
| give over to | let X destroy / hand over to |
Hebrew poetry often says the same thing twice with different words (synonymous parallelism). In UST, collapse true parallelism into one statement when both lines express the same meaning.
| ULT (parallel lines) | UST (collapsed) |
|---|---|
| "He gave over their cattle to the hail / and their livestock to the bolts of lightning" | "He sent a terrible thunderstorm with hail to kill all their cattle" |
| "They did not keep the covenant of God / and they refused to walk in his law" | "They refused to obey God's covenant and law" |
| "Yahweh knows the way of the righteous / but the way of the wicked will perish" | Keep both - this is antithetic parallelism (contrast), not synonymous |
Judgment call: If the second line adds new information or contrasts with the first, keep both lines. If it just restates the first line with different words, collapse them.
Use mcp__workspace-tools__read_usfm_chapter to read only the target chapter from the T4T file (e.g., file: data/t4t/25-LAM.usfm, chapter: 3). Do NOT read the entire book file — only the chapter you are generating.
Use mcp__workspace-tools__fetch_t4t when T4T files are missing or stale.
T4T uses special markers that serve two purposes:
| Marker | Meaning | UST Implication |
|---|---|---|
\add...\add* | Implicit information | Usually weave into prose; rarely bracket |
[IDI] | Idiom | Render the meaning, not literal form |
[DOU] | Doublet (repetition for emphasis) | May simplify or keep both terms |
[SYN] | Synecdoche (part for whole) | Express the intended referent |
[RHQ] | Rhetorical question | Keep as question or convert to statement |
[EUP] | Euphemism | Use clear language |
[MTY] | Metonymy (association) | Express what is actually meant |
[MET] | Metaphor | State the plain meaning; do not preserve the image |
[SIM] | Simile | State the plain meaning; do not preserve the comparison |
These markers are valuable pre-identified translation issues - use them to inform your rendering choices before removing them from the final text. When you see [MET] or [SIM], the T4T is flagging figurative language — strip the marker AND replace the figure with what it means in plain English.
Check that T4T accurately represents the Hebrew meaning:
mcp__workspace-tools__read_usfm_chapter on data/hebrew_bible/[BOOK].usfm for the target chapter only--context was provided, read sources.ult from context.json. Otherwise use mcp__workspace-tools__read_usfm_chapter on the freshest available local ULT, falling back to a fresh mcp__workspace-tools__fetch_door43 from en_ultKey relationship:
If T4T diverges from Hebrew meaning, correct the meaning. If T4T and ULT express the same meaning differently, that's expected — they serve different purposes.
The purpose of this step is to catch T4T meaning errors — places where the T4T got the meaning wrong. It is NOT a license to import Hebrew phrasing, imagery, or structure into the UST. If the T4T's meaning is correct, keep the T4T's wording even if the Hebrew is more vivid or poetic.
Before generating UST, check for any pre-identified translation issues:
If --context was provided and sources.issues is set, use that exact issues TSV path. Otherwise look for issue files at output/issues/<BOOK>/<BOOK>-<CHAPTER>.tsv and verse-range variants under output/issues/<BOOK>/
If found, read the identified issues - these flag constructions needing attention:
Use identified issues to guide your transformation decisions in Step 4
Compare T4T to unfoldingWord standards. Flag areas that need adjustment:
Check Issues Resolved for authoritative decisions using Grep on data/issues_resolved_optimized.txt (topically organized). If that file is missing, fall back to data/issues_resolved.txt.
Remove T4T notation markers - [IDI], [DOU], [SYN], [RHQ], [EUP], [MTY], [MET], [SIM]
Handle \add...\add* markers - weave into prose; rarely bracket (see Step 4A)
Check for unfoldingWord-specific requirements:
Apply only necessary changes. The T4T is already a good meaning-based translation.
| T4T | UST |
|---|---|
\add text \add* | Evaluate: most become unbracketed natural prose |
[IDI], [DOU], etc. | Remove entirely |
[RHQ] | Remove (keep the rhetorical question) |
T4T \add...\add* markers: These mark where T4T added clarifying information. In UST, most of this content should be woven into natural prose WITHOUT brackets. Only use {brackets} when the added content is:
Important edge case: If a \add phrase is a verse-initial framing clause (scene-setting such as travel/worship setting, speaker setup, or inferred self-talk context) and it has no direct Hebrew expression, prefer {brackets} instead of plain prose.
Example (PSA 121:1):
{As I travel toward Jerusalem,} I look toward the hills and ask myself, “Where will my help come from?”As I travel toward Jerusalem, I look toward the hills ... (reads as if directly expressed in source)Quick decision check per \add segment: drop / weave / bracket.
See reference/ust_patterns.md Section 8 for detailed guidance.
T4T may use "the LORD" or other renderings. Update to:
Use Grep for issues/glossary checks and mcp__workspace-tools__build_ust_index (lookup) for published precedent.
When a vocabulary decision requires checking published precedent (UST index, glossaries, or issues_resolved), record it in data/quick-ref/ust_decisions.csv for future reference. Only record non-trivial decisions -- common words that map obviously don't need tracking.
# Check if decision already recorded
grep "H2617" data/quick-ref/ust_decisions.csv 2>/dev/null
# Append new decision (creates file with header if needed)
echo "H2617,chesed,faithful love,PSA,dominant UST rendering 67%,,$(date +%Y-%m-%d)" >> data/quick-ref/ust_decisions.csv
Every passive construction must be converted to active voice.
Detection pattern: auxiliary (be/is/are/was/were/been/being) + past participle
| ULT/T4T (passive) | UST (active) |
|---|---|
| "they will be killed" | "they will die" / "someone will kill them" |
| "will be eaten by jackals" | "jackals will eat" |
| "A psalm written by David" | "David wrote this song" |
| "it was told to Solomon" | "Someone told Solomon" |
If you cannot identify the agent, use:
When identified issues flag figs-abstractnouns, convert the abstract noun to a verbal or clausal form:
| Abstract (ULT/T4T) | Verbal (UST) |
|---|---|
| "the salvation of Yahweh" | "how Yahweh saves" |
| "his righteousness" | "how righteous he is" |
| "the fear of Yahweh" | "to deeply respect Yahweh" |
| "covenant faithfulness" | "You are always kind to me, as you promised" |
| "his power and glory" | "how powerful and glorious you are" |
Ask: What action or quality does this noun represent? Express it as a verb or clause.
When identified issues flag figs-nominaladj, unpack the nominalized adjective into its full meaning:
| Nominalized (ULT/T4T) | Unpacked (UST) |
|---|---|
| "the wicked" | "wicked people" / "people who do evil" |
| "the righteous" | "righteous people" / "people who do what is right" |
| "the dead" | "dead people" / "people who have died" |
| "the poor" | "poor people" / "people who are poor" |
The UST should make clear who or what is being described.
When the issues file flags figs-metaphor or figs-simile, or T4T markers [MET]/[SIM] are present:
| Hebrew figure | BAD (preserved/new metaphor) | GOOD (plain meaning) |
|---|---|---|
| "breath of our nostrils" (king) | "as essential as the breath in our nostrils" | "the one who kept us alive" |
| "poured out his anger" | "poured out his fierce anger" | "showed how extremely angry he was" |
| "drink from the cup of anger" | "drink from the cup of his anger" | "Yahweh will punish you severely" |
| "purer than snow, whiter than milk" | "brighter than snow, whiter than milk" | "very pure and healthy-looking" |
| "wrapped in anger" | "wrapped yourself in anger" | "because you were angry" |
| "streams of water from my eye" | "tears like streams of water" | "many tears flow from my eyes" |
| "saturated with wormwood" | "drenched me in misery" | "caused me to suffer greatly" |
| "walled up my ways with stone" | "blocked every way forward" (English path idiom) | "prevented me from making any progress" |
| "a bear lying in ambush" | "waited in hiding" (still figurative) | "attacked me suddenly and without warning" |
| "he bent his bow / shot arrows into my body" | "He shot his arrows deep into my body" (literal fact) | "He deliberately caused me intense suffering" |
| "made my teeth grind on gravel / pressed me in ashes" | "made me chew on gravel / pushed my face in ashes" (literal fact) | "He completely humiliated and degraded me" |
(See Active Voice above for passive → active conversion)
Superscription verse anchoring:
Do not assume all psalm headings belong in \d before verse 1. Anchor placement to the Hebrew chapter structure:
If Hebrew \v 1 contains both superscription and body text (e.g., Psalms 120-134 "song of ascents" + body), the superscription is part of verse 1. Output as:
\d
\v 1 A song of ascents.
\q1 Yahweh, remember David
\q2 and all of the difficulties that he had.
\d is an empty paragraph-style marker (tells renderers to style what follows as a superscription). \v 1 contains just the superscription text. \q1 starts the poetry body, still part of verse 1. Do NOT put text on the \d line, do NOT put \d after \v 1, and do NOT omit \d.
If Hebrew has superscription words only in \v 1 (no body text until \v 2), with verse-offset markers showing English versification is shifted (Hebrew v2 = English v1), keep the superscription on \d with its text and start body at English \v 1:
\d This is for the chief musician. It is a psalm of David.
\v 1 All the people on the earth, shout joyfully to God!
Quick check at chapter start:
\c N in Hebrew.\v 1 has both superscription words AND body text: use format 1 (empty \d, superscription in \v 1).\v 1 has only superscription words and body starts at \v 2: use format 2 (\d with text, body at English \v 1).If T4T starts sentences with "And" or "But", replace:
Cross-check with:
reference/ust_patterns.md - transformation patterns../reference/gl_guidelines.md - shared style rules (formality, numbers, spelling, comparisons){Brackets} - Use Sparingly:
{As I travel toward Jerusalem,})Ensure proper USFM formatting:
\id [BOOK] - unfoldingWord Simplified Text
\usfm 3.0
\h [Book Name]
\toc1 [Full Book Name]
\toc2 [Abbreviated Name]
\toc3 [Short Code]
\mt [Main Title]
\c [chapter]
\p
\v [verse] [text]
\q1 [poetry line 1]
\q2 [poetry line 2 - indented]
Poetry markers:
\q1 - first colon of a verse\q2 - second/third colon (parallel lines)\d - superscription (Psalms, only when Hebrew has standalone heading)\qs ... \qs* - SelahSave to output/AI-UST/ with naming convention:
output/AI-UST/[BOOK]/[BOOK]-[CHAPTER].usfm
After writing the UST USFM, write a hints JSON that records which Hebrew words you rendered in each English phrase. As you generated each phrase, you knew which Hebrew concepts you were rendering -- capture that mapping now.
Output path: output/AI-UST/hints/<BOOK>/<BOOK>-<CH>.json
Format:
[
{
"reference": "PSA 1:1",
"hints": [
{"english": "The person who will have a truly good life", "hebrew_indices": [0, 1]},
{"english": "is the person who", "hebrew_indices": [2]},
{"english": "does not do what evil people tell him to do,", "hebrew_indices": [3, 4, 5, 6]},
{"english": "{It seems like}", "hebrew_indices": [], "implied": true}
]
}
]
Rules:
english = phrase from the UST, matching english_text word-for-wordhebrew_indices = which Hebrew word positions (0-based) contributed meaning to that phrase"implied": true on entries with bracketed content (hebrew_indices: [])Run mcp__workspace-tools__check_ust_passives on output/AI-UST/[BOOK]/[BOOK]-[CHAPTER].usfm.
If passives are found (exit code 1), fix them before proceeding. The script prints each passive phrase with its verse reference to stderr.
Run mcp__workspace-tools__curly_quotes with inPlace: true to normalize quotes.
This converts:
"..." to curly "..."'...' to curly '...'Use mcp__workspace-tools__fetch_t4t with books=["PSA", "1KI"] (or omit books to list available).
Use Grep for quick text lookups in:
data/issues_resolved_optimized.txt (or data/issues_resolved.txt)data/quick-ref/ust_decisions.csvdata/glossary/*.csvWhen comparing T4T to ULT, prefer chapter reads from mcp__workspace-tools__read_usfm_chapter using the authoritative ULT path from context when available.
For steps 3 and 4 (UST Strong's index), use mcp__workspace-tools__build_ust_index with lookup="H2617" or compare="H2617".
Use mcp__workspace-tools__build_ust_index with optional parameters:
lookup="H2617" — look up published UST renderings for a Strong's numbercompare="H2617" — compare ULT (literal) vs UST (meaning-based) renderingsstats=true — index statisticsIf alignment data is needed, use the aligned ULT supplied by the pipeline context or the workspace MCP alignment tools. Do not rely on ad hoc shell scripts or /tmp files.
Before finalizing UST output, verify:
T4T Conversion:
\add...\add* content woven into natural prose (rarely bracketed)unfoldingWord Standards:
Style:
\v 1-embedded vs standalone \d)Always check these at runtime - do not rely on memory:
| Source | Path | Purpose |
|---|---|---|
| T4T | data/t4t/*.usfm | PRIMARY SOURCE for UST |
| Issues Resolved | data/issues_resolved_optimized.txt | FINAL AUTHORITY - UST decisions (topically organized; fallback: data/issues_resolved.txt) |
| Hebrew Glossary | data/glossary/hebrew_ot_glossary.csv | UST_GLOSS column |
| Psalms Reference | data/glossary/psalms_reference.csv | UST_GLOSS column |
| Sacrifice Terms | data/glossary/sacrifice_terminology.csv | UST_GLOSS column where available |
| Measurements | data/glossary/biblical_measurements.csv | UST_GLOSS column where available |
| Biblical Phrases | data/glossary/biblical_phrases.csv | UST_GLOSS column where available |
| Context ULT | context.json -> sources.ult | Meaning verification (authoritative when present) |
| UST Strong's Index | data/cache/ust_index.json | Published UST renderings by Strong's number |
| UST Decisions | data/quick-ref/ust_decisions.csv | Prior UST vocabulary decisions |
| UST Patterns | reference/ust_patterns.md | Transformation rules |
| Style Guide | ../reference/gl_guidelines.md | Shared style rules |
Note: data/published_ust/ contains older UST that may not meet current standards. Use T4T as your base, not published UST. The UST Strong's index is still useful for seeing how published UST renders specific Hebrew words -- treat it as precedent to consider, not authority to follow. Likewise, when context.json is present, its ULT path overrides any published-ULT fallback.