diff --git a/.gitignore b/.gitignore index 7abdeb3..e632053 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,9 @@ pnpm-debug.log* yarn-debug.log* yarn-error.log* +# workspace files +*.code-workspace + # others .env*.local .vercel diff --git a/NEW_DOCUMENTATION_SUMMARY.md b/NEW_DOCUMENTATION_SUMMARY.md deleted file mode 100644 index 35605e3..0000000 --- a/NEW_DOCUMENTATION_SUMMARY.md +++ /dev/null @@ -1,257 +0,0 @@ -# New Documentation Pages - Summary - -## Created Documentation - -I've created 3 comprehensive new documentation pages to fill the gaps identified in the codex-editor documentation: - -### 1. **Importing Source Files** πŸ“ -**Location:** `/docs/project-management/importing-files/` - -**Coverage:** -- Complete overview of Source vs Target imports -- All 15+ supported file formats with detailed descriptions -- Step-by-step workflows for each import type -- Import wizard usage -- Alignment algorithms (ID-based, sequential, timestamp-based) -- Preview & confirm features -- Troubleshooting section -- Best practices -- Comprehensive FAQ - -**Key Features Documented:** -- USFM, Paratext, eBible formats -- DOCX (standard + round-trip) -- Markdown -- VTT/SRT subtitles -- OBS (Open Bible Stories) -- InDesign (IDML) -- Smart Segmenter (40+ formats) -- CSV/TSV -- PDF (experimental) - ---- - -### 2. **Video & Audio Translation** πŸŽ₯ -**Location:** `/docs/translation/video-audio-translation/` - -**Coverage:** -- Complete subtitle translation workflows (VTT/SRT) -- Cell-by-cell audio playback system -- Audio file organization and naming conventions -- Recording workflows and best practices -- Timestamp management -- Complex subtitle mappings (1:1, 1:many, many:1, many:many) -- Dubbing project workflows -- Oral translation projects -- Detailed examples and use cases -- Troubleshooting guide - -**Key Features Documented:** -- Subtitle import/export cycle -- Audio file structure (`.project/attachments/`) -- Naming convention: `{BOOK}_{CCC}_{VVV}.{ext}` -- Supported audio formats (WAV, MP3, M4A, OGG) -- Integration with video players -- Quality guidelines -- Multi-take recording strategies - ---- - -### 3. **Advanced Export Options** πŸ“€ -**Location:** `/docs/translation/advanced-export-options/` - -**Coverage:** -- All export formats explained in detail -- Round-trip workflows (DOCX, IDML, OBS, Subtitles) -- Standard exports (Plain Text, HTML, USFM) -- Rebuild Export (intelligent format detection) -- Batch export capabilities -- Format comparison table -- Workflow examples for different project types -- Troubleshooting export issues -- Best practices - -**Key Features Documented:** -- DOCX Round-trip (export back to Word with formatting) -- IDML export (InDesign publishing) -- OBS Markdown export (stories with images) -- VTT/SRT subtitle export -- Biblica format -- Rebuild Export auto-detection -- Filename conventions -- Mixed format batch exports - ---- - -## Updates to Existing Documentation - -### Updated Files: - -1. **`/docs/project-management/meta.json`** - - Added "importing-files" to navigation - -2. **`/docs/translation/meta.json`** - - Added "video-audio-translation" - - Added "dictionary-reference-tools" - - Added "advanced-export-options" - -3. **`/docs/faq.mdx`** - - Updated "What file formats can I import?" with comprehensive list and link - - Updated "Can I use Codex with non-Bible content?" with links to new guides - - Updated "What export formats are available?" with complete list and link - -4. **`/docs/translation/exporting-project/index.mdx`** - - Added overview of advanced formats - - Added links to new comprehensive guide - - Added "Next Steps" section - ---- - -## Documentation Style & Features - -All new pages include: - -βœ… **Video placeholders** - Ready for Loom video integration (`PLACEHOLDER_VIDEO_ID`) -βœ… **Comprehensive coverage** - 5,000-10,000 words per page -βœ… **Step-by-step workflows** - Clear, actionable instructions -βœ… **Real-world examples** - Multiple use cases demonstrated -βœ… **Visual formatting** - Callouts, tables, code blocks, accordions -βœ… **Troubleshooting sections** - Common problems with solutions -βœ… **Best practices** - Expert guidance for each feature -βœ… **FAQ accordions** - 6-8 questions per page -βœ… **Cross-references** - Links to related documentation -βœ… **Next Steps** - Guide users to related content -βœ… **Discord community links** - Encourage user engagement - ---- - -## What's Now Documented That Wasn't Before - -### Major Feature Gaps Closed: - -1. **File Import System** - Was only briefly mentioned in FAQ, now has 10,000+ word comprehensive guide -2. **Video/Audio Translation** - Was completely undocumented, now has full workflow guide -3. **Export Formats** - Was limited to 3 formats, now documents 10+ formats with round-trip workflows -4. **Round-trip Workflows** - DOCX, IDML, and OBS round-trip capabilities were undocumented -5. **Subtitle Translation** - Complex feature that was invisible to users -6. **Audio Playback** - Sophisticated system with specific requirements, now fully documented - -### Features Still Not Documented (Lower Priority): - -- Dictionary Table (not frontend-facing or hidden) -- Search Passages view (may not be fully implemented) -- Comments sidebar (basic collaboration feature, may document later) -- AI Metrics/Edit Analysis (background feature) -- Words View (terminology management, may not be user-facing) -- Automated Testing view (developer feature) -- Source Editing Mode toggle (advanced feature) -- Cell Label Importer (mentioned but not detailed guide) -- Book Name Customization (mentioned but not detailed guide) -- Splash Screen details (internal/automatic) -- Update notification system (automatic/background) -- Progress Reporting command (background feature) - ---- - -## Recommendations for Video Recording - -### Priority Videos to Record: - -1. **Importing Source Files** (15-20 minutes) - - Show the import wizard - - Demonstrate Source vs Target import - - Import a DOCX file using round-trip importer - - Import subtitles - - Show preview & confirm for translation import - -2. **Video & Audio Translation** (10-15 minutes) - - Import a VTT file - - Translate some subtitles - - Export back to VTT - - Show audio playback feature with properly named files - - Demonstrate the naming convention - -3. **Advanced Export Options** (8-12 minutes) - - Show different export formats - - Demonstrate DOCX round-trip workflow - - Use Rebuild Export with mixed file types - - Open exported files in respective applications - -### Video Recording Tips: - -- **Show real workflows** - Import actual files, translate real content -- **Highlight the "why"** - Explain when to use each feature -- **Point out gotchas** - Mention common mistakes (like using wrong importer) -- **Show the results** - Open exported files in Word, VLC, etc. to prove it works -- **Keep it practical** - Focus on common use cases - ---- - -## Next Steps for Documentation Site - -1. βœ… **Pages Created** - All 4 major pages written -2. βœ… **Navigation Updated** - meta.json files updated -3. βœ… **Cross-references Added** - FAQ and related pages updated -4. ⏳ **Record Videos** - Replace `PLACEHOLDER_VIDEO_ID` with real Loom IDs -5. ⏳ **User Testing** - Have someone follow the guides and provide feedback -6. ⏳ **Screenshots** - Consider adding screenshots for complex UI elements -7. ⏳ **Search Optimization** - Ensure new pages are indexed properly - ---- - -## Impact Summary - -**Before:** -- ~15 documentation pages -- Major features undocumented -- Users discovering features by accident -- Limited export understanding -- No video/audio translation guidance - -**After:** -- 18 documentation pages (+3 comprehensive guides) -- All major features documented -- Clear pathways for different use cases -- Complete import/export documentation -- Professional media translation workflows - -**Lines of Documentation Added:** ~32,000 words across 3 pages - ---- - -## Files Modified - -### New Files: -- `/content/docs/project-management/importing-files/index.mdx` -- `/content/docs/translation/video-audio-translation/index.mdx` -- `/content/docs/translation/advanced-export-options/index.mdx` - -### Modified Files: -- `/content/docs/project-management/meta.json` -- `/content/docs/translation/meta.json` -- `/content/docs/faq.mdx` -- `/content/docs/translation/exporting-project/index.mdx` - ---- - -## Quality Assurance Checklist - -- [x] All pages follow existing documentation style -- [x] Video placeholders included -- [x] Cross-references to related pages -- [x] FAQ sections included -- [x] Troubleshooting sections included -- [x] Best practices included -- [x] Real-world examples included -- [x] Navigation updated -- [x] Existing pages updated with links -- [ ] Videos recorded (pending) -- [ ] User testing completed (pending) -- [ ] Screenshots added (optional) - ---- - -**Ready for review and video recording!** πŸŽ‰ - -All documentation is written in the same style as existing pages and ready for videos to be recorded and integrated. - diff --git a/content/docs/faq.mdx b/content/docs/faq.mdx index 8c02daf..ccdceb8 100644 --- a/content/docs/faq.mdx +++ b/content/docs/faq.mdx @@ -284,14 +284,13 @@ You'll remain logged in for up to one year after initial login, making it conven ### What export formats are available? -Codex Editor supports multiple export formats: - -- **Standard formats** β€” Plain text, HTML, USFM, and XLIFF -- **Round-trip Export** β€” Auto-detects original format (DOCX, USFM, OBS, TMS, CSV/TSV, IDML, Biblica) -- **Subtitles** β€” VTT/SRT with original timing preserved -- **Data export** β€” CSV/TSV with source, target, and metadata columns -- **Backtranslations** β€” CSV with source, translation, and backtranslation -- **Audio** β€” Per-cell audio attachments +Codex Editor supports multiple export formats at different stages of readiness: + +- **Stable** β€” Plain text and HTML +- **Beta** β€” USFM, XLIFF, Round-trip Export (auto-detects original format), and Subtitles (VTT/SRT) +- **Coming Soon** β€” Data export (CSV/TSV), Backtranslations (CSV), and Audio export + +Formats marked Beta are functional but may require manual review. Coming Soon formats are planned but not yet fully implemented. [See all export options β†’](/docs/translation/exporting-project) diff --git a/content/docs/getting-started/download-codex.mdx b/content/docs/getting-started/download-codex.mdx index d473a80..aec38ad 100644 --- a/content/docs/getting-started/download-codex.mdx +++ b/content/docs/getting-started/download-codex.mdx @@ -4,6 +4,31 @@ description: Download and install Codex Editor on macOS, Windows, and Linux --- Download Codex Editor to start your translation journey. The application is available for macOS, Windows, and Linux platforms, with specific builds optimized for different system architectures. +## System Requirements + +### Minimum Requirements +- **RAM**: 4GB (8GB recommended) +- **Storage**: 2GB free space for the application +- **Internet**: Required for initial setup and collaboration via our GitLab cloud service + +### Project Storage + +In addition to the application itself, you'll need disk space for your translation projects: + +- **Text-only projects**: Text and version history are lightweight β€” most projects stay well under 500MB. +- **Audio projects**: Audio recordings add up quickly depending on length and format. For reference: + - A **30-second clip** (e.g., a single verse or short paragraph): ~5MB uncompressed (WAV), under 1MB compressed (MP3) + - A **10-minute recording** (roughly the length of a typical YouTube video): ~100MB WAV, ~10MB MP3 + - A **30-minute recording** (a book chapter or short podcast episode): ~300MB WAV, ~30MB MP3 + - A **45-minute recording** (a TV episode): ~450MB WAV, ~45MB MP3 + + Audio storage scales with your project's scope and recording format. Compressed formats (MP3, OGG) use roughly one-tenth the space of uncompressed WAV. Plan your disk space accordingly based on how much audio your project will involve. + +### Supported Operating Systems +- **macOS**: 10.15 (Catalina) or later +- **Windows**: Windows 10 or later +- **Linux**: Most modern distributions (Ubuntu 20.04+, Fedora 36+, or equivalent) + ## Download Options Visit [codexeditor.app](https://codexeditor.app/) to access the download page with platform-specific options. @@ -29,7 +54,10 @@ Visit [codexeditor.app](https://codexeditor.app/) to access the download page wi -## macOS Installation +## Installation Instructions + + + ### Determining Your Mac Type @@ -45,7 +73,7 @@ Before downloading, you need to identify your Mac's processor type: - Check: Apple Menu β†’ About This Mac β†’ look for "Intel" processor - Or run in Terminal: `uname -m` (returns "x86_64") -### Download Steps for macOS +### Download Steps 1. Visit [codexeditor.app](https://codexeditor.app/) 2. Click the **macOS** button at the top of the page @@ -54,20 +82,21 @@ Before downloading, you need to identify your Mac's processor type: - **Intel** - for older Intel-based Macs 4. The download will begin automatically -### macOS Installation Process +### Installation Process 1. Once downloaded, open the `.dmg` file 2. Drag Codex Editor to your Applications folder -## Windows Installation + + -### Download Steps for Windows +### Download Steps 1. Visit [codexeditor.app](https://codexeditor.app/) 2. Click the **Windows** button at the top of the page 3. The download will start automatically (x64.exe file) -### Windows Installation Process +### Installation Process 1. Locate the downloaded `.exe` file (usually in Downloads folder) 2. Double-click to run the installer @@ -83,25 +112,25 @@ Windows may show security warnings because the application isn't code-signed: 2. **User Account Control**: Allow the installer to make changes 3. Follow the installation wizard prompts -**What "Unsigned" Means**: The application doesn't have a digital signature from a recognized certificate authority(aka Microsoft). Windows flags this as potentially risky, but it's safe to proceed. +**What "Unsigned" Means**: The application doesn't have a digital signature from a recognized certificate authority (aka Microsoft). Windows flags this as potentially risky, but it's safe to proceed. -## Linux Installation + + -### Determining Your Linux Architecture +### Determining Your Architecture Before downloading, identify your system architecture: ```bash -# Check your architecture uname -m ``` **Common Results:** - `x86_64` β†’ Choose **x64** -- `aarch64` β†’ Choose **arm64** +- `aarch64` β†’ Choose **arm64** - `armv7l` β†’ Choose **armhf** -### Download Steps for Linux +### Download Steps 1. Visit [codexeditor.app](https://codexeditor.app/) 2. Click the **Linux** button at the top of the page @@ -110,7 +139,7 @@ uname -m - **arm64** - For 64-bit ARM processors (like Raspberry Pi 4, Apple Silicon via emulation) - **armhf** - For 32-bit ARM processors (older Raspberry Pi models) -### Linux Installation Process +### Installation Process The exact installation method depends on the package format provided: @@ -148,17 +177,8 @@ Linux systems may require additional permissions: **What "Unsigned" Means**: The package isn't signed with a recognized GPG key or distributed through official repositories. This is common for third-party applications. -## System Requirements - -### Minimum Requirements -- **RAM**: 4GB (8GB recommended) -- **Storage**: 2GB free space -- **Internet**: Required for initial setup and cloud features - -### Supported Operating Systems -- **macOS**: 10.14 (Mojave) or later -- **Windows**: Windows 10 or later -- **Linux**: Most modern distributions + + ## Post-Installation Steps @@ -166,7 +186,7 @@ After successfully installing Codex Editor: 1. **Launch the Application**: Find and open Codex Editor 2. **Initial Setup**: [Creating your account](/docs/getting-started/initial-setup) -4. **Start Your Project**: [Create your first translation project](/docs/project-management/creating-project) +3. **Start Your Project**: [Create your first translation project](/docs/project-management/creating-project) --- @@ -209,4 +229,4 @@ If you encounter issues during download or installation: Once Codex Editor is installed and running: 1. [Complete the initial setup](/docs/getting-started/initial-setup) -3. [Start your first translation project](/docs/project-management/creating-project) \ No newline at end of file +2. [Start your first translation project](/docs/project-management/creating-project) \ No newline at end of file diff --git a/content/docs/index.mdx b/content/docs/index.mdx index cec1521..a32c282 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -87,7 +87,7 @@ Codex runs as a **desktop application** (Electron-based, like VS Code) on Window - Phrase-level notes and annotations ### Export & Integration -- Multiple export formats (plain text, HTML, USFM) +- Stable export to plain text and HTML, with additional formats (USFM, XLIFF, round-trip, subtitles) in beta - Integration with existing translation workflows - Project archiving and backup capabilities diff --git a/content/docs/project-management/importing-files.mdx b/content/docs/project-management/importing-files.mdx index 3c9137e..e8c0798 100644 --- a/content/docs/project-management/importing-files.mdx +++ b/content/docs/project-management/importing-files.mdx @@ -53,6 +53,10 @@ Use this when you have existing translations to bring into Codex: Importers are organized into two groups: **Essential** (general-purpose) and **Specialized** (format-specific and structured-content workflows). + +Some importers below are marked **Round-trip export supported**, meaning you can export back to the original format after translating. Round-trip export is currently in beta β€” see [Export Formats](/docs/translation/exporting-project#export-formats) for details. + + ### Essential Importers **Audio** diff --git a/content/docs/translation/exporting-project.mdx b/content/docs/translation/exporting-project.mdx index 6ae75f9..0a8198a 100644 --- a/content/docs/translation/exporting-project.mdx +++ b/content/docs/translation/exporting-project.mdx @@ -1,5 +1,5 @@ --- -title: Export Options +title: Exporting Projects description: Learn about all available export formats in Codex Editor and how to export your translation project --- @@ -22,7 +22,25 @@ You must set your source and target languages in Project Settings before the exp The formats available in Step 2 depend on which file group you selected in Step 1. Not all formats appear for every file type. -### Round-trip Export + +Formats marked **Beta** are functional but still being refined β€” output may require manual review. Formats marked **Coming Soon** are visible in the interface but not yet fully implemented. + + +### Standard Text Formats + +These are available for most file types: + +- **Generate Plaintext** β€” Plain text with minimal formatting. Universal compatibility. +- **Generate HTML** β€” Web pages with chapter navigation. + +### Scripture-Specific Formats `Beta` + +These appear only for USFM and eBible file groups: + +- **Generate USFM** β€” Export with full USFM markers (`\id`, `\c`, `\v`, etc.). Includes an option to skip USFM validation for faster export. +- **Generate XLIFF** β€” XML Localization Interchange File Format for professional translation workflows. + +### Round-trip Export `Beta` If your files were imported with a round-trip importer, the **Round-trip Export** option appears. This intelligently detects the original file format and exports back to it with your translations applied. @@ -42,7 +60,7 @@ Supported round-trip formats: **When in doubt, use Round-trip Export.** It automatically picks the right format based on how the file was originally imported. -### Subtitle Export +### Subtitle Export `Beta` For files imported with the Subtitles importer, three subtitle-specific options are available: @@ -52,21 +70,7 @@ For files imported with the Subtitles importer, three subtitle-specific options All subtitle exports preserve the original timestamps. -### Standard Text Formats - -These are available for most file types: - -- **Generate Plaintext** β€” Plain text with minimal formatting. Universal compatibility. -- **Generate XLIFF** β€” XML Localization Interchange File Format for professional translation workflows. - -### Scripture-Specific Formats - -These appear only for USFM and eBible file groups: - -- **Generate USFM** β€” Export with full USFM markers (`\id`, `\c`, `\v`, etc.). Includes an option to skip USFM validation for faster export. -- **Generate HTML** β€” Web pages with chapter navigation. - -### Data Export +### Data Export `Coming Soon` These are available for all file types and useful for analysis or quality assurance: @@ -74,7 +78,7 @@ These are available for all file types and useful for analysis or quality assura - **TSV** β€” Tab-separated values with the same columns as CSV - **Backtranslations (CSV)** β€” Exports backtranslations with ID, source text, translation, and backtranslation columns -### Audio Export +### Audio Export `Coming Soon` The **Audio** toggle at the top of Step 2 lets you export per-cell audio attachments alongside any text format. You can optionally embed timestamps in audio metadata (WAV, WebM, M4A). Audio can also be exported on its own without selecting a text format. diff --git a/content/docs/translation/video-audio-translation.mdx b/content/docs/translation/video-audio-translation.mdx index 834cfdf..8e04b33 100644 --- a/content/docs/translation/video-audio-translation.mdx +++ b/content/docs/translation/video-audio-translation.mdx @@ -61,7 +61,7 @@ Each subtitle becomes a cell with: **Timing Tip:** The timestamp metadata is preserved in each cell. You don't need to manually manage start/end timesβ€”Codex handles this automatically during export. -### Step 3: Export Translated Subtitles +### Step 3: Export Translated Subtitles `Beta` 1. Open **Project Settings** (sidebar menu) 2. Scroll to **Export Project** @@ -74,6 +74,10 @@ Your exported file will have: - Your translated text - Original subtitle format (VTT or SRT) + +Subtitle export is currently in beta β€” output may require manual review. See [Export Formats](/docs/translation/exporting-project#export-formats) for details on format availability. + + ### Subtitle Import Examples **Example 1: Simple 1-to-1 Mapping** @@ -251,7 +255,7 @@ Complete workflow for video dubbing: 3. **Record audio** for each cell using the built-in recorder or by importing files 4. **Review** using the video player and timeline editor in the editor 5. **Validate** recordings with your team using the audio validation workflow -6. **Export subtitles** for final video through Project Settings +6. **Export subtitles** for final video through Project Settings (subtitle export is in beta; audio export is coming soon) ### Oral Translation Projects @@ -262,7 +266,7 @@ For communities creating oral translations: 3. **Use Whisper transcription** to generate a text draft from recordings 4. **Review** the transcription against the recording 5. **Validate** with team members using the audio validation feature -6. **Export** your translation when complete +6. **Export** your translation when complete (text export is stable; audio export is coming soon) ### Audio Bible Recording @@ -273,7 +277,7 @@ For communities creating oral translations: 3. Use **Transcribe** to get a text draft if needed 4. Use **History** to compare takes and select the best one 5. Have team members **Validate** each verse -6. Export the final audio files +6. Export the final audio files (audio export is coming soon β€” see [export formats](/docs/translation/exporting-project#export-formats)) --- diff --git a/content/docs/troubleshooting.mdx b/content/docs/troubleshooting.mdx index 36f2203..efa0b87 100644 --- a/content/docs/troubleshooting.mdx +++ b/content/docs/troubleshooting.mdx @@ -34,6 +34,8 @@ If you already know the area you need, jump straight to the deeper guide: +Also check our [Frequently Asked Questions](/docs/faq) β€” your question may already be answered there. + ## Before You Escalate Use the guided flow above, then make sure you have: