Importing Files

Codex Editor supports importing a wide variety of file formats for translation projects. Whether you're working with structured texts, documents, subtitles, or audio, the import wizard walks you through the process and automatically processes your files.

Understanding Source vs Target Import

Before importing, it's important to understand the two types of imports:

Source Import - Import original content that you want to translate

• Creates a new source file (read-only reference)
• Automatically creates a blank target file for your translation
• Use this for: source texts, documents you're translating, video subtitles, audio

Target Import - Import existing translations for source files already in your project

• Matches translated content to existing source files
• Populates your target notebook with translations
• Use this for: partially completed translations, importing work from other tools

Opening the Import Interface

1. Click the Compass icon in the sidebar to open Navigation
2. Click "Add Files" button
3. The import wizard will guide you through the process

Choosing Your Import Type

Option 1: Import New Source Files

Use this when you're starting fresh or adding new content to translate:

1. Select "Import Your Content" in the wizard
2. Browse available importers (see supported formats below)
3. Upload your file(s)
4. Codex creates both source and target notebooks automatically

Option 2: Import Translations

Use this when you have existing translations to bring into Codex:

1. Select "Add Your Translation" in the wizard
2. Choose which source file this translation belongs to
3. Select the appropriate importer
4. The system aligns your translation with the source content

Supported File Formats

Importers are organized into two groups: Essential (general-purpose) and Specialized (format-specific and structured-content workflows).

Essential Importers

Audio

• Supports .mp3, .wav, .m4a, .aac, .ogg, .webm, .flac
• Backend processing supports large files
• Use for: Audio translation, recording-based projects

Markdown

• GitHub Flavored Markdown (.md, .markdown, .mdown, .mkd)
• Image extraction and formatting preservation
• Use for: Documentation translation, blog posts, articles

Subtitles

• WebVTT (.vtt) and SubRip (.srt) formats
• Timestamp-based cell alignment for media synchronization
• Use for: Video dubbing, subtitle translation

TMS Files

• Translation memory and localization files: .tmx, .xliff, .xlf
• Round-trip export supported
• Use for: CAT tool workflows, localization projects, translation memory exchange

Word Documents

• Microsoft Word (.docx) with full structure preservation
• Round-trip export supported — preserves formatting for export back to Word
• Use for: Document translation, literature projects

InDesign Files

• Adobe InDesign Markup (.idml)
• Loss-free round-trip editing
• Round-trip export supported
• Use for: Publishing and layout projects

Specialized Importers

USFM New

• Unified Standard Format Markers (.usfm, .sfm)
• Headers are placed in chapter 1; target imports import verse content only
• Round-trip export supported
• Use for: Translation projects, Paratext exports

Paratext Projects

• Import complete Paratext projects (.zip or .ptx archive)
• Processes .SFM files and reads project settings and book names
• Use for: Existing Paratext translation work

eBible Download

• Download translations directly from eBible.org
• Access to hundreds of open-license translations
• Includes popular versions (BBE, WEB, ASV, KJV) and original language texts
• Optionally import as a translation only (to populate an existing target project)
• Use for: Source text acquisition

Macula Bible

• Hebrew Old Testament and Greek New Testament with linguistic annotations
• Downloaded directly within Codex
• Use for: Original language study, interlinear translation projects

Bible Stories

• Open Bible Stories (OBS) format (.md, .zip)
• Supports single files, ZIP archives
• Preserves images and story structure
• Round-trip export supported
• Use for: Bible story translation projects

Biblica Study Notes

• Biblica IDML importer with Study Bible notes
• Round-trip export supported
• Use for: Study translation projects

Bible Spreadsheet with Audio Data

• CSV and TSV files with verse-by-verse content and audio URL columns
• Round-trip export supported
• Use for: Spreadsheet-based translation workflows with associated audio

Import Workflow Examples

Example 1: Importing a Structured Text File (USFM)

1. Open Navigation → Add Files
2. Select "Import Your Content"
3. Choose "USFM New" importer
4. Upload your .usfm file (e.g., 01-GEN.usfm)
5. Codex creates:
   • GEN.source — Source text (read-only)
   • GEN.codex — Your translation workspace

Example 2: Downloading Source Text from the Cloud

You can download open-license source texts directly within Codex:

1. Open Navigation → Add Files
2. Select "Import Your Content"
3. Choose "eBible Download" importer
4. Search for your language or specific text version (e.g., "WEB", "Greek")
5. Click Download to fetch the text
   • Optionally check "Import as Translation Only" to populate an existing target project
6. Monitor progress and confirm once complete

Example 3: Importing Video Subtitles

1. Open Navigation → Add Files
2. Select "Import Your Content"
3. Choose "Subtitles" importer
4. Upload your subtitle file (e.g., video.vtt)
5. Codex creates timestamped cells for each subtitle cue
6. Translate each cell
7. Export back to VTT/SRT when complete

Example 4: Importing a Word Document for Translation

1. Open Navigation → Add Files
2. Select "Import Your Content"
3. Choose "Word Documents" importer
4. Upload your .docx file
5. Translate paragraph by paragraph
6. Export back to DOCX with formatting preserved

Example 5: Importing an Existing Translation

1. Open Navigation → Add Files
2. Select "Add Your Translation"
3. Choose the source file this translation belongs to
4. Select the appropriate importer (USFM, DOCX, etc.)
5. Upload your translation file
6. Codex aligns content with your source file
7. Review alignment and continue translation work

Advanced Import Features

Batch Import (Multiple Files)

• Drag and drop multiple files at once
• Use ZIP archives for organized imports
• System processes files in parallel

Alignment Algorithms

When importing translations (Target Import), Codex uses intelligent alignment:

ID-Based Matching

• Matches by segment references (for structured texts)
• Matches by cell IDs (for structured content)
• Accuracy: Very high for properly structured files

Sequential Insertion

• Fills empty cells in order
• Used for content without IDs (DOCX, Markdown, plain text)
• Accuracy: Good for similar-length translations

Timestamp-Based (Subtitles)

• Matches by time overlap
• Handles complex 1:many and many:1 mappings
• Accuracy: Excellent for time-synced content

Preview & Confirm

For translation imports, you can:

• Preview alignment results before applying
• See matched vs paratext content statistics
• Try different alignment methods
• Review confidence scores

Best Practices

Before Importing

1. Organize your files with clear, descriptive names
2. Check file formats are supported
3. Backup important files before conversion
4. Review file quality (no corruption, proper encoding)

During Import

1. Use round-trip importers if you need to export back to the original format
2. Preview alignment results for translation imports
3. Check cell counts to ensure complete import
4. Verify structure looks correct before proceeding

After Import

1. Review imported content for accuracy
2. Check metadata (book names, cell IDs, timestamps)
3. Test export if using a round-trip workflow
4. Begin translation with confidence!

Next Steps

After importing your files:

• Begin using translation tools
• Configure AI assistance
• Set up collaboration
• Learn about export options

FAQ

---

Need more help? Complete the Troubleshooting guide support form for import and alignment issues, then paste the generated template into Discord.