UST-alignment

Generate meaning-based Hebrew-to-English UST alignments as JSON mappings.

1|Updated Mar 25, 2026
One-click install
npx skills add https://github.com/unfoldingWord/bp-assistant-skills --skill ust-alignment
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: UST-alignment
Source: https://github.com/unfoldingWord/bp-assistant-skills/tree/main/.claude/skills/UST-alignment
Command: npx skills add https://github.com/unfoldingWord/bp-assistant-skills --skill ust-alignment

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Create precise, meaning-based alignments between Hebrew source text and English UST translations, handling radical restructuring and implied information to produce usable alignment data.

Core Features & Use Cases

  • Two-step workflow: AI generates index-based mappings from Hebrew to English phrases, and a script converts mappings into properly formatted aligned USFM.
  • Handles superscriptions, implied information, and split alignments, outputting a JSON structure compatible with downstream USFM tools.
  • Use case: align a Hebrew verse with its UST rendering to produce a machine-readable mapping for publication or QA.

Quick Start

Provide Hebrew USFM and English UST draft to generate a meaning-based alignment and output the JSON mapping.

Frequently Asked Questions about UST-alignment

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I align Hebrew source text with an English UST translation?

To align Hebrew source text with an English UST translation, you provide the Hebrew USFM and English UST draft. The system generates index-based mappings from Hebrew to English phrases and outputs a machine-readable JSON mapping.

How does meaning-based translation alignment handle implied information and restructuring?

Meaning-based alignment handles implied information and radical restructuring by mapping phrases based on semantic equivalence rather than strict word-for-word matching. It constructs index-based mappings to accurately represent split alignments and superscriptions in the output.

Can I convert Hebrew-to-English alignment mappings into USFM format?

Yes, you can convert alignment mappings into USFM format. The workflow uses a two-step process where the AI generates index-based JSON mappings, and a subsequent script converts those mappings into properly formatted aligned USFM.

What is needed to generate a JSON mapping for Hebrew-to-UST alignment?

To generate a JSON mapping for Hebrew-to-UST alignment, you need Hebrew source text in USFM format and an English UST draft. Optional hints can also be provided to help produce deterministic, validated alignments.

Does the alignment workflow support JSON-based mapping for downstream publication tools?

Yes, the alignment workflow supports JSON-based mapping for downstream publication tools. It outputs a JSON structure specifically designed to be compatible with downstream USFM tools for publication or quality assurance tasks.

What are the limitations when aligning superscriptions and split alignments in biblical text?

Aligning superscriptions and split alignments requires careful handling of radical restructuring. The system addresses these limitations by using meaning-based index mappings to ensure the JSON output accurately represents complex semantic relationships.