Importing

Everything enters Aquilla through the Import dialog, opened from the editor header’s Import button. This page is the full catalog; Creating a project covers the quick path of getting a first file in.

Who can bring in new source files is an organization setting, Who can import files: Project lead by default, or Maintainer only. If your role is below it, the import buttons for new source text are hidden; importing a translation into a file already in the project stays open to contributors. See Organization settings.

The dialog opens on “What are you importing?” with cards for New source text (“Adds new files to translate from.”), A translation (“Target text for a file that’s already in this project.”) and, where you can upload recordings, Recordings (“Audio for lines already here. Each file finds its line by its name.”; see Uploading recordings). Choose New source text and the dialog shows “Choose the format that matches your files.” with a Most popular row and a Specialized section behind a filter box. Cards marked Beta work today and are still settling; Soon cards are announced but not yet live. For A translation, see Importing translations into an existing file.

Most popular up top, Specialized below. The filter box narrows the specialized list.

Uploading your own files

Upload files takes nearly anything a translation project starts from. The panel lists what each group covers:

• Scripture — USFM, USX, SFM
• Translation — XLIFF/XLF, TMX, CSV/TSV
• Documents — DOCX, TXT, MD, HTML, EPUB, JSON/ARB, PPTX (text boxes and table cells alike), IDML (InDesign)
• Localization — PO/POT, Java properties
• Subtitles — VTT, SRT, SBV
• Paratext project — .zip or folder
• Other formats — AI-assisted when configured, always reviewed before import

Drag files in, or pick them; a whole Paratext project can arrive as a folder or zip.

Drop files on the panel, or use Choose files / Choose folder. A Paratext upload asks one extra question first: whether the project should come in as Source text or as a Translation in progress. An EPUB shows a chapters picker on preview, so you import just the parts you need.

A single JSON or ARB file opens Choose which keys to translate first: “Tick the values in {fileName} that hold translatable text. Everything you leave unticked stays in the file and is written back unchanged when you export.” Use Select all keys or tick keys one by one, watch the count of strings selected, then choose Import selected keys. The finished translation can go back into the same JSON file with the JSON export.

Preview before anything is written

Every import ends at a preview: how many cells, each reference and its text, and structural content marked separately. Nothing lands until Confirm import.

For USFM files, the preview also checks the file’s structure. If something is off, it says “Structure problems found in this file” and lists each one, for example “This chapter number appears more than once” or “Unrecognized marker” followed by the marker, so you can fix the source file before you import it.

For a WebVTT subtitle file whose cue times leave out the hours (such as 01:03.209), Aquilla reads them as minutes and seconds and keeps the cues. The preview says how many it read that way, for example “3 cue times left out the hours (01:03.209) and were read as minutes and seconds. Check those cues’ wording in the preview.” If some cue times still can’t be read, a second notice says so: “2 cue times could not be read, so their wording is not in this import.”

Some converters write a video frame number as hundredths of a second, so 00:01:06:15 (frame 15) becomes 00:01:06.150 instead of the real time. When every cue time in a subtitle file looks like that, the preview warns “This file’s times look like video frame numbers written as hundredths of a second, so lines may start up to 0.7 s early.”, with an (i), “Why these times look wrong”, that explains it. Fix the times is chosen to start with, and a line under it names the frame rate used: the linked film’s (“Converted at 24 frames a second, the film’s rate.”) or, without one, the rate the highest frame number points to. Use a different frame rate opens a Frame rate picker if you know the file’s rate is another. Keep as is imports the times unchanged. The same check runs wherever a subtitle file comes in: uploading a new file or updating an existing one, the Media view’s Sources menu, attaching captions, YouTube captions, and a translated subtitle file.

Every cell has a size limit. If a document contains a section too large for one cell, the import stops before anything uploads and names exactly which section is too big, so you can split it in the source document and try again. IDML layouts get one extra chance first: Aquilla splits an oversized story at its line breaks, and only a paragraph with no break inside it reaches that limit.

The preview: check the cells and references, then Confirm import.

Re-importing a file

When the source of a file you already imported has been revised, choose Re-import in that file’s ⋯ menu in the sidebar. Anyone who can import source files can use it. The dialog, titled “Re-import {name}”, takes one document: a project or a set of books is refused (“Re-import takes one document, not a project or a set of books.”). Spreadsheets, JSON files and packages that hold several documents can’t be re-imported this way. A file from a partner importer such as Biblica reopens that partner’s panel instead.

