๐ A Powerful React Web Application for Creating and Managing Translation Word Lists (TWL)
Transform USFM content into high-quality TWL files with advanced collaboration and quality control features
๐ Quick Start โข ๐ Features โข ๐ ๏ธ Development โข ๐ Documentation
โจ Smart Generation: Automatically creates TWL entries from USFM content using advanced algorithms
๐ Interactive Table: Powerful search, filtering, and editing capabilities
๐ Scripture Viewer: Integrated biblical text analysis with word alignments
๐จ Modern UI: Clean, responsive Material-UI design
๐ Real-time Collaboration: Seamless integration with Door43 Content Service
๐พ Auto-save: Never lose your work with browser local storage
๐ Multi-language Support: Handles Hebrew, Greek, and English content
Choose Your Book ๐
- Select from the dropdown menu (e.g., "Genesis (gen)", "Matthew (mat)")
- Choose a branch from the DCS repository (defaults to 'master')
- Branch selection is used when fetching existing TWL files from DCS
Three Ways to Import ๐
- Click "Paste text" and the app will read your clipboard
- Paste TWL content directly into the text area
- Click "Import a saved TSV file" to upload a .tsv file from your computer
- Works with both standard 6-column TWL files and extended format files
- Click "Fetch en_twl/twl_BOOK.tsv" to download current TWL from DCS
- Uses selected branch to fetch the appropriate version
๐ Supported Formats:
- 6-column format: For merging with newly generated TWLs
- 8-12 column format: Extended format files load directly into table view
When you import a 6-column TWL file, a checkbox appears to control how the app merges the fetched content with newly generated TWLs:
Default Behavior (Checkbox Checked - Default):
- ๐ Ignore Fetched TWLs' Sort Order (recommended for first-time generation)
- The generated TWLs maintain their order (as created by the generation algorithm)
- Fetched TWLs that don't match generated ones are inserted based on their Bible reference position in the generated list
- Creates a completely new sort order based on the generation algorithm
- After merging: Rows are automatically reordered within each verse to match their position in the ULT Bible text
- ๐ก Use this when: Generating TWLs for a book that has never had automated TWLs generated before
Alternative Behavior (Checkbox Unchecked):
- โ Keep Fetched TWLs' Sort Order (recommended for updates)
- The fetched/existing TWLs maintain their original order from DCS
- New generated TWLs are inserted before or after matching existing TWLs based on context
- Preserves the structure of previously generated lists
- ๐ก Use this when: Updating a recently generated list with new changes or improvements
๐ฏ Key Difference:
| Scenario | Use Setting |
|---|---|
| First-time generation for a book | โ Check "Ignore fetched order" (default) |
| Updating an existing TWL with new changes | โ Uncheck |
| Re-generating from scratch | โ Check "Ignore fetched order" (default) |
| Preserving existing sort preferences | โ Uncheck |
Generate TWLs ๐ ๏ธ: Creates new TWL entries automatically from USFM using the twl-generator library
Load into Table View ๐: If you imported extended format, loads directly without generation
- ๐ Your work is automatically saved to browser's local storage
- โฐ Close browser and return later - your work is preserved!
- ๐ Works across browser sessions until you clear browser data
Search Functionality ๐ต๏ธโโ๏ธ
The search feature allows you to find content across multiple columns:
๐ฏ Exact Match Columns (case-insensitive):
- ๐ Reference: Search for exact Bible references (e.g., "1:1", "gen 1:1")
๐ฏ Exact Match Columns (case-sensitive):
- ๐ Merge Status: Search for exact status values ("OLD", "NEW", "MERGED")
๐ Partial Match Columns (case-insensitive):
- ๐ OrigWords: Search within original language words
- ๐ TWLink: Search within Translation Word links
- ๐ฌ GLQuote: Search within Gateway Language quotes
- โ Disambiguation: Search within disambiguation options
- ๐ Variant of: Search within variant relationships
- ๐ ID: Search within row IDs
- ๐ท๏ธ Tags: Search within tag values
๐ก Search Tips:
- Search across all available columns simultaneously
- Results shown if search term matches ANY column
- Use exact matches for precise filtering
- Use partial matches for broader searches
๐๏ธ Other Filters:
- โ Disambiguation Filter: Show only rows with disambiguation options
- ๐ Variant Filter: Show entries that are variants of other words
- ๐ Merge Status Filter:
- โ Merged: Show rows where existing content was merged with generated content
- โ Unmerged: Show rows that are either from existing content only or newly generated
- ๏ฟฝ๏ธ Deleted Rows Filter:
- ๐๏ธ Show Deleted Rows: Show all rows including deleted ones
- ๐ฏ Only Show Deleted Rows: Show only deleted rows
- ๏ฟฝ๐ Invalid RC Links: Show entries with problematic Translation Word links
๐๏ธ 1. Delete Single Row (Smart Persistent Deletion)
- Click the trash icon (๐๏ธ) to mark a row as deleted
- ๐ง Smart Memory: Your deletions are remembered across sessions and future generations
- ๐ Persistent Behavior:
- When you delete a row, it will be automatically filtered out in all future TWL generations for this book
- When you restore (undelete) a row, it will always appear in future generations
- Deleted rows show with a "DELETED" prefix and are visually grayed out
- ๐ซ Protection: MERGED rows (existing TSV content) cannot be deleted to preserve existing work
- โถ Restore: Click the delete icon again on a DELETED row to restore it
โ ๏ธ Note: Only affects NEW and OLD rows; MERGED rows are protected from deletion
๐ 2. Unlink Word
- Click the unlink icon (๐) to remove all instances of that word
- Removes ALL rows with the same OrigWords and TWLink combination
- Also prevents this word from appearing in future TWL generations
โ ๏ธ Global Impact: Affects all users of the app - use carefully!
โ๏ธ 3. Edit TWLink
- Click anywhere in the TWLink column (except on the link text itself) to quickly enter edit mode
- Click directly on the link text to open the Translation Word article modal
- Allows you to correct or change which Translation Word article this entry links to
- The TWLink column shows a subtle blue background on hover when clickable for editing
๐ 4. View Scripture Context
- Click the book icon (๐) to open the Scripture Viewer
- Shows the aligned original Hebrew/Greek words with English translations
- Displays lexicon data with Strong's numbers, lemmas, and morphology
- Includes context verses (the target verse plus surrounding verses)
- Words with lexicon data are highlighted and clickable for detailed information
๐จ 5. Translation Word Articles
- ๐ Hover over TWLink or Disambiguation links: See a tooltip with the article's title/terms
- ๐ฑ๏ธ Click TWLink: Opens the full Translation Word article in a modal popup
- โ๏ธ View on DCS: From the article modal, click "View on DCS" to open the article on the DCS website
The app features an advanced deletion system that remembers your choices across sessions and generations:
- Delete a Row: Marks the row with "DELETED" prefix and stores this decision in the cloud
- Future Generations: Deleted rows are automatically filtered out when generating new TWLs
- Restore Feature: Click delete again on a DELETED row to restore it permanently
- Cloud Sync: Your deletion preferences sync across devices and persist forever
- โ Can Delete: NEW rows (newly generated content)
- โ Can Delete: OLD rows (existing content that wasn't merged)
- ๐ซ Cannot Delete: MERGED rows (existing TSV content that was successfully merged)
- Remove Errors: Delete incorrectly generated entries that you never want to see again
- Clean Up: Remove unwanted translation word associations permanently
- Quality Control: Hide problematic entries while preserving good existing content
- Regular Rows: Normal appearance
- DELETED Rows: Grayed out with red text and "DELETED" prefix in Reference column
- MERGED Rows: Cannot be deleted (delete button disabled for these rows)
โฌ๏ธ 6. Move Row Up/Down
- โฌ๏ธ Up Arrow: Move row up within the same reference (verse)
- โฌ๏ธ Down Arrow: Move row down within the same reference (verse)
- ๐ Same Reference Only: Can only move rows within the same Bible reference
- ๐ซ Hidden States:
- Arrow buttons are completely hidden when search/filter is active
- Up arrow disabled if it's the first row of a reference
- Down arrow disabled if it's the last row of a reference
- โถ Undo Support: Moving rows enables the Undo button to reverse the action
- ๐ Cross-Page Movement: If moving causes a row to move to another page, the table updates accordingly
โ 6. Handle Disambiguations
- ๐ Hover over disambiguation links: See the terms for each alternative word definition
- ๐ฑ๏ธ Click disambiguation links: Switch between alternative word definitions
- โ๏ธ Clear disambiguations: Click the checkbox in the Disambiguation column to remove all disambiguation options
- ๐ Switch to "Raw Text" mode to edit the TSV content directly
- ๐พ Click "Save & Return to Table View" when finished
- ๐ ๏ธ Useful for bulk edits or complex changes
- Single-level undo: Reverses your most recent change
- Available after row deletions, disambiguations, and other table modifications
- Only remembers one step back
Click "Manage Unlinked Words" ๐ง to access the global unlinked words system:
- ๐ View all unlinked words: See what words have been unlinked across all books
- โ Remove words from unlinked list: Re-enable words that were previously unlinked
- ๐ Global impact: Changes here affect all users of the app
- ๐ฏ Purpose: Prevents problematic or incorrect word links from appearing in future TWL generations
- Click "Save TWLs to File" ๐ฅ to download your complete work
- Creates a .tsv file with all columns (8-12 columns depending on content)
- Others can import this file into the app to continue your work
- Useful for collaboration and backup
- Send your exported file to other translators or editors
- They can import it using the "Import a saved TSV file" option
- Preserves all your edits, disambiguations, and merge status
When your TWL is complete and reviewed โ
- ๐ฑ๏ธ Click "Commit to DCS"
- ๐ค Enter your name and email address
- ๐ฌ Add an optional commit message
- ๐ค Click "Commit & Create PR"
- ๐ Only the first 6 columns (standard TWL format) are uploaded to DCS
- ๐ฟ A new branch is created with your changes
- ๐ A Pull Request is automatically opened for review
- ๐ Extended columns (Disambiguation, etc.) are not included in DCS
- โ All disambiguation options have been reviewed and selected
- ๐ Variant word relationships are correct
- ๐ Unmerged rows have been reviewed (decide if they should stay or be removed)
- ๐ Invalid RC links have been checked using the filter
Here's the recommended step-by-step process ๐บ๏ธ
- ๐ Select your target Bible book
- ๐ฟ Choose appropriate branch (if fetching from DCS)
- ๐ฅ Import existing TWL content (if available) using paste, upload, or fetch
โ ๏ธ Important Merge Strategy Decision: After importing, you'll see a checkbox to "Ignore fetched TWLs' sort order"- First-time generation? (no automated TWLs exist yet) โ โ Check the box
- Updating recent changes? (has automated TWLs) โ โ Leave unchecked (default)
- โก Generate new TWLs or load extended format content
- ๐ Review the generated content in table view
- ๐ Use the Scripture Viewer to verify word alignments and context:
- Click the book icon (๐) for any row to see the biblical text with word alignments
- Verify that OrigWords and GLQuote match correctly in context
- Check lexicon data for accuracy of Strong's numbers and lemmas
- ๐๏ธ Use filters to focus on specific issues:
- Start with "Unmerged" to review new/old content
- Check "Invalid RC Links" for broken references
- Review "Disambiguation" entries for multiple word options
- Check "Variant of" entries to verify any irregular forms of the article term used in the scripture
- โ๏ธ Make necessary edits:
- Delete incorrect rows (single row deletion)
- Unlink problematic words (affects all instances globally)
- Edit TWLinks for better accuracy
- Select appropriate disambiguation options using hover tooltips for guidance
- โ Handle disambiguation options:
- Hover over disambiguation links to preview terms for each option
- Click through disambiguation links to select the best option
- Clear disambiguations that aren't needed
- ๐จ Verify Translation Word articles:
- Hover over TWLinks to quickly check article terms
- Click TWLinks to read full articles and ensure they match the biblical context
- Use the Scripture Viewer to confirm word alignments make sense
- ๐ Review variant relationships using the variant filter
- ๐ Check merge status - ensure merged content looks correct
- ๐ Use the search function to find and fix specific issues
- ๐พ Save your work to file for backup and collaboration
- ๐ Final review - go through filters one more time
- ๐ Commit to DCS when completely satisfied with the results
- ๐ค Share the Pull Request link with reviewers if needed
The Scripture Viewer provides advanced biblical text analysis ๐ฌ
- ๐ฑ๏ธ Click the book icon (๐) in any table row to open the Scripture Viewer for that specific verse
- ๐ Multi-language Display: Shows original Hebrew/Greek text alongside English translations (ULT and UST)
- ๐ Word Alignment: Visual highlighting shows how original language words align with English translations
- ๐ Lexicon Integration: Click on any word to see detailed lexical information:
- Strong's numbers and lemmas
- Morphological analysis (grammatical information)
- English glosses and meanings
- ๐ Context Verses: Displays the target verse plus several verses before and after for better understanding
- ๐ฏ Interactive Highlighting: Words matching your TWL entry are automatically highlighted
- โก Punctuation Handling: Smart matching works even when words have punctuation (commas, periods, etc.)
- ๐ฎ๐ฑ๐ฌ๐ท Original language words (Hebrew/Greek) show lexical data when clicked
- ๐บ๐ธ English words show alignment information linking back to the original language
- โจ Highlighting shows the specific words mentioned in your TWL entry
- ๐ Supports complex quotes with multiple word parts separated by "&"
Seamless integration with Translation Word articles ๐
- ๐ TWLink Column: Hover over any Translation Word link to see the article's main terms
- โ Disambiguation Links: Hover over disambiguation options to preview their specific terms
- โก Dynamic Loading: Tooltips are loaded dynamically from the Translation Word articles
- ๐ Click TWLink: Opens the full Translation Word article in an elegant modal popup
- ๐ Formatted Content: Articles are displayed with proper markdown formatting (headings, lists, links, etc.)
- ๐ Scrollable Content: Long articles have scrollbars for easy reading
- โ๏ธ DCS Integration: Click "View on DCS" to open the article on the Door43 Content Service website
- โ Easy Navigation: Close with the X button to return to your work
- ๐ Reference Links: Click any Bible reference to open Translation Notes in a new window
- ๐ฌ Long Text Tooltips: Hover over long content to see full details in a tooltip
- ๐๏ธ Column Visibility: Control which columns are displayed
- โ Automatic Validation: The app checks TWL format and shows validation errors
- ๐ Browser Compatibility: Works in modern web browsers with localStorage support
- ๐ฑ Responsive Design: Works on desktop and tablet devices
Common Issues & Solutions ๐ ๏ธ
- ๐พ Lost Work: Check if your browser's localStorage was cleared
- ๐ฅ Import Errors: Ensure your TSV file has the correct number of columns and headers
- โก Generation Fails: Verify the book selection and try again
- โ๏ธ DCS Commit Issues: Check your internet connection and credentials
- Node.js (v16 or higher) ๐ข
- pnpm package manager ๐ฆ
-
๐ฅ Clone the repository
git clone https://github.com/unfoldingWord/tsv7-twl-creation-app.git cd tsv7-twl-creation-app -
๐ฆ Install dependencies
pnpm install
-
โก Start development server
pnpm run dev
-
๐ Open in browser Navigate to
http://localhost:5173/
| Command | Description |
|---|---|
pnpm run dev |
๐ Start development server with hot reload |
pnpm run build |
๐ฆ Create production build |
pnpm run preview |
๐ Preview production build locally |
pnpm run lint |
๐ Run ESLint for code quality checks |
This application has been refactored into a modular, maintainable architecture ๐๏ธ
- ๐งฉ Modular structure with separated concerns
- ๐ฃ Custom React hooks for state management
- ๐ Reusable components and utility functions
- ๐ง Service layer for API calls and complex processing
- ๐ Comprehensive documentation and JSDoc comments
๐ ARCHITECTURE.md - Complete architecture documentation
Guidelines for Contributors ๐ฅ
- ๐ Read the ARCHITECTURE.md to understand the codebase structure
- ๐ Follow the established patterns for new features
- ๐ Add appropriate documentation and comments
- ๐งช Test changes thoroughly before submitting PRs
- โ๏ธ React 18 with Material-UI components
- โก Vite for fast development and building
- ๐ฃ Custom hooks with React's built-in state
- ๐ twl-generator for TWL generation from USFM
- ๐ฌ tsv-quote-converters for quote processing
- โ๏ธ Door43 Content Service (DCS) for content fetching
- ๐ Netlify-ready with build configurations
๐ This tool streamlines the Translation Word List creation process while maintaining compatibility with the Door43 translation workflow.
Made with โค๏ธ by the unfoldingWord team