unfoldingWord/uW-Tools-CollabLight logoDoor43 Developer Documentation

Getting Started

Developer Guides

Repository Formats

Migration & Conversion

Automation & MCP

Translation Academy Resource Container to Scripture Burrito Migration Guide

Introduction

This guide provides specific instructions for migrating Translation Academy Resource Containers to Scripture Burrito format. Translation Academy repositories contain training materials in nested Markdown files that map well to Scripture Burrito's peripheral resource capabilities.

Applicable Repository Types:

  • Translation Academy: TA (Translation methodology and training materials)

Migration Overview

Why Migrate Translation Academy Repositories

Benefits of Scripture Burrito for Translation Academy:

  • Dedicated Peripheral Support: Scripture Burrito has peripheral flavor designed for training materials
  • Enhanced Article Organization: Better handling of multi-file article structure
  • Improved Cross-Referencing: Better relationship modeling to other resources
  • Explicit Content Structure: Clear identification of article components
  • Training Workflow Support: Better support for systematic training progression

Migration Complexity

Complexity Level: Medium Data Loss: ❌ None (all RC data preservable with enhancement) Time Required: 3-4 hours for automated conversion Manual Review: Significant (verify article structure and cross-references)

Pre-Migration Analysis

Step 1: Analyze Source Repository

Check Repository Characteristics:

  • Verify subject is "Translation Academy"
  • Confirm container type is "man"
  • Note absence of projects array (uses directory structure)
  • Examine nested directory organization (translate/, checking/, intro/)

Expected File Structure:

  • manifest.yaml with dublin_core section
  • Multiple category directories
  • Three-file article structure (title.md, sub-title.md, 01.md)
  • LICENSE.md file

Step 2: Analyze Article Structure

Article Organization:

  • translate/: Translation methodology topics (~50-100 articles)
  • checking/: Quality assurance topics (~10-20 articles)
  • intro/: Introduction and overview topics (~5-10 articles)

Article File Structure:

  • title.md: Short article title
  • sub-title.md: Descriptive subtitle or question
  • 01.md: Complete article content

Migration Steps

Step 1: Create Scripture Burrito Metadata

Base Metadata for Translation Academy:

{
  "meta": {
    "format": "scripture burrito",
    "version": "0.3.0"
  },
  "identification": {
    "name": "unfoldingWord® Translation Academy",
    "abbreviation": "TA",
    "description": "Translation methodology and training materials"
  },
  "languages": [
    {
      "tag": "en",
      "name": "English",
      "direction": "ltr"
    }
  ],
  "type": {
    "flavorType": {
      "name": "peripheralResource",
      "currentScope": {
        "trainingTopics": ["figs-metaphor", "translate-names", "grammar-connect"]
      }
    }
  }
}

Step 2: Convert Article Structure to Ingredients

For Each Article Topic:

Create Ingredient for Complete Article:

  • Key: Use topic path (e.g., "translate/figs-metaphor/article.md")
  • mimeType: "text/markdown"
  • role: "guide"
  • scope: Topic-specific scope with category information

Combine Three Files into One:

  • Merge title.md + sub-title.md + 01.md into single article
  • Create unified Markdown structure
  • Preserve all content and formatting

Example Article Combination:

# Metaphor
## What is metaphor and how do I translate it?

{Content from 01.md}

Example Ingredient:

"translate/figs-metaphor/article.md": {
  "mimeType": "text/markdown",
  "role": "guide",
  "scope": {
    "trainingTopic": "figs-metaphor",
    "category": "translation",
    "difficulty": "intermediate"
  },
  "description": "How to translate metaphors"
}

Step 3: Handle Category Organization

Map RC Directory Structure to SB Categories:

  • translate/ → "category": "translation"
  • checking/ → "category": "checking"
  • intro/ → "category": "introduction"

Enhanced Scope with Training Metadata:

"scope": {
  "trainingTopic": "figs-metaphor",
  "category": "translation",
  "subcategory": "figures-of-speech",
  "difficulty": "intermediate",
  "prerequisites": ["translate-unknown"],
  "relatedTopics": ["figs-simile", "figs-hyperbole"]
}

Step 4: Convert Dependencies and Relationships

RC Relations to SB Relationships:

  • Translation Notes (which reference TA) become "target" relationships
  • Bible texts become "related" relationships
  • Other training resources become "related" relationships

