The constructor portal

In the last section, we explained how to access LARA content. We’ll now show you how to create it. As our running example, we’ll use the first couple of pages of The Little Prince, the English version of Saint-Exupéry’s classic Le petit prince. This is a good book to use since there are translations available in a huge number of language, in particular the original French. We’ll start off by building a very simple minimal version of the content, then we’ll do a few rounds of making it more interesting and elaborate. Here is the text we’ll be working with:

Once when I was six years old I saw a magnificent picture in a book,
called True Stories from Nature, about the primeval forest. It was a
picture of a boa constrictor in the act of swallowing an animal. Here
is a copy of the drawing.

In the book it said: “Boa constrictors swallow their prey whole, without
chewing it. After that they are not able to move, and they sleep through
the six months that they need for digestion.” I pondered deeply, then,
over the adventures of the jungle. And after some work with a coloured
pencil I succeeded in making my first drawing. My Drawing Number One.

It looked like this:

I showed my masterpiece to the grown-ups, and asked them whether the
drawing frightened them. But they answered: “Frighten? Why should anyone
be frightened by a hat?” My drawing was not a picture of a hat. It was a
picture of a boa constrictor digesting an elephant. But since the grownups
were not able to understand it, I made another drawing: I drew the inside
of the boa constrictor, so that the grown-ups could see it clearly. They
always need to have things explained.

First, open an editor, create a new file, and copy and paste the above text.

Note

The LARA portal supports several file formats. Most people will probably prefer to use Microsoft word and save the text as a docx file. If you are familiar with these tools, another good solution is to use Notepad++, TextEdit, or some other editor which supports UTF-8 well, and save as a UTF-8 encoded .txt file.

Save your text as a file called little_prince_ch1.docx or little_prince_ch1.txt, depending on which editor you used, so that it’s ready to upload when you need it. In the following, we’ll assume you used Word and saved your file as a document called little_prince_ch1.docx.

Then go back to the LARA Portal, but this time click on Creating texts and then on Add new text. You should now get something like this:

You’re going to fill out the form in a way that’s quite similar to what you did for the reader portal. Your Reading language is “English” (that’s the language The Little Prince is written in), and we’ll pick “French” as the value of Translation language, since we’re planning to put in French translations later on. Enter a content name like “The Little Prince ch 1” and check the box for Use automatic tagging - we’ll see what that means in a minute. A little confusingly, your screen should now change so that it looks like this:

Next, hit the button opposite Upload plain text. You’ll get the usual kind of file navigation box, where you need to find the little_prince_ch1.docx file you saved earlier. Locate it and hit Open:

Your screen should now look something like this, where the portal has confirmed that it got the file:

Now hit Tag Raw Text. The screen should confirm that everything worked, and show you more controls:

For the moment, let’s not worry about most of the controls. Just go to the bottom, check Use automated tagged text file generated with Portal tagger, and then hit Create Resources just under it. The portal will do a lot of work here getting things ready for you to add audio and translations - but since we’re saving that for the next version, we’re going to ignore it. So we’ll skip the Fill out resources tab for now and move directly to the Create pages tab:

Hit Create Pages. The portal should confirm that it worked:

Now click Preview pages. Your LARA pages should open in another tab of your browser and look like this:

As you can see, this is very basic compared to Peter Rabbit - just text, nothing else. But you can at least click on words and see where they have occurred. For example, if you click on “saw” in the first sentence, you should get:

If you got this far, congratulations! You have just built your first LARA resource. Next, let’s see how we can improve it.

Adding audio and translations

In the second version of our Little Prince example, we’re going to add audio and translations. You can create audio in two ways, either by recording it using a human voice or by using a TTS engine. We’ll start by using a TTS engine to create the words audio. Near the top of the screen, set Audio type for words to TTS:

Choose the TTS engine and the voice from the menus a little further down:

Now click Make resources at the bottom, and when that’s finished go to the second tab, Step 2: fill out resources:

select Recording at the bottom:

and click on Click here to generate words tts file. The portal will pause for a couple of minutes as it generates the TTS files. When it’s finished, you should get a confirmation:

Go to the third tab and do Make pages as before. Now when you preview the pages, you should be able to click on individual words and listen to TTS audio.