The preview adds an Analysis box that counts the lines the new document would add and the lines whose source text changed, listing the first 40 of each, with the old text shown for a changed line. If the two match, it says “Nothing in this file has changed.” Under it: “Translations already in the file are kept. A changed source line is marked for review until it is validated.” Any translation text in the uploaded document is not used. Then choose one of:

• Update this file: puts the new source into this file. Each translation stays. A line whose source changed loses its validations and is highlighted in the editor (“The source text changed in a re-import. The translation was kept. Validating this cell clears the highlight.”). A change that only swaps an apostrophe or a soft hyphen stays validated, a line that only moved keeps its translation and validations, and a line the new document no longer has is set aside rather than deleted. New lines are added.
• Make updated copy: leaves this file as it is and makes a copy, with its translations, that gets the same update. If the name is taken, the copy is named like “Name (updated)”.
• Make a blank copy: adds the new document as a fresh file with no translations, named like “Name (blank)” if the name is taken.

When the file already exists

Uploading a file whose name matches one already in the project opens Re-import detected: “The following 1 file already exists in this project. Choose what to do with it.” Per file you choose:

• Update existing — “Updating matches stable units and keeps translations, language lanes, comments, audio, and units missing from the new file.” This is the safe default for a revised source.
• Skip — leave the project untouched.
• Import as duplicate — bring it in as a second file.

With several colliding files, the Apply to all row (Update all, Skip all, Import all as duplicates) decides them in one move.

Update existing works the same whichever way the file comes in, including a spreadsheet or a single JSON file that goes on to its column-mapping or key-picking step: the chosen file is updated in place rather than imported a second time. For a workbook, picking the same sheet you imported before updates that sheet’s file; picking a different sheet imports it as a new file.

Audio and video files can’t be updated in place. For those the screen offers only Skip or Import as duplicate and says “Audio and video files cannot be updated in place. Choose Skip or Import as duplicate for those files.”

When you update an InDesign (IDML) file, Aquilla also places the translations it kept into the new file’s bold, italic and other styled pieces, showing “Aligning styles in {fileName}… {count}/{total}” while it works. This uses the project’s AI; if AI isn’t set up, the source is still updated and every translation stays as it was.

A collision is a choice, not an accident: update in place, skip, or keep both.

Public Bible libraries

Two cards import source text with nothing to upload:

• eBible corpus pulls openly licensed translations from the BibleNLP corpus. Search by language, title, or id, and pick a mode: New source file, or Into target column to fill your target from an existing translation.
• Bible API (helloao.org) offers “1,000+ translations — the whole Bible, one testament, or just the books you pick.”

Search the corpus, pick a translation, and it imports directly; no files change hands.

Uploading recordings

To add a whole folder of recordings to lines that are already in the project, choose Import → Recordings. It works across as many books as you like. For one file, open that file’s ⋯ menu in the sidebar and choose Upload recordings…; this works for any file, not just Bible books. You need the same access as for uploading a single recording (Contributor or above), and the recordings go into the language you’re working in. If the project has no source text yet, the card says “Add a source text first. Recordings go onto lines that are already here.”

Drag the recordings or a folder in, or pick them. Each file finds its line from its name, for example “Genesis 1-1”, “Gen 1.1”, “1Sam_3_4” or “GEN_001_001”. A folder can name the book or the chapter. A name such as “1-1a” or “part 1” makes a piece of one verse, “Genesis 1-1-3” is one recording for verses 1 to 3, and files with no numbers go onto the lines in folder order. Click the (i) to read the full rules, How each recording finds its line.

Nothing uploads until you’ve checked the preview. It lists every file with the line it goes to and how it was placed (by name, by number or by order). Use Change to pick another line, Don’t upload to leave a file out, or Start one line earlier / Start one line later for files placed by order. Files that can’t be placed are listed with the reason, such as “This isn’t an audio file.” A line that already has a recording keeps it in its take list, and the new one becomes the one that plays. Choose Upload {count} recordings to start.

Every file and the line it goes to, before anything uploads.

The (i) beside the summary opens the full rules.

