ADRIFT Language Resource

From IFWiki

An ADRIFT Language Resource, or ALR, is a text document with the file extension .alr that can be imported into the ADRIFT Generator. It contains a list of all the words and phrases you want to replace in the game's output stream with alternative words and phrases. The ALR is a valuable resource for writing advanced descriptions in ADRIFT games that would be otherwise impossible. ALRs were introduced with the release of ADRIFT 3.90 on 01-Jan-2001.

# +--------------------------------------
# BUY
Buy what?|Acheter quoi?
I don't think|Je ne pense pas que:
is for sale|est en vente
You can't buy |Vous ne pouvez pas acheter
I can't buy |Je ne peux pas acheter 
A sample of the French ALR file by Sabine Gorecki.

What are ALR files used for?

To translate from English to some other language

As the name suggests, an ADRIFT Language Resource can be used to help create ADRIFT games in languages such as French, Italian, and Spanish. Since handling of standard commands is hidden from the programmer and default responses like "You can't buy %theobject%." cannot be edited, ALR files are used to translate text just before it's displayed on the screen. This is likely the original intended use for ALRs.

To change ADRIFT's default responses

The ALR can be used to override default responses in English. For example:

You see no such thing.|Either you can't see that, or it's not important.

will replace any "You see no such thing." (the default response) that appears in the Runner with "Either you can't see that, or it's not important."

To vary the text output

ALRs are also used for generating randomized text, or for displaying the nth text string from a list of possible strings. ADRIFT has no concept of lists and arrays in the same way that other authoring systems do, so ALRs have been drafted into providing this sort of functionality. Here's how it works:

Suppose we want the player to have a rank, like "Captain" or "Admiral" that changes as the game progresses. First, define an integer variable, such as myrank that we'll use to hold a numerical value of the rank. We might initialize it to 0, meaning "Ensign", for example. Elsewhere in the game, you'll want to add Tasks that'll change myrank to 1, 2, etc. as appropriate.

Then create the ALR to look something like this:

# List of Ranks (any line starting with # is treated as a comment)
[rank=0]|Ensign
[rank=1]|Lieutenant
[rank=2]|First Mate
[rank=3]|Captain
[rank=4]|Admiral

There's nothing special about the brackets and equal-sign in "[rank= ]" -- we just want an unusual text string that is used just for this purpose, and it might as well be readable as well. If you'd rather match on "<<RANKS[0]>>" or "$RANK0" instead, that's fine, as long as it's unusual and unique.

Then in the appropriate text fields of your game, where you want the rank to appear, you'd use "[rank=%myrank%]" so when myrank is 0, it prints "Ensign", and when myrank is 1, it prints "Lieutenant", and so on.

Congratulations, [rank=%myrank%] Smith! You've done it again!

Creating an ALR file

Use a simple text editor, such as Notepad, to create an ALR file. The important lines in an ALR file are of the form:

oldtext|newtext

which is a directive to replace every instance of the oldtext string with the newtext string just before displaying the text on the player's screen. The pipe-character (|) is used to separate the two strings.

Any line beginning with a hash-character (#) is a comment. Comments are ignored. Blank lines are also ignored. And that's all there is to ALR syntax.

How to add, remove, and extract ALRs to and from your game

ALRs are manipulated via the File menu in the ADRIFT Generator:

  • File|Import|Language Resource - Adds an ALR file to your game. Note that only one ALR can be added to your game at a time; a newer ALR replaces the old one. If you want the effect of two ALRs, you'll have to combine their contents into a single ALR first. If you get a parse error when you import an ALR, it probably means that one of the lines is missing a pipe-character.
  • File|Import|Clear Language Resource - Deletes the ALR data from your game.
  • File|Export|Language Resource - Creates an ALR file from your game. Comments that were in the original ALR file are lost.

Caveats and other fiddly details

  • Stupid matching. Whatever is on the left side of the pipe-character will only match text identical to it. There's nothing fancy about this at all. If you want regular expression pattern matching, you're out of luck.
    • Case is important. "there is" won't match "There is".
    • Spaces are important too. Don't assume word-boundaries are checked. A "here|ici" line will change "Wherever" to "Wiciver" if you let it. Add leading and trailing spaces and punctuation as appropriate so you're matching what you want to match. Don't forget to put the same spacing and punctuation on the right side of the pipe as well.
    • Literal pipe-characters can never be mapped.
  • Longer matches are matched first. Substitutions aren't quite done in the order they appear in your ALR file; the longer left sides are processed first. Only if the left sides are the same length will the matching happen in the same order as in the ALR.
For example, consider this pair of lines:
rock|boulder
red rock|crimson rock
Regardless of the order of these two lines, "red rock" will be displayed as "crimson boulder".
  • No backtracking. Consider these three lines:
blue|black
lagoon|lake
black lake|blueberries
Can you figure out what "blue lagoon" turns into? It becomes "black lake". Because longer matches are processed earlier, the ALR first tries to match "black lake", then "lagoon", then "blue". It doesn't go back and retry a match it's already finished processing.
  • ALR processing happens after %variable% subtitutions. You cannot, for example, put %theobject% into an ALR file and expect it to be replaced by the current value of the theobject text variable.
  • HTML-style codes are interpreted after ALR processing. Feel free to use <b>, <i>, <br>, etc. in an ALR.
  • Polyseme errors. Some common English prepositions don't translate straightforwardly to other languages. Does "about" mean "concerning" or "around"? Does "of" mean "possessed by" or indicate quantity (as in "cup of coffee")? Does "with" mean "together with" or "by means of"? All you can really do about this is try to catch all the less likely forms in the context of a larger phrase so only one possible translation is left for single words.
  • Homograph errors. Some English words might look exactly like words in the target language but with a completely different meaning. You'll want to take extra care that such words don't get translated twice. Fortunately, this is a rare problem.

Links