Example Relationships:

"relationships": [
  {
    "type": "target",
    "flavor": "parascripturalWordAlignment",
    "id": "en_tn",
    "description": "Translation Notes reference these training articles"
  },
  {
    "type": "related",
    "flavor": "textTranslation",
    "id": "en_ult",
    "description": "Bible text used in training examples"
  }
]

Step 5: Enhance with Training-Specific Features

Add Training Progression Metadata:

"type": {
  "flavorType": {
    "name": "peripheralResource",
    "trainingStructure": {
      "categories": ["translation", "checking", "introduction"],
      "totalTopics": 85,
      "difficultyLevels": ["beginner", "intermediate", "advanced"],
      "learningPath": [
        "intro/translation-guidelines",
        "translate/translate-unknown", 
        "translate/figs-metaphor"
      ]
    }
  }
}

Migration Examples

Example 1: Translation Methodology Article

Source RC Structure:

en_ta/
└── translate/
    └── figs-metaphor/
        ├── title.md          # "Metaphor"
        ├── sub-title.md      # "What is metaphor..."
        └── 01.md             # Complete content

Converted SB Structure:

en_ta_sb/
├── metadata.json
└── translate/
    └── figs-metaphor/
        └── article.md        # Combined content

Combined Article Content:

# Metaphor
## What is metaphor and how do I translate it?

### Description
A metaphor is a figure of speech...

### Examples From the Bible
> Listen to this word, you cows of Bashan (Amos 4:1a ULT)

### Translation Strategies
1. Use a simile that would be understood...

Example 2: Complete Category Migration

Category: translate/ (Translation Methodology)

SB Ingredient Organization:

"ingredients": {
  "translate/figs-metaphor/article.md": {
    "mimeType": "text/markdown",
    "role": "guide",
    "scope": {
      "trainingTopic": "figs-metaphor",
      "category": "translation",
      "subcategory": "figures-of-speech"
    }
  },
  "translate/translate-names/article.md": {
    "mimeType": "text/markdown",
    "role": "guide", 
    "scope": {
      "trainingTopic": "translate-names",
      "category": "translation",
      "subcategory": "cultural-concepts"
    }
  }
}

Migration Validation

Step 1: Validate Article Assembly

Check Article Combination:

  • Verify title, subtitle, and content are properly merged
  • Confirm markdown structure is preserved
  • Check that all sections are included

Step 2: Validate Training Organization

Organization Checks:

  • Verify all categories are properly represented
  • Confirm topic relationships are maintained
  • Check that training progression is logical

Step 3: Test Training Workflow

Functional Testing:

  • Load converted SB into training-aware tools
  • Test article navigation and cross-referencing
  • Verify category-based organization works

Best Practices for Translation Academy Migration

1. Preserve Training Structure

  • Maintain category-based organization
  • Preserve article relationships and cross-references
  • Keep training progression logical

2. Enhance with SB Capabilities

  • Add difficulty levels and prerequisites to scope
  • Include semantic categorization
  • Utilize relationship system for better cross-referencing

3. Optimize for Training Workflow

  • Organize ingredients for systematic learning
  • Enable topic-based navigation
  • Support progress tracking capabilities

4. Quality Assurance

  • Validate all articles are properly combined
  • Verify cross-references are maintained
  • Test training workflow functionality

Migration Benefits

Enhanced Capabilities in Scripture Burrito

Better Than RC:

  • Unified Article Structure: Combined articles vs three-file system
  • Enhanced Metadata: Rich scope information vs directory structure only
  • Better Cross-Referencing: Relationship system vs simple relation array
  • Training Progression: Explicit learning paths vs implicit organization
  • Tool Ecosystem: Access to peripheral resource tools

Preserved RC Features

No Data Loss:

  • All training content preserved
  • Article structure maintained
  • Cross-references preserved
  • Category organization maintained
  • Training methodology preserved

Common Migration Issues

Issue 1: Three-File Article Structure

Problem: Each topic split across title.md, sub-title.md, and 01.md Solution: SB allows unified article structure - combine files into single ingredient

Issue 2: Complex Cross-References

Problem: Articles reference each other extensively Solution: SB relationship system provides better cross-reference modeling

Issue 3: Training Progression

Problem: Learning path implicit in RC directory structure Solution: SB scope can include explicit prerequisite and progression information

This migration guide is based on analysis of Translation Academy 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