A banner shows the upload’s progress, with Stop uploading. If the connection drops, the upload waits and carries on when you’re back online. Any file that couldn’t upload is listed with its reason, with Try them again. When a verse came in as several pieces, its Recording tab offers Join into one recording.

Audio and video files

Upload files also takes audio and video. An uploaded video is linked automatically as the file’s picture, so it plays beside the timeline with no separate link step. If you drop caption files (VTT, SRT, or SBV) in the same batch, or an MP4 or M4A file carries its own caption tracks, Aquilla opens an Import window titled with the media file’s name before anything is written. It says “Review wording and timing before importing. Your original files are preserved.”

• Text source chooses where the wording and timing come from: a caption file from the batch (one whose name matches the media file is offered first), the media file’s own Embedded captions (named by language when it has one), or Transcribe audio. Transcribe audio splits the audio at pauses and, as the window says, you can choose automatic transcription after the import (see Audio & voices).
• The window lists the captions to import, one line each, with a count such as “24 captions”. The pencil beside a caption opens its wording and its start and end times for editing (type times the way the list shows them, like 1:02.5). A count such as “1 needs attention” marks captions whose wording or times can’t be imported as they stand; fix them before Continue import is available. The X beside a caption (“Remove caption {number}”) drops it. A caption that Aquilla placed by matching text can show its Alignment confidence.
• A caption file you use in this window becomes the media file’s text. A caption file you do not use imports as an ordinary subtitle file.

Captions can also be added after the import as separate tracks on the timeline: see Attaching captions as a text track. Importing audio or video is limited to 2 GB per file.

YouTube video

The YouTube video card (in the Most popular row) is described as “Link a film, bring captions, or generate them from your original media.” Choose a Caption source, then paste the video’s link under YouTube video link. Open About YouTube captions for a short explanation of what YouTube does and does not share with Aquilla.

• Link the film only: links the video as the file’s picture. Give the file a Video name, then choose Preview import and Link film. Once linked, a maintainer can attach captions to turn them into the file’s rows; see Attaching captions as rows below.
• Import a caption export: upload your own VTT, SRT, or SBV file under Your caption export. About YouTube captions says “Export your captions from YouTube Studio as VTT, SRT, or SBV.” Aquilla cannot read captions from YouTube itself, so the export is the only way to bring the text in. Each caption becomes a cell: the wording is the cell’s text, and the caption’s start and end times set the cell’s timing. Preview captions shows the cells before Import captions writes them.
• Use original audio or video: upload the original recording, with the same timing as the YouTube video, under Your original audio or video. Aquilla can generate captions from it using your ASR settings, or let you review embedded caption tracks. Import media and link the film opens the same review window as an uploaded audio or video file (see Audio and video files below), then the picture is linked to the YouTube video.

The YouTube video importer, set to bring in a caption export.

Attaching captions as rows

A linked video with no rows yet shows a card explaining what to do. On an empty linked-video file, a maintainer can Attach captions without track-editing enabled. Attach captions appears in the Text view’s card and the Media view’s Text track card. The attached captions become the file’s own rows, like captions added at import time. The video keeps its own sound unless you choose an uploaded recording.

For a linked video that is not on YouTube, the card adds “or make rows from the film’s own sound”. Pick a Sound track (the project’s source language is chosen to start) and click Make rows. Aquilla downloads the sound, saves a copy with the file as its recording, splits it into rows where the speech pauses, and transcribes them. The rows are timed to the video. Progress shows as it goes, and you can cancel until the rows go in (“Stopped. Nothing was saved.”). A long transcription that reaches the hosted limit pauses and carries on by itself: “Transcription limit reached, continuing at {time}”.

From another project

The From another project card (marked live link) is described as “Read another Aquilla project’s source files here. The link is live, so later upstream edits keep flowing through.” It opens the same steps as Project Settings → Source & sync → Link to a source project: pick the project, say which corpus becomes your source, and review the files you will bring in before anything changes. The card is greyed out when the project already reads its source from another project, or when your role is below Project Lead. See Linking a project you already started.

Spreadsheets and column mapping

