AgentSkillsCN

vref-to-usfm

将 VREF 对齐的文本文件（共 41,899 行）转换为 SFM/USFM 文件，并添加适当的标记，以便与 Paratext 等圣经翻译软件兼容。在将经文对齐的纯文本重新转换为标准 USFM 格式，同时保留 \id、\c、\v 等标记时，此方案可提供高效支持。

SKILL.md
--- frontmatter
name: vref-to-usfm
description: Convert VREF-aligned text files (41,899 lines) into SFM/USFM files with proper markers for use with Bible translation software like Paratext. Use when transforming verse-aligned plain text back into standard USFM format with \id, \c, and \v markers.

vref-to-usfm

Convert VREF-aligned text files (41,899 lines) into SFM/USFM files with proper markers.

Overview

This skill converts verse-aligned plain text files into Standard Format Markers (SFM/USFM) files suitable for use with Bible translation software like Paratext.

Input Format

  • •VREF-aligned text file: one verse per line (41,899 lines total)
  • •Empty lines indicate missing/untranslated verses
  • •<range> markers indicate verse ranges (text is on the previous verse)

Output Format

SFM files with proper markers:

code
\id GEN
\c 1
\v 1 In the beginning God created the heavens and the earth.
\v 2 And the earth was without form...
\c 2
\v 1 Thus the heavens and the earth were finished...

Usage

The script is located in the scripts/ subdirectory of this skill. After installing the skill, you can run it with Python.

Convert with project ID (recommended)

bash
python ~/.claude/skills/vref-to-usfm/scripts/vref_to_usfm.py \
    input.txt \
    --output-dir ./output \
    --project-id MalBT

This creates files like ./output/MalBT/01GENMalBT.SFM, ./output/MalBT/02EXOMalBT.SFM, etc.

Convert all books (without project ID)

bash
python ~/.claude/skills/vref-to-usfm/scripts/vref_to_usfm.py \
    input.txt \
    --output-dir ./output

Convert a single book

bash
python ~/.claude/skills/vref-to-usfm/scripts/vref_to_usfm.py \
    input.txt \
    --book GEN \
    --output-dir ./output \
    --project-id MalBT

Use a custom vref.txt (different versification)

bash
python ~/.claude/skills/vref-to-usfm/scripts/vref_to_usfm.py \
    input.txt \
    --vref /path/to/custom/vref.txt \
    --output-dir ./output \
    --project-id MalBT

Options

OptionDescriptionDefault
inputPath to VREF-aligned text file(required)
--vrefPath to vref.txt reference filevref.txt in skill directory
--output-dirOutput directory for SFM files(required)
--bookConvert only this book (e.g., GEN, MAT)All books
--project-idProject ID for directory and filenamesNone

Output Files

With --project-id

Files are placed in a subdirectory named after the project ID, with filenames in the format <booknum><bookcode><projectid>.SFM:

  • •MalBT/01GENMalBT.SFM, MalBT/02EXOMalBT.SFM, ... (Old Testament)
  • •MalBT/40MATMalBT.SFM, MalBT/41MRKMalBT.SFM, ... (New Testament)

Without --project-id

Files are named by book code with .sfm extension:

  • •GEN.sfm, EXO.sfm, LEV.sfm, ...
  • •MAT.sfm, MRK.sfm, LUK.sfm, ...

Handling Special Cases

  • •Empty lines: Verse is skipped (not included in output)
  • •<range> markers: Creates verse ranges in output (e.g., \v 1-2 text when v1 has text and v2 is <range>)
  • •Chapter boundaries: New \c marker inserted automatically
  • •Book boundaries: New file created with \id marker