We could do the audio for the segments (sentences) the same way, but instead we’re going to record it manually using the LiteDevTools recording tool. If you don’t already have a LiteDevTools account, start by going to the LiteDevTools homepage and signing up. It’s free and will take about a minute. Then go back to the LARA Portal, and click on Creating texts and then on My LARA texts. You’ll get a screen showing all your LARA projects. If this is the first time you’ve used LARA (I have done this example pretending to be an imaginary user called testlara), you’ll only have one project:

Click on the Edit project icon for your project. You’ll be back in the Create Resources screen:

In the menu Assign recording voice for segments, select the userid for your new LiteDevTools account:

Also, choose a value in the Word Translations Model line. You’ll soon see what this is for. Let’s start by picking surface word type, since it’s the simplest option.

Hit Create resources at the bottom to save your changes and get things set up for the next step.

Go back again to the Fill out Resources tab and open the Recording tab. This should give you a link to go to the recording platform:

Click on the link, which should open the LiteDevTools homepage in another tab:

Log in using your new account, then click on Available tasks under Recording. You should see a list of tasks. There should be one for the resource you’re constructing, that looks something like this:

I click Go to task on that line, and get a screen that looks like this:

There’s a line for each word I need to record. I hit the Record button for that line, speak, and hit it again to stop recording. To listen to what I’ve recorded, I hit the Play button, and if I don’t like it I can record again. I can exit at any time and then come back later to resume. I record all the segments. When I’ve finished, I go back to the portal, and proceed to the Create pages tab. As I did last time, I hit Create pages. The portal confirms that it found everything and created the pages. I can again click on Preview pages to look at the result:

Now we have a loudspeaker icon after each segment, and when we click on it we can hear the audio we just recorded.

Finally, we’ll add translations. Go back to the second tab, open Translations, and click on the icon opposite Segment translation under Fill out translations online:

You should get a screen that looks like this:

I chose this text because it’s the English version of a well-known French book. I google around a bit until I’ve found a PDF of the French original, then I cut and paste the French. The result looks like this:

If you know French, you’ll see that the result is sometimes only approximate, due to the fact that the English translation is quite free, but we won’t get into that now. Click Save and exit to go back to the Fill out resources tab. Now click on the icon immediately next to Type translation. You’ll get a screen that looks like this:

As before, you need to enter a translation for each word. It’s often difficult to decide what a good translation is without knowing the context. If you hover your mouse over the word in the left-hand column, you’ll get a popup showing you some example contexts. Use those to fill in the translations:

When you’ve finished a page, use the controls at the bottom to move to the next one.

At the end I exit, go back to the third tab, and make the pages again. Voilà! Now I can hover the mouse over a word to get audio and translations, I can hover over a loudspeaker to see a translation of a segment, and I can click on a loudspeaker to get audio for a segment.

Word token translations

If you’re fussy about the quality of your translations, there’s a thing you can do to improve them. A constant problem when translating from English to French is that French has gender, but English doesn’t. So for example “a” sometimes needs to be translated as “un” and sometimes as “une”. Similarly, French verbs have more forms than English verbs, so “have” could be any one out of “avoir”, “ai”, “as”, “avons”, “avez” and “ont”. Also, many common French words like “de”, “le” and “ne” need to be shortened to “d’”, “l’” and “n’” when then come before a vowel.

You can fix these and similar problems by using the Word token translation model, which lets you assign an individual translation to each separate word in the text. You start by going back to the “create resources” screen and selecting surface word token in the Word Translations Model line:

Then hit the Create resources button and wait for processing to complete. When it’s finished, go to the “fill in resources” screen and it should look like this:

Note that you’ve now got a control next to Token translation. We’re going to use that in a moment, but first press the right-hand button in the Type translation row:

This uses the word translations you’ve already written to fill in a rough draft of the word token translations. When processing has finished, click the Token translation button, and you should see a screen that looks like this:

The layout here is that lines are in groups of three, one for each segment. In each group, the first line is the source text, here in English, and the third line is the segment translation, here in French. The middle line is the word translations, which have initially been filled in using the word type translations. You can edit the middle lines to improve the quality of the French, producing something like this:

Go back to the create pages tab and remake the pages, and you’ll see your improved translations when you hover your mouse over the words.

Flashcards

Now that you’ve added translations and audio, it’s easy to add flashcards too. Go back to Create resources and look near the bottom of the screen:

These controls are to say which kinds of flashcards you’re going to enable for your text. Not all of them will be possible. Here are what the choices mean:

• Word translation: lemma translation The question is a lemma in the L2 (the text language), the answers are translations of the lemma in the L1 (the student language). To use this option, you need to have chosen the lemma translation option for Word translations model and filled in the translations.

• Word translation: token translation The question is a word in the L2, the answers are translations of the word in the L1. To use this option, you need to have chosen the token translation option for Word translations model and filled in the translations.

• Audio translation The question is a spoken word in the L2, the answers are translations of the word in the L1. To use this option, you need to have chosen the token translation option for Word translations model, filled in the translations, and recorded audio for the words.

• Signed video The question is a signed video for a word, the answer are words. To use this option, you need to have chosen the Video annotation option under Advanced options and recorded sign language video for words.

• Sentence with gap The question is a sentence with a gap, the answers are words that might fill the gap. You can always use this option.

For “The Little Prince ch 1”, we’ve got token translation and audio for words, so we can check the second, third and fifth options:

As usual, hit Create resources to save your choices. Now open Exercises > Flashcards from the menu on the left. You should see “The Little Prince ch 1” among the sets of flashcards offered:

Hit Take the test, and you should see the choices you selected:

If you choose e.g. “token translation”, you should get flashcards that look like this:

Editing the tagger output

Next, we’re going to look more closely at the file produced by the tagging step, and show you how to edit it to correct tagging errors, divide the text into pages, and add pictures.

Go back to the Create resources tab and click on the green button opposite Automatically created tagged text. This will let you download the file produced by the tagger:

The file should be called Tagged_little_prince_ch1.docx or Tagged_little_prince_ch1.txt depending on which file format you chose. Save and then open it with Word or Notepad++ as appropriate. You should see something like this:

Once when I was#be# six years#year# old I saw#see# a magnificent picture in a book,
called#call# True Stories#story# from Nature, about the primeval forest.|| It was#be# a
picture of a boa constrictor in the act of swallowing#swallow# an animal.|| Here
is#be# a copy of the drawing.||

In the book it said#say#: “Boa constrictors#constrictor# swallow their#they# prey whole, without
chewing#chew# it.|| After that they are#be# not able to move, and they sleep through
the six months#month# that they need for digestion.”|| I pondered#ponder# deeply, then,
over the adventures#adventure# of the jungle.|| And after some work with a coloured
pencil I succeeded#succeed# in making#make# my#i# first drawing.|| My#i# Drawing Number One.||

It looked#look# like this:

I showed#show# my#i# masterpiece to the grown-ups#grown-up#, and asked#ask# them#they# whether the
drawing frightened them#they#.|| But they answered#answer#: “Frighten?|| Why should anyone
be frightened#frighten# by a hat?”|| My#i# drawing was#be# not a picture of a hat.|| It was#be# a
picture of a boa constrictor digesting#digest# an elephant.|| But since the grownups#grownup#
were#be# not able to understand it, I made#make# another drawing: I drew#draw# the inside
of the boa constrictor, so that the grown-ups#grown-up# could see it clearly.|| They
always need to have things#thing# explained#explain#.||

There are two obvious differences compared with the original text. First, many words have a tag after them, placed between two hash signs. So for example “was” has been changed to “was#be#”, and “chewing” has been changed to “chewing#chew#”. The point of this is to group together different forms of the same word: “was”, “is” and “were” all have the same tag after them, “#be#”. If you look at your generated LARA pages, and click on one of these words, you’ll see that the examples on the right do indeed contain all the other ones:

Second, you’ll see a double vertical bar, || in many places. These have been added automatically to separate the text into the segments that you recorded and added translations for in the previous version. LARA has tried to add them at the ends of sentences.

Third, it happens surprisingly often that the process of turning a piece of text into LARA form reveals obvious inconsistencies in spelling. A good way to look for them it to click on Alphabetical index at the bottom of a concordance page and look for similar words that have ended up close to each other. If we do that here, we notice this section:

It looks like the editor was careless and didn’t notice that “grown-up” was spelled both with a hyphen and without.