The Spreadsheet importer (CSV, TSV, XLSX) shows your file’s real columns and asks what each one means: “Tell us which column contains each piece of data. Only ‘Source text’ is required.” Beyond source and target you can map a cell label or reference, a cast name, start and end timestamps, and a content type, with a First row is a header checkbox for files with headings. A mapped cast name becomes each line’s character, and each character is cast once, so every line it names picks up that character’s voice. See Dubbing & characters.

Your columns, Aquilla's fields: only Source text is required; everything else is optional.

The related Paired translation importer fills the target column from source and target pairs in a spreadsheet, and Translation Memory does the same from a TMX memory file.

The specialized importers

• Macula Hebrew + Greek — original-language OT/NT with per-word lemma, morphology, and Strong’s.
• Translation Notes — unfoldingWord notes, shown beside the matching verse as you translate.
• Biblica Study Bible Notes — an InDesign study Bible, Treasure Hunt Bible or Reach 4 Life package. A book volume imports its study notes and every verse of the Bible text, each verse as its own cell keyed to its reference, so a translator can tell a verse from a note about it. Front and back matter volumes hold no scripture and import notes only.
• Open Bible Stories — narrative stories with reference images, from unfoldingWord/door43.
• Door43 (DCS) — import a released Door43 resource as a pinned source you can re-sync later; the workflow is covered in Source projects & linked targets.
• SDBH Hebrew Lexicon — the Semantic Dictionary of Biblical Hebrew, for localizing definitions by semantic domain with lossless export back to MARBLE XML. Choose the master edition as your source and, optionally, an already-localized edition to pre-fill the target column. A few entries list more verse references than a cell can hold; if any do, Aquilla warns you first (“Some reference lists will not be imported,” naming each affected entry) and lets you Cancel import or Import anyway. Those entries’ definitions still import in full: only the oversized reference list is left off, and exporting rebuilds from the preserved lexicon file, so the original reference data is never actually lost.

Google Drive appears when the deployment has Drive access configured: you pick files or a whole folder, only the items you pick are shared with Aquilla, and Google Docs import as DOCX.

Importing translations into an existing file

To fill a file’s target column from a translated file, open Import and choose A translation. It needs the Contributor role or higher, and the project needs at least one source file to translate into; otherwise the card says “Add a source text first. A translation goes into a file that’s already here.” (a project lead has to add it).

A translation: pick the file, pick the language, then drop in the translated file.

1. Under “Which file does it translate?”, pick the file in the searchable list (“Search files”).
2. The dialog is now titled “Import a translation into {fileName}”. Drop in the translated file. Accepted files are USFM/SFM, CSV/TSV/XLSX, and, for subtitle files, VTT, SRT, or SBV, so a translated subtitle file from a dubbing vendor imports the same way a VTT does.
3. Aquilla pairs the rows with the file’s lines and opens Review matches. Only the rows you confirm import, and source text never changes.

To have someone check the translation before it lands, tick Stage as proposals for review: “Each match becomes a proposal waiting for approval. Nothing is written to the file until someone approves it.” The dialog title then ends in “as proposals”. The matches arrive as one changeset, named “Imported from” the file, that is approved or rejected like any other staged change.

On a project with more than one target language, the dialog has a Fill which language lane picker, set to the language you have open in the editor. The translations go into the language you choose, and choosing another one opens it in the editor (“Opening this language… you can choose a file in a moment” shows while it loads). With a single target language the picker is hidden. Add one file at a time.

When an upload looks like a translation

Source uploads get a check first. If a file looks like a translation of a book already in the project, the dialog stops with “This looks like a translation” (the file says it is in your target language) or “{book} is already in this project” (the file is for a book you already have), and asks “What is it?” with answer cards:

• A translation of {book}: fills that book’s empty translation lines, and you check every match before anything is saved.
• New source text: adds the file to the project as new source text. Nothing already there changes.
• A separate source text: adds it as its own file next to the one you have.

A translation goes into one file at a time. A file that holds several books, some already in the project, can only come in as source text; to bring it in as a translation, split it into one file per book first.

Reading the Review matches screen

While Aquilla pairs the incoming rows with your cells, the screen shows “Matching lines…” over placeholder rows. A summary strip then counts what it found: rows matched, rows already there (the cell already holds exactly that text, so importing changes nothing), rows that would replace existing text, cells left without a translation, and, for subtitles, cues skipped because they were empty or unreadable. A Lines left without a translation list names every cell the file did not fill. A switch above the list, All or To check, hides the rows that need no attention.

Each row shows the incoming text beside the cell’s source text, and rows that would overwrite a translation show “Replaces:” with the current text. Rows tagged Already there, and rows tagged Contested, start unticked. Tick the ones you want. Select all ticks every row shown (never an Already there row) and then turns into Deselect all.

Paired by source text: a row whose source doesn't match its line gets a Source differs pill and starts unticked.

The eBible Into target column mode ends at a review step too, reached with Next: Review matches. It lists each matched verse; where the target already has text, the verse is tagged conflict, starts unticked, and shows the current text struck through above the incoming text.

Review matches: conflicts start unticked; Apply writes only the verses you keep.

How rows are paired depends on the file:

• By reference. USFM, and spreadsheets with a reference column you mapped, match on cell references. Aquilla recognises a reference in several spellings, so Genesis 1:4, gen 1:4, and GEN 1.5 all find their verse.
• By timing. Subtitle files, and spreadsheets with Start timestamp and End timestamp columns mapped, match on when each cue or row plays, when both sides have timestamps. Inserting or deleting one cue only affects that row.
• By source text. A spreadsheet whose Source text column is mapped is paired with lines by that text. The screen says “Paired with lines by source text. Rows whose source doesn’t match their line are left unticked.” A row whose source differs from its line’s carries a Source differs pill.
• By order. With none of these, rows pair top to bottom, and an amber warning says “Matched in order, not by reference or timing. Check each row’s source text.”

Other warnings say a pairing is shaky. “The open file’s lines have no timings, so rows were matched in order. Check each row’s source text.” appears when you bring in timed rows but the open file’s lines have no times to match against. “Rows in this file: {rows}. Lines in the open file: {lines}. If a row was added or left out, every row after it is on the wrong line.” appears when the counts differ. When the file belongs to another book or chapter, a note such as “This file is for {incoming}; the open file is {file}.” says so.

A row that finds no line lands in “Rows that didn’t find a line” (verses: “Verses that didn’t find a line”) with its reason, such as “No line has this reference,” “This reference appears twice,” “No reference,” or “No line has this source text.”

Subtitle imports add tools for messy files:

• Timing shift. If every cue in the file runs early or late by the same amount, a tickbox such as “Shift timings 2 seconds later (lines up 14 more)” offers the correction. Ticked, pairing uses the corrected timings; unticked, it uses them as delivered. A frame-rate mismatch between the file and your video is corrected the same way (“Frame rate adjusted”). Only the pairing changes: your cells’ own timings are never altered.
• Contested rows. Two cues that both fit one line show a Contested pill. Click it to open Also fits this line, which shows the other cue and where it sits now (“Now on:” a line, or “Not placed”), and use Swap to put that cue on this line instead.
• Same timing. Cues with identical start and end times, as when two people speak at once, show a Same timing pill and a Swap button. Which line each landed on was decided by file order, so check them.
• Timing differs. A row whose cue times differ from its line’s shows a Timing differs pill. Only the text imports; the line keeps its own time.
• Cues that didn’t find a line. A list names each unplaced cue and why: “No line within reach,” “Lost its line to another cue,” or “Timecode ends before it starts.” A count of broken timecodes shows in the strip. “Many cues cover only part of their lines. Check the pairings.” means the file is probably offset or cut differently from yours.

On a spreadsheet with several sheets, the back arrow in the dialog title reads Back to sheet list on the column step and Back to column mapping on the review step.

Who can import

Importing writes project content, so it follows the same role rules as editing. Bringing upstream changes into a Door43-pinned source is stricter: “Maintainer or above required to import upstream changes.”

Downloading what you imported

Aquilla keeps a copy of the original file behind every import that had one (an uploaded document, not a public-library pick), so you can get back the exact bytes you brought in, translations aside. A file’s ⋯ menu offers Download original when a copy exists; a project’s overview page also lists every file with one under an Imported originals card, each with its own Download original button plus a Download all originals button that bundles them into a single zip. On a project with more than five imported originals, the card shows five at a time behind Show {N} more and Show all ({N}) buttons, collapsible again with Show fewer.

This is different from Export: export injects your current translations into a copy of the file, while downloading the original hands back what you imported, untouched. See Exporting your work for the translated version.