Note: this article was originally posted in January 2015


Adapt It will work effectively for non-scripture materials, as well as for scripture materials. It’s effectiveness depends on the similarity of the source language (the language of the text you are starting from) to the target language (the language of the adapted/translated text that you want to generate).

  1. The source text must be Plain Text – and it should be Unicode encoded. Don’t try to input the text of WORD’s .doc or .docx documents, or OpenOffice’s or LibreOffice’s .odt documents. Instead, click Save As… on such documents and save them as UTF8 encoded plain text to some place known to you on the hard drive. All the above word processors have the Save As… command as an option – it is within their File menu. If you are unsure, or Adapt It does not accept your input text, let me know (bruce_waters@sil.org) and I’ll help you further. Better still, email me and attach the file which you are trying to load into Adapt It, and I’ll check it out and advise you. We can Skype talk if you wish. My Skype name is adaptitbruce.
  2. If the source language and target language are similar, or dialects of each other, then the work goes very quickly. If the languages are related more distantly, then more work is needed to get a good translation – in particular, you would make more use of “mergers” (source text words grouped into a unit which you translate by a word or phrase of the target language), placeholder insertions, and retranslations — these are described further below.
  3. Adapt It will automatically, when first launched, create a folder, the “work folder”, in which all adapting work is saved. All translations between a pair of languages are done in a “project” and each project will have it’s own folder. The work folder is called  Adapt It Unicode Work, and all project folders will be automatically created within that folder. Each project name is of the form:  “<source language name> to <target language name> adaptations”  – where <source language name> and <target language name> are names which the user supplies in the Start Working… wizard which runs when Adapt It is launched.
    For instance, if you were adapting between Dutch (as source text) and German (as target text), you’d enter the names  Dutch  and German in the wizard and the project will then be stored in a folder named “Dutch to German adaptations” within the Adapt It Unicode Work folder.
    The only part of this project setup process that you can control is the two language names you type in to create a project; Adapt It does all the rest under the hood on your behalf – creating the project folder, configuration files, a knowledge base file, and so forth.
  4. Adapt It translates from a source text, into a target text – lining up the corresponding words or phrases vertically. Your translation work is done in a text box (we call it the phrasebox), which moves from location to location in the document. At each location you enter the translation word or phrase and follow that with a click of the Enter key to cause the text box to move forward to the next ‘empty’ location (that is, a source text word which as yet has no translation associated with it). The text box dynamically resizes itself if the translation is lengthy.
    Be careful when typing a translation into the box. A common error of new users is that they forget that the adaptation text typed into the box must be a translation equivalent meaning for the source text immediately above the phrasebox, and they let their eye wander along the source text line of words and they keep entering translations for words that have nothing to do with the meaning of the source text word or phrase immediately above the phrasebox.
  5. When adapting you are not limited to word-for-word translations. Adapt It also supports phrase-by-phrase adaptations (that is, phrasal translations, or if that makes no sense to you then consider it as a group of words which need to be translated as a unit of meaning). Typically you will adapt using a mix of word by word and phrase by phrase translations.
    A phrasal adaptation is useful when there are some grammatical differences between the source language and the target language, and those grammatical differences can by ignored by adapting over a larger stretch such as a phrase. Phrasal adaptations rely on their being a selection of source text words made first – the selection tells Adapt It which words need to be grouped together to form the source text phrase. How to make a selection is described in a later point.
    To make a phrasal translation you just select the source words which are to be ‘merged‘ together into a phrase group, and then clear the phrasebox and then type the word or phrase of the translation into it.  You can skip first clearing the phrasebox if the text in it is already selected, because the first character you type will replace the entire contents and you then just finish typing the rest of the meaning. (In our documentation, we often refer to a phrasal adaptation as a merger. They mean the same thing.)
  6. In the course of doing the adapting work, a Knowledge Base (KB) is progressively built up as you work. It starts off empty, but after a lot of work it may contain thousands of entries. The KB is what gives Adapt It its power to help you more and more as you do your work. Its entries are the associations between each source text word or phrase, and the target text’s word or phrase which is the equivalent meaning.
    Adapt It manages the KB automatically for you. You can inspect its contents at any time (see the Knowledge Base Editor item in the Tools menu).
    Here’s how the KB and the document interact as you do your adapting work. When, at the current location of the phrasebox, you press the Enter key (or the Tab key) to have a translation in the phrasebox accepted, Adapt It stores an appropriate entry in the KB, and then looks ahead for the next empty location in the document. It moves the phrasebox to that location, and then builds a temporary set of ten source text phrases from the source text’s context there (a one-word phrase, a two-word phrase, a three-word phrase, etc). It then tries to find, starting with the longest of those phrases and going to the shortest, a matching entry in the KB. If it finds one, the matched entry’s stored translation is automatically inserted into the adaptation at that location. But if there is more than one possibility, a dialog will open and the currently known possibilities are listed. You would then click the meaning that you want for that location, or type a new translation into the dialog if none of the listed meanings is appropriate, and then click OK to have your choice, or your new meaning, accepted. When it is accepted it is displayed in the phrasebox awaiting your next action (which usually will be a new press of the Enter key to move the phrasebox forward again).
    Matched and automatically inserted adaptations from KB lookups are displayed with a light purple background. This is important. You should check that the purple backgrounded series of adaptation words is an accurate translation of the source text words above. If the meaning is not accurate, click the translation text where it needs editing and change the adaptation to get the correct meaning. Only when you have verified the adaptation is an accurate translation should you continue adapting at new empty locations further on.
    The KB is not specific to the type of translating work you are currently doing. You might populate the KB with thousands of entries while working on literacy materials, or story books, or planning documents or whatever, and then decide you want to translate scripture between the same language pair. The one KB works equally well for each of those tasks, and you would do them all within the one project.
    (This is unlike Paratext’s Interlinear feature. The latter works only for texts which are chapters and verses from the Old or New Testament; if you try adapting other materials in Paratext, you’ll get no output at all. This is because Paratext’s interlinear feature is based on statistics, and the known content of the verses within the scriptures. Adapt It’s adaptation engine is not statistics based, but instead relies on the user’s knowledge of meaning equivalents of words and phrases in the language pairs involved in the translation work.)
  7. To successfully do a translation, there are just a few workflow techniques to master. We talk in more detail about these in the documentation files – see below. Some of these techniques use buttons on the command bar just above the interlinear display. Hover the mouse of each of the buttons to see tooltips which describe what they do.
    Briefly, the basic workflow techniques are:
    a) Click under a source text word or phrase to reposition the phrasebox at that location.
    b) Type a translation into the phrasebox (or edit what is in the phrase box).
    c) Press the Enter key (or Tab key) to cause the phrasebox’s translation to be accepted into the KB and have the phrasebox automatically relocated to the next “empty” location.
    d) Make a selection (this is always done in the source text line – the top line of a ‘strip’). There are several ways: click a source text word, or click and keep the mouse button down while dragging the mouse to the last word of the wanted selection and release the button (you don’t need to touch intervening words, and the selection can extend over more than one line), or a couple of other ways which you can read about in the documentation – one very useful way is to hold the ALT key down while pressing either the right or left arrow keys one or more times.
    e) Merge two or more selected words (a maximum of ten) to form a phrase which can then be translated with a target text word or phrase. The merger can be initiated by a button (on the command bar), or by ALT+Enter key combination, or just by typing a character into the phrasebox.
    f) Insert a Placeholder (it shows as … (3 dots) in the source text line) so that an extra word or phrase of the target language can be placed at that … location, when the extra words are not appropriate as translations which are part of the meaning of either the source text word or phrase on either side of the … location.
    If you insert a placeholder where there is punctuation before or after, Adapt It will ask you what is the direction of association. That is, is the placeholder text to be interpreted as an addition to the text which precedes it, or as an insertion belonging to the text which follows it. Once you supply your answer, it will move the punctuation to the appropriate place on the placeholder.
    g) Select one or more words, and press the button for doing a Retranslation. A dialog shows into which the retranslation can be typed.
    You’d do this when your word by word, or phrase by phrase, adapting does not produce a suitably idiomatic translation.
    A retranslation is laid out with vertical word alignments like the adaptations are, but its source text will have a different colour, and above each word will be an asterisk (to remind you that this is a retranslation, and it is not stored in the KB). The words of the retranslation are just displayed one after another under the source text words that were selected originally, and so there is no meaningful relationship between the source text word and the target text word underneath it. If a retranslation is longer than the original selection, Adapt It will automatically add extra placeholders (one or more …. ellipses) in the source text line and hang the extra target text words underneath them.
    h) There are buttons on the command bar to remove a placeholder, to delete or edit a retranslation, or to undo a phrasal merger. The button for each such task is to the right of the button which creates the placeholder, makes the retranslation, or merges words into a phrase, respectively. The retranslation option also has a third button for editing an existing translation – first select any source text word in the retranslation to be edited, then click the button to get the retranslation dialog back open so you can edit the retranslation contents.Those eight techniques are sufficient for getting to a successful translated equivalent to whatever source text you entered – whether you are adapting scripture, or non-scripture. Adapt It has heaps of extra features of course, but you don’t need those extras for the basic task of producing a translation of something.
  8. To get your finished translation out of Adapt It, the way to do it is to use the Export-Import menu. You click the Export Translation Text… item. A dialog will show and the text type of export will be already selected – so click OK and you’ll see a dialog for naming the export file (you can change the destination folder here if you wish) – supply your desired name and click the Save button.
  9. Documentation: every Adapt It installation contains some documentation files. There is an Adapt It Tutorial which is a text document with tables within it, which takes you through the setup process, and the above eight workflow techniques. Many people find Adapt It intuitive and easy to learn and use, so don’t be afraid to skip any of this documentation stuff if you think you get the idea already. There is also an Adapt It Quick Start document, which is worth reading and maybe you should have open in a web browser (it’s an html document) so you can refer to it as you learn how to do things. It gives the steps for many common tasks. There is also an Adapt It Reference which is about 70 pages of detailed documentation – very few people bother to read this, but it documents all the features, and includes screenshots.
  10. Where to download Adapt It?  In your web browser go to   http://adapt-it.org/  and download the Windows installer. A Macintosh installer is also available there. If you prefer to use Linux, use a package manager to download it; instructions are at http://packages.sil.org/
  11. To get going, assuming you are on a Windows machine, you’d do this the following.  On Macintosh or Linux the first few steps would be a little different, but then the rest are the same.
    a) Make sure that you have a web connection open – because Adapt It will want to automatically install the GIT distributed version control software as part of its install process. While not essential for successful use of Adapt It, it is valuable for supporting backups and storing ‘snapshots’ of the state of an adaptation document, and for restoring earlier states of the document if wanted, etc. You use this with the File > Save and store in history   command when Adapt It is running.
    If you install while a web connection is not open, the Adapt It will still work, but the document history & backups feature will not be supported.
    b) Download the Adapt It installer.
    c) Double-click the  installer. Accept the default options.
    d) Launch Adapt It
    e) The initial window size will be too small to be useful, but continue in the wizard to set up a project using the desired source and target language names.
    f) Cancel out of the wizard at the Document page. Then resize the Adapt It window to whatever size you want for future work.
    g) Exit from Adapt It. This causes configuration files (a ‘basic’ one, and a project-specific one) to be constructed and written to disk. The configuration files store your session preferences so they can be restored at next launch – such as window location and size. (You can resize the window at any time, by the way, as you work.)

At this point you are ready for work.
Prepare a plain text source text file; take note of where it is (or put a copy in the __SOURCE_INPUTS folder (within the project folder), launch Adapt It, open the project, click the <New Document> item at the Documents page of the wizard, navigate to wherever your source text input file is, select it, and click Open.
Adapt It will lay out the source text in ‘strips’ (groups of horizontal lines), and piles (piles are ‘vertical’ storage elements – top one is source text, next down is target text, and there can be other things too – but you’ll not need them (i.e. glosses line, and a free translations line)).
The phrasebox will start off at the first word. Begin adapting, and don’t forget to Save periodically. (Adapt It will automatically do a Save every 10 minutes if you forget.)  Explore the menu choices, particularly the Preferences… choice on the Edit menu.

Advice for starting an Adaptation project