You may disagree with LARA’s judgements about both tags and separators (indeed, sometimes it will be plain wrong). Here, I’m not sure I like the way it’s tagged “my” as my#i#. A grammarian will tell you that “my” is the possessive form of “I”, but this may not be the best way to help someone who’s learning English. I definitely don’t like the way that “boa” and “constrictor” have been listed as separate words. It’s a single word, “boa constrictor”. I’d rather not have the separator after “Frighten?”. And the two different spellings of “grown-up” are obviously unacceptable. We can correct all these issues by editing the text so that we have the following:

Once when I was#be# six years#year# old I saw#see# a magnificent picture in a book,
called#call# True Stories#story# from Nature, about the primeval forest.|| It was#be# a
picture of a @boa constrictor@ in the act of swallowing#swallow# an animal.|| Here
is#be# a copy of the drawing.||

In the book it said#say#: “@Boa constrictors@#boa constrictor# swallow their#they# prey whole, without
chewing#chew# it.|| After that they are#be# not able to move, and they sleep through
the six months#month# that they need for digestion.”|| I pondered#ponder# deeply, then,
over the adventures#adventure# of the jungle.|| And after some work with a coloured
pencil I succeeded#succeed# in making#make# my first drawing.|| My Drawing Number One.||

It looked#look# like this:

I showed#show# my masterpiece to the grown-ups#grown-up#, and asked#ask# them#they# whether the
drawing frightened them#they#.|| But they answered#answer#: “Frighten? Why should anyone
be frightened#frighten# by a hat?”|| My drawing was#be# not a picture of a hat.|| It was#be# a
picture of a @boa constrictor@ digesting#digest# an elephant.|| But since the grown-ups#grown-up#
were#be# not able to understand it, I made#make# another drawing: I drew#draw# the inside
of the @boa constrictor@, so that the grown-ups#grown-up# could see it clearly.|| They
always need to have things#thing# explained#explain#.||

The only thing that’s maybe not obvious here is the @ signs: LARA use them to show that a phrase, here “boa constrictor”, should be treated as single word. Note that when it appeared in the plural, we needed a tag after it, so @Boa constrictors@#boa constrictor#. We upload the edited version of the text using the button at the bottom of the create resources screen:

When we produce a new set of LARA pages, we see that that “boa constrictor” is indeed treated the way we intended:

Note that if we want everything to carry on working correctly, we’ll need to add a translation for the new word “boa constrictor”, and record audio both for that and for the new segment we made by taking out the separator after “Frighten?” LARA has set everything up for us in the translattion windows and LiteDevTools, so this is quick: we just need to do the new items.

Adding pages, headings and images

We now have all the content in place, but it still doesn’t look very nice. Let’s do something about that by dividing it into pages, adding a heading at the beginning, and putting in these three well-known images:

The primeval forest

My drawing number 1

My drawing number 2

First, we need to get the three images. We cut and paste them from one of the many copies of The Little Prince available on the web, and save them as the_primeval_forest.jpg, drawing_number_1.jpg and drawing_number_2.jpg. Our layout is going to be simple: we’ll have a title page with the title and author, and three more pages, with a picture on each page. The new version of the tagged LARA text looks like this.

<page>
<h1>The Little Prince||</h1>
Antoine de Saint-Exupéry||

<page>
Once when I was#be# six years#year# old I saw#see# a magnificent picture in a book,
called#call# True Stories#story# from Nature, about the primeval forest.|| It was#be# a
picture of a @boa constrictor@ in the act of swallowing#swallow# an animal.|| Here
is#be# a copy of the drawing.||
<img src="the_primeval_forest.jpg" width="416" height="196"/>||

<page>
In the book it said#say#: “@Boa constrictors@#boa constrictor# swallow their#they# prey whole, without
chewing#chew# it.|| After that they are#be# not able to move, and they sleep through
the six months#month# that they need for digestion.”|| I pondered#ponder# deeply, then,
over the adventures#adventure# of the jungle.|| And after some work with a coloured
pencil I succeeded#succeed# in making#make# my first drawing.|| My Drawing Number One.||

It looked#look# like this: ||
<img src="drawing_number_1.jpg" width="432" height="124"/>||

