Problem: I have an Adapt It Scripture book that has adaptation work done apart from collaborating with Paratext. How do I get Adapt It 6 to use this document collaborating chapter-by-chapter with Paratext?
The ability to collaborate with Paratext (and Bibledit) was added starting with version 6 of the Adapt It program. Some users may have created adapted books within Adapt It before the collaboration feature was available. In such cases, the question can arise (addressed in this topic) as to how one can get previously adapted (or partly adapted) books into the form needed so that adaptation work can continue using Adapt It’s new collaboration feature with Paratext. There are a few different ways that are possible to get your Adapt It and Paratext data correctly set up. I will describe here a method that is perhaps the easiest and most straight forward for getting your data and settings into the form they need to be. I have tested the process described below using a sample Nyindrou to Tok Pisin project, and have verified that the process works well. As always let us know if something isn’t clear or you run into a snag trying to follow these steps.
Setting up Adapt It to collaborate with Paratext can provide mother tongue translators (MTTs) with a powerful pair of tools that assist in the translation of Scripture texts from a related language into the MTT’s own mother tongue. When collaboration is setup between Adapt It and Paratext, the two programs work together as one for the given project (language pair), eliminating the need for exporting texts from one program and importing them into the other program. The initial drafting of the target (related) language Scriptures is done within Adapt It. Once the draft is complete within Adapt It, the next stage of revising and checking the text is done within Paratext.
An administrator first sets up at least two Paratext projects:
- A Paratext project containing the Scripture texts that are used as source texts for the translation done by the MTT
- A different Paratext project (initially just empty books with only \c and \v markers in them) that will receive the target texts composing the adaptations made by the MTT while working in Adapt It
After the administrator has set up the Paratext projects, he then accesses Adapt It’s Administrator menu and selects “Setup or Remove Collaboration…” to tell Adapt It to collaborate with those designated Paratext projects. In collaboration Adapt It knows how to automatically retrieve its source texts from the designated Paratext project containing source texts, and automatically save the MTTs adaptations to the designated Paratext project for receiving target texts. This process is fully automatic: The MTT simply simply selects the Bible book and/or chapter to work on in each Adapt It session, and every time work is saved within Adapt It, Adapt It transfers the adaptations (target text) to the appropriate Scripture book in the designated Paratext project. Once a book has been drafted, the work in Adapt It for that book ends, and the MTT simply starts up Paratext and opens the target language project where the drafted book now appears with all the formatting that was specified in the source text. From Paratext then, the MTT can continue the process of revision, checking and polishing the book for publication.
First an overview of the process we’ll follow
First we’ll make backups copies of your data in case something goes wrong. Then, we’ll open a whole Scripture book which has previously had adaptation work done for one or more chapters within Adapt It with collaboration mode OFF (or before collaboration with Paratext was a possibility). In these instructions we’ll assume that the Scripture book is the Gospel of Mark, but it could be any Scripture book. We’ll open the book of Mark within Adapt It, and while the Mark document is open and displaying on the Adapt It screen, we’ll execute two of Adapt It’s menu commands on that document (in the order given):
- We’ll use Adapt It’s Export-Import > Export Translation Text… command to export the translation parts of the adaptation document (the target text) out to a separate usfm-format file for later import into Paratext, and then
- We’ll use Adapt It’s Tools > Split… command to split the single Mark adaptation document into separate Adapt It chapter documents, naming them properly in preparation for collaboration.
Both of the above processes should be fairly easy to do with just a few mouse clicks and typing a base file name in an edit box of the Split dialog.
Then we’ll run Paratext and open the designated target text project (which typically would be empty), and import into Paratext the usfm text file containing the adapted target text of Mark which you exported in (1) above – telling Paratext to replace or merge it with any existing contents contained in Paratext’s copy of the target text book of Mark. Once this has been done Paratext will have your target text adaptations for the book of Mark, and Adapt It will have the corresponding “adapted” documents that relate the source text with the target text, one chapter per document.
Throughout this process the Adapt It knowledge base file stays intact and retains all the mappings done previously between the source text and target text, and will be useful for continued translation work under collaboration with Paratext.
Next, we’ll do a little housekeeping to verify that the Adapt It chapter documents created in (2) above are named correctly so that the collaboration mechanism recognizes them. We’ll delete any empty chapter documents produced by the “split” operation – it is better to allow them to be created on the fly by the collaboration mechanism when needed. Lastly, we’ll check that the collaboration settings within Adapt It are correct, and do a test run to ensure that all is working correctly.
Detailed steps for the overview described above
1. Backup your Adapt It and Paratext data
Backup your work using a USB flash drive or external backup drive. The backup should include everything in the user’s Adapt It Unicode Work folder and the My Paratext Projects (on Windows) or the ParatextProjects folder (on Linux). You might also want to copy the same folders to a different flash drive kept by the program administrator.
2. Run Adapt It, and open the Scripture book that was (partly) adapted apart from collaboration
Select the project in which your adaptation document is located from the Select a Project page of Adapt It’s startup wizard. Then click Next >. One of the following will appear next:
- If you created the Adapt It document apart from collaboration, and have not set up collaboration for the project, the Select a Document page of the wizard should appear next with a list of adaptation documents that were created apart from collaboration. Select the document – the multi-chapter book of Mark in our present case – and click on the Finish button to open the adaptation document. Or,
- If you or your administrator has set up this project for collaboration, what should appear next is the Choose How You Want To Work With This Project dialog with 3 radio button choices. If this dialog appears, you should select the middle button that says, Work with other Adapt It texts (Paratext texts not available: Collaboration off), and click OK. You will then see the Choose a Document wizard page. The list on this page should show the name of the multi-chapter book of Mark that containing the adaptations previously entered for the whole book. Select the document – the book of Mark in our present case – and click on the Finish button to open the adaptation document.
Once you have your multi-chapter-book-of-mark document open within Adapt It, scroll through the whole book and note which chapters have adapted content. Write down the chapter numbers that have any significant adaptation content that you want to preserve. You will need to know the chapter numbers that have adapted content for later reference. With the document open in Adapt It proceed to the next step below.
3. Export the translation text
With your working multi-chapter document open in Adapt It, select the Export Translation Text… command from the Export-Import menu. We will use the Export Translation (Target) Text dialog that appears to export the translation (target text) part of the adaptation document out to a separate usfm-format plain text file. Don’t change any defaults in the dialog, and just click the OK button. The default location for saving translation text exports should be the _TARGET_OUTPUTS folder within your Adapt It project folder. Use the provided file name that Adapt It supplies which will be similar to the name of the visible adaptation document, but it will have a .txt extension instead of an .xml extension. I will assume in these steps that the file name is Mark.txt. Click the Save button in the file dialog. Adapt It reports the location where this export has been saved. Remember where this exported file is located and its file name (write it down), as you will need to navigate to it again from within Paratext in a step below.
4. Move any orphaned files out of the way
Let’s assume your Adapt It project is named Language A to Language B adaptations. Start up your file browser or file manager (Window Explorer in Windows, Nautilus or Nemo file manager in Linux), and navigate to the Adaptations folder of the Adapt It project where your adapted document is located. Assuming your project is named Language A to Language B adaptations, its Adaptations folder should be located at: Adapt It Unicode Work/Language A to Language B/Adaptations/. Look at the names within that Adaptations folder. If there are any collaboration chapter files in the Adaptations folder that might have been created at some point for the book of Mark (having …MRK_CH… in their file name) we will need to move them out of the way before we do the next step. Move any existing files that have names of the form _Collab_42_MRK_CHnn where the nn is 01, 02, 03, 04, etc. In other words, if there is an existing file within the Adaptations folder that has the name _Collab_42_MRK_CH01 or _Collab_42_MRK_CH02, _Collab_42_MRK_CH03, or _Collab_42_MRK_CH04, etc, any such files will conflict with the next step and need to be copied elsewhere and deleted from the current Adaptations folder. Do not attempt to delete the multi-chapter document that is currently open within Adapt It (the name is shown in Adapt It’s title bar). Once you have eliminated any potentially conflicting files, go to the next step.
5. Split your old adaptation document using Adapt It’s Split command
With your multi-chapter document still open in Adapt It, select the Split… command from the Tools menu. The Split The Open Document Into Smaller Documents dialog appears. Click on the third radio button labelled Split into single chapter documents. Then in the text box, type the following as a generic name to which Adapt It will add each chapter number to form individual chapter files: _Collab_42_MRK_CH
Note that the generic name begins with an underscore and uses underscores between each part of the name except there is no underscore after the CH at the end of the name you type. You can also look at the list in the dialog to check for any potential filename clashes. There should be no clashes if you did step 4 above. Click on the Split Now button to initiate the splitting of the whole book of Mark into individual chapter documents. The document splitting process may take a couple minutes to complete. You will see the message Splitting the document succeeded when it is complete for the book of Mark – which should now have 16 separate chapter files. The original single whole book file was removed by the split routine after creating the individual chapter files. Click OK. Adapt It will then show the Choose a Document wizard page where you can also see the list of chapter documents that were created. At this point, click on Cancel to close the wizard page, and click on Close if necessary to close the Split dialog. Then select Close Project from the Adapt It File menu to close the Adapt It project, leaving a blank Adapt It window. We will come back to Adapt It in a later step below.
6. Import the translated text into Paratext
Run Paratext. Access the Paratext File menu and select Project/Resource, then select the Paratext project that is designated for storing the target/translation texts. (If you have not yet created a Paratext projects for holding source texts and a different Paratext project for holding the translation/target texts see the “Help_for_Administrators.htm” help file for information on setting up collaboration between Adapt It and Paratext.) With the Paratext target text project open, display the book of Mark (MRK) using the drop down selection box at the top of the Paratext window. Normally, this Paratext book of Mark should be empty (with only chapter and verse numbers, but no text in the verses). Now we will import into Paratext the usfm text of Mark that we exported from Adapt It back in step 3. Select the Import Book(s)… menu item from the Paratext Project menu. In the Open file dialog that appears, navigate to the usfm book of Mark that you exported from Adapt It back in step 3. The target text you exported in step 3 should be located at: Adapt It Unicode Work/Language A to Language B adaptations/_TARGET_OUTPUTS/Mark.txt where Mark.txt is my representation here for the actual file name of the exported file created in step 3. Select the Mark.txt file and click Open. Paratext displays the Import Book(s): … dialog, and in the Books to Import column, it should list the book abbreviated as MRK with a tick in the check box next to it. At the bottom left of this dialog there is also a check box called Replace entire book(s). You may leave this check box un-ticked if there are already some translated verses in the Paratext book of Mark, to preserve those verses. Put a tick this box if you know that the Paratext book of Mark is basically empty (it has chapters and verse numbers but no text). When the box is ticked the exported Mark.txt file will replace the entire book with the contents of the Mark.txt imported book. Click on the OK button to start the import process into Paratext. At this point Paratext should now have your target text adaptations for the book of Mark in the Paratext project for storing translated texts. Within Paratext, scroll around through the book and make sure it contains what you expect – that it has the adapted translations that you were expecting from the file you exported from Adapt It in step 3. The rest of the file should have empty chapter and verse numbers. Save the file from within Paratext, and then shut down the Paratext program for the next three steps below.
7. Remove any empty Adapt It chapter files from the Adapt It project’s Adaptations folder
In this step you will tidy up the Adapt It project’s Adaptations folder, removing chapter document files that you know are empty (have no adaptations). In your file browser or file manager, navigate to the Adapt It Unicode Work/Language A to Language B adaptations/Adaptations/ folder. In step 2 you wrote down which chapters had adapted content, and so you should now know which other chapters have no adapted content. Those files with adapted content we want to preserve, but those which were created empty, we can remove by deleting them from the Adaptations folder. The chapter files for the book of Mark will be named _Collab_42_MRK_CH01.xml, _Collab_42_MRK_CH02.xml, _Collab_42_MRK_CH03.xml, _Collab_42_MRK_CH04.xml, etc up to _Collab_42_MRK_CH16. There should be no harm in leaving the empty chapter files within the Adaptations folder, but I think it is best to allow Adapt It to create new chapter documents when the user first selects those chapters for adaptation during collaboration. So, go ahead and delete the chapter documents that you know are empty (have no text content other than empty chapters and verse numbers) from the Adaptations folder.
8. Check the collaboration settings for your project
In this step you will check the collaboration settings for the Language A to Language B adaptations project using the Adapt It Administrator menu item Setup or Remove Collaboration…. If you did step 5 above, Adapt It should still be running (if not, run Adapt It and Cancel at the first wizard page). Make the Administrator menu visible using the Show Administrator menu (password protected) item on the View menu. The password admin always works. Then, from the newly visible Administrator menu, select the Setup or Remove Collaboration… menu item, which will show the dialog. This dialog has 4 numbered parts. In part 1, click on the down arrow of the drop-down box and select the Language A to Language B adaptations project. Ensure that the Paratext button is selected in part 2. In part 3 ensure that the Get by Chapter Only (Recommended) radio button is selected (it is on the right side of the dialog in part 3). Click the top Select from List button and make sure that the appropriate Paratext project is selected – the one for obtaining source texts. (let Adapt It analyze the Project’s books which may take a minute or two). You can read the summary message. Then click the second Select from List button and make sure that the appropriate Paratext project is selected – the one for receiving the adapted texts (again let Adapt It analyze the books which may take a bit of time). In part 4 click on the Accept this setup and prepare for another button. Click OK to dismiss the collaboration setting summary message. Finally click on the dialog’s Close button. The Choose a Project wizard page appears. Go to the next step below.
9. The last step is to check that collaboration is working properly
We’re still working within Adapt It. The Language A to Language B adaptations project should be automatically selected in the list, so click on Next >. The Choose How You Want To Work With This Project dialog appears. Click on the top radio button that says, Work with my Paratext Scripture texts (Collaboration on), and click OK. The Get Source Text From Paratext Project dialog should appear listing the books in the left hand list and chapters for a selected book in the right hand list. Ensure that Mark is selected in the left hand list, and select the Mark 1 chapter in the right hand list, then click on OK to proceed. You should find that all of your’ adaptations are now within the chapter documents accessible via collaboration while in Adapt It, and that the Paratext project for receiving adapted translations also has the same target text that is within the Adapt It chapter documents.
For best results, the MTT should continue working only in collaboration mode. The top button in the Choose How You Want To Work With This Project dialog will normally be selected by default – unless the user explicitly selects Close Project from the Adapt It File menu, or selects Cancel from the Get Source Text From Paratext dialog and tells Adapt It to turn off collaboration. The MTT should always make sure that the top button is selected and always work with collaboration ON for each work session.
The above steps can be followed to prepare other Scripture books that may have been adapted (or partly adapted) apart from collaboration, making them available as chapter-by-chapter documents while working in collaboration with Paratext.
Note: The knowledge base file for a given project is the file within the project folder having the same name as the project folder, but having an .xml file extension on it. For example, For example, the knowledge base file would be called Language A to Language B adaptations.xml and is located within the Language A to Language B adaptations project folder, which in turn is located in the Adapt It Unicode Work folder. If the knowledge base for an Adapt It project ever gets corrupted or accidentally deleted, it can be retrieved either from backups, or it can be quickly recreated by using the Restore Knowledge Base… command on the File menu, which will restore the knowledge base from one’s existing adaptation documents.
Have fun collaborating with Paratext!