unfoldingWord/uW-Tools-CollabLight logoDoor43 Developer Documentation

Getting Started

Developer Guides

Repository Formats

Migration & Conversion

Automation & MCP

Translation Words Resource Container to Scripture Burrito Migration Guide

Introduction

This guide provides specific instructions for migrating Translation Words Resource Containers to Scripture Burrito format. Translation Words repositories contain biblical term definitions in nested Markdown files that map excellently to Scripture Burrito's glossary capabilities.

Applicable Repository Types:

  • Translation Words: TW (Biblical term definitions and explanations)

Migration Overview

Why Migrate Translation Words Repositories

Benefits of Scripture Burrito for Translation Words:

  • Perfect Glossary Support: Scripture Burrito has dedicated glossary flavor type
  • Enhanced Organization: Better handling of nested directory structures
  • Improved Cross-Referencing: Better linking to Bible texts and other resources
  • Explicit Content Typing: Markdown files clearly identified with MIME types
  • Term Relationship Modeling: Enhanced support for term interconnections

Migration Complexity

Complexity Level: Low-Medium Data Loss: ❌ None (all RC data preservable and enhanced) Time Required: 2-3 hours for automated conversion Manual Review: Moderate (verify term organization and cross-references)

Pre-Migration Analysis

Step 1: Analyze Source Repository

Check Repository Characteristics:

  • Verify subject is "Translation Words"
  • Confirm container type is "dict"
  • Note absence of projects array (uses directory structure)
  • Examine nested directory organization (bible/kt/, bible/names/, bible/other/)

Expected File Structure:

  • manifest.yaml with dublin_core section
  • bible/ directory with three subdirectories
  • Markdown files for each term definition
  • LICENSE.md file

Step 2: Analyze Term Organization

Directory Categories:

  • bible/kt/: Key Terms (~100-200 theological concepts)
  • bible/names/: Proper Names (~200-400 people and places)
  • bible/other/: Other Terms (~100-300 general vocabulary)

Term File Analysis:

  • Each term has one .md file
  • Standard article structure with Definition, Translation Suggestions, Examples
  • Cross-references to Bible passages
  • Strong's numbers and transliteration data

Migration Steps

Step 1: Create Scripture Burrito Metadata

Base Metadata for Translation Words:

{
  "meta": {
    "format": "scripture burrito",
    "version": "0.3.0"
  },
  "identification": {
    "name": "unfoldingWord® Translation Words",
    "abbreviation": "TW",
    "description": "Biblical term definitions and explanations"
  },
  "languages": [
    {
      "tag": "en",
      "name": "English", 
      "direction": "ltr"
    }
  ],
  "type": {
    "flavorType": {
      "name": "glossary",
      "currentScope": {
        "glossaryEntries": ["god", "jesus", "abraham", "bread"]
      }
    }
  }
}

Step 2: Convert Directory Structure to Ingredients

For Each Term File in Nested Directories:

Create Ingredient Entry:

  • Key: Use full path including directory (e.g., "bible/kt/god.md")
  • mimeType: "text/markdown"
  • role: "glossary"
  • scope: Term-specific scope with category information

Example Ingredients:

"bible/kt/god.md": {
  "mimeType": "text/markdown",
  "role": "glossary",
  "scope": {
    "glossaryEntry": "god",
    "category": "keyTerm"
  },
  "description": "Definition of God"
},
"bible/names/abraham.md": {
  "mimeType": "text/markdown", 
  "role": "glossary",
  "scope": {
    "glossaryEntry": "abraham",
    "category": "properName"
  },
  "description": "Information about Abraham"
},
"bible/other/bread.md": {
  "mimeType": "text/markdown",
  "role": "glossary", 
  "scope": {
    "glossaryEntry": "bread",
    "category": "generalTerm"
  },
  "description": "Definition of bread"
}

Step 3: Handle Term Categories

Map RC Directory Structure to SB Categories:

  • bible/kt/ → "category": "keyTerm"
  • bible/names/ → "category": "properName"
  • bible/other/ → "category": "generalTerm"

Enhanced Scope with Categories:

"scope": {
  "glossaryEntry": "salvation",
  "category": "keyTerm",
  "strongsNumbers": ["G4991", "H3444"],
  "semanticDomain": "theology"
}

Step 4: Convert Dependencies and Relationships

RC Relations to SB Relationships:

  • Bible texts (ULT, UST) become "target" relationships
  • Translation Words Links becomes "related" relationship
  • Other support resources become "related" relationships

Example Relationships:

"relationships": [
  {
    "type": "target",
    "flavor": "textTranslation",
    "id": "en_ult",
    "description": "Target Bible text for term definitions"
  },
  {
    "type": "related",
    "flavor": "parascripturalWordAlignment",
    "id": "en_twl", 
    "description": "Word links to these definitions"
  }
]

Step 5: Enhance with Glossary-Specific Features

Add Glossary Metadata:

"type": {
  "flavorType": {
    "name": "glossary",
    "currentScope": {
      "glossaryEntries": [
        "god", "jesus", "salvation", "abraham", "moses", "bread", "temple"
      ]
    },
    "glossaryStructure": {
      "categories": ["keyTerm", "properName", "generalTerm"],
      "totalEntries": 650,
      "languages": ["en"]
    }
  }
}

Migration Examples

Example 1: Key Terms Migration

Source RC Structure:

en_tw/
├── manifest.yaml
└── bible/
    └── kt/
        ├── god.md
        ├── jesus.md
        └── salvation.md

Converted SB Structure:

en_tw_sb/
├── metadata.json
└── bible/
    └── kt/
        ├── god.md
        ├── jesus.md
        └── salvation.md

Key Changes:

  • manifest.yaml → metadata.json with glossary flavor
  • Same file structure preserved
  • Enhanced ingredient metadata for each term

Example 2: Complete Translation Words Migration

Enhanced SB Metadata:

{
  "type": {
    "flavorType": {
      "name": "glossary"
    }
  },
  "ingredients": {
    "bible/kt/god.md": {
      "mimeType": "text/markdown",
      "role": "glossary",
      "scope": {
        "glossaryEntry": "god",
        "category": "keyTerm",
        "strongsNumbers": ["H430", "G2316"]
      }
    },
    "bible/names/abraham.md": {
      "mimeType": "text/markdown",
      "role": "glossary", 
      "scope": {
        "glossaryEntry": "abraham",
        "category": "properName",
        "strongsNumbers": ["H85"]
      }
    },
    "bible/other/bread.md": {
      "mimeType": "text/markdown",
      "role": "glossary",
      "scope": {
        "glossaryEntry": "bread", 
        "category": "generalTerm",
        "strongsNumbers": ["H3899", "G740"]
      }
    }
  }
}

Migration Validation

Step 1: Validate Glossary Structure

Check Glossary Organization:

  • Verify all term files are properly referenced in ingredients
  • Confirm category assignments are correct
  • Check that glossary entries list is complete

Step 2: Validate Term Content

Content Integrity Checks:

  • Verify all Markdown files are accessible
  • Check that term definitions are preserved
  • Confirm Strong's numbers and cross-references are maintained

Step 3: Test Glossary Functionality

Functional Testing:

  • Load converted SB into glossary-aware tools
  • Test term lookup and cross-referencing
  • Verify category-based navigation works

Best Practices for Translation Words Migration

1. Preserve Term Hierarchy

  • Maintain three-category organization (kt, names, other)
  • Preserve term relationships within categories
  • Keep Strong's number associations

2. Enhance with SB Capabilities

  • Add semantic domain information to scope
  • Include term frequency data if available
  • Utilize relationship system for term interconnections

3. Optimize for Glossary Workflow

  • Organize ingredients for efficient term lookup
  • Enable category-based browsing
  • Support cross-reference navigation

4. Quality Assurance

  • Validate all term files are accessible
  • Verify category assignments are logical
  • Test glossary functionality with SB tools

Migration Benefits

Enhanced Capabilities in Scripture Burrito

Better Than RC:

  • Explicit Glossary Support: Dedicated glossary flavor vs generic dict type
  • Enhanced Term Metadata: Scope objects with category and Strong's info
  • Better Cross-Referencing: Relationship system vs simple relation array
  • Semantic Organization: Category and domain support vs directory structure only
  • Tool Ecosystem: Access to glossary-specific SB tools

Preserved RC Features

No Data Loss:

  • All term definitions preserved exactly
  • Directory structure maintained
  • Strong's numbers preserved
  • Cross-references maintained
  • Term relationships preserved

Common Migration Issues

Issue 1: Nested Directory Structure

Problem: Complex bible/category/term.md organization Solution: SB ingredients preserve exact directory structure

Issue 2: Term Cross-References

Problem: Terms reference each other and Bible passages Solution: SB relationship system provides better cross-reference modeling

Issue 3: Strong's Number Integration

Problem: Strong's numbers need to be preserved and enhanced Solution: SB scope objects can include Strong's numbers and semantic data

This migration guide is based on analysis of Translation Words Resource Containers and Scripture Burrito specification research, and should be used alongside the main RC to Scripture Burrito Conversion Guide.

Edit this page on GitHub
Overview