<page>
I showed#show# my masterpiece to the grown-ups#grown-up#, and asked#ask# them#they# whether the
drawing frightened them#they#.|| But they answered#answer#: “Frighten? Why should anyone
be frightened#frighten# by a hat?”|| My drawing was#be# not a picture of a hat.|| It was#be# a
picture of a @boa constrictor@ digesting#digest# an elephant.|| But since the grown-ups#grown-up#
were#be# not able to understand it, I made#make# another drawing: I drew#draw# the inside
of the @boa constrictor@, so that the grown-ups#grown-up# could see it clearly.|| They
always need to have things#thing# explained#explain#.||
<img src="drawing_number_2.jpg" width="344" height="116"/>||

When we upload it again, we get a new request from the portal asking for the images. We zip up our three images in a file called little_prince_images.zip and upload them using the Upload button opposite Embedded image. The portal confirms. Then we hit Create resources as usual. When it’s finished that step, we go to Create pages and remake the pages. As we hoped, we see we’ve now got the text divided into four pages with images:

Using the tagging error feedback file

We’ve so far neglected an obvious problem: there’s always the possibility that when you edit the tagged file you’ll make a careless slip and create a malformed tag. Most often you’ll omit a # somewhere, so your hashtags don’t balance. For example, let’s say that the last version of “The Little Prince ch 1”, had ended up like this. There’s an error… maybe you can already see it?

<page>
<h1>The Little Prince||</h1>
Antoine de Saint-Exupéry||

<page>
Once when I was#be# six years#year# old I saw#see# a magnificent picture in a book,
called#call# True Stories#story# from Nature, about the primeval forest.|| It was#be# a
picture of a @boa constrictor@ in the act of swallowing#swallow# an animal.|| Here
is#be# a copy of the drawing.||
<img src="the_primeval_forest.jpg" width="416" height="196"/>||

<page>
In the book it said#say#: “@Boa constrictors@#boa constrictor# swallow their#they# prey whole, without
chewing#chew# it.|| After that they are#be# not able to move, and they sleep through
the six months#month# that they need for digestion.”|| I pondered#ponder# deeply, then,
over the adventures#adventure# of the jungle.|| And after some work with a coloured
pencil I succeeded#succeed in making#make# my first drawing.|| My Drawing Number One.||

It looked#look# like this: ||
<img src="drawing_number_1.jpg" width="432" height="124"/>||

<page>
I showed#show# my masterpiece to the grown-ups#grown-up#, and asked#ask# them#they# whether the
drawing frightened them#they#.|| But they answered#answer#: “Frighten? Why should anyone
be frightened#frighten# by a hat?”|| My drawing was#be# not a picture of a hat.|| It was#be# a
picture of a @boa constrictor@ digesting#digest# an elephant.|| But since the grown-ups#grown-up#
were#be# not able to understand it, I made#make# another drawing: I drew#draw# the inside
of the @boa constrictor@, so that the grown-ups#grown-up# could see it clearly.|| They
always need to have things#thing# explained#explain#.||
<img src="drawing_number_2.jpg" width="344" height="116"/>||

If not, upload the file to Creating texts > Step 1 create resources and hit Make resources. Now you get a message at the top of the screen that looks like this:

Click on the page icon, top left, and you’ll get a file called ErrorReport.txt which you can download and read. The contents should start like this:

details of error:
PythonRes : --- Environment variables and working directories look okay
--- Environment variables and working directories look okay
*** Error: incorrect tagging in " And after some work with a coloured pencil I succeeded#succeed in making#make# my first drawing."

It’s narrowed down the problem to the segment where you made the mistake. (If there had been several bad segments, it would have shown all of them). When you look at it carefully, you that you missed the hashtag after “succeed”. The segment should really have been as follows:

And after some work with a coloured pencil I succeeded#succeed# in making#make# my first drawing.

You fix the missing hashtag, upload the corrected file, and now it should do what you expected.

Publishing content for the reader portal

As soon as you have reached the point where you have successfully created LARA pages from your text, you can also publish them so that they are available to the reader portal. All you need to do is hit the Publish Resource button in the Create Pages tab. You will get a confirmation:

If we go into the Add text tab in the reader portal, we see it is indeed available:

We can add it, go back to the reading history, and click on the Navigate icon:

When we try it out, we are able to access our new text through the reader portal.