Building Non-English Artemis Project Web Sites

We're still writing this document. This draft is on line so people can use it for a reference while we get the final version tied up.

Here are the steps for creating a web site for versions of the Artemis Project translated into languages other than English.

1. Decide on a directory name. The name should be mnemonic, such as 'dutch' or 'nl' for Dutch, or 'german' or 'deutsch' for German. Think about it now, because we changing it later will require many hours of work.

   Choose a code that will mean something to a person who speaks the target language; never mind what a native English-speaker might think. For example, we use "nl" (for "nederland") instead of "dutch" for the Dutch version of the Artemis Project web site, and "de" instead of "german" for the the German version. The Spanish version is "es".

2. Ask one of the system managers to create a new directory tree for the new versions of the web documents, starting at the top of the server hiearchy. For example, the German version's directory tree starts at /de/, and the German version of the Artemis Data Book starts at /de/adb/. The Dutch version is /nl/adb/, and the Spanish version is /es/adb/.
3. Get an account in the ASI Web Management System. To do this, fill in the simple form at http://www.asi.org/wsd/. "WSD" stands for "WebSite Director," the web management system from CyberTeams.

   You'll use WebSite Director to create and maintain documents on the ASI web.

4. You can add anything that looks good to the new web site, paralleling the structure of the Artemis Project web site. Just add the new directory at the beginning of the pathname.

   For example, look at the Brief Overview of the Artemis Project documents. You'll find the English version at http://www.asi.org/adb/01/brief-overview.html, and the German version at http://www.asi.org/de/adb/01/brief-overview.html.

   Don't append the language code to file names. Since these files go into a different directory, they can have th the same file names as the English versions. Keeping the same file names will make it much easier to keep track of the documents.

   At the end of this essay you will find a list of documents that seem to be the top priorities for presenting documents in your language.

Presenting the Main Entrance

1. Copy the English version of the main entrance page (/index.html) to the new heirachy. For example, the Dutch version is at http://www.asi.org/nl/index.html.
2. Translate the main entrance text into the new language. To do that, submit a request to MODIFY DOCUMENT, modifying /yourlanguage/index.html. (Substitute the code for your language for 'yourlanguage' in the file name.
3. Make new buttons for the main entrance graphics. You can do this yourself, or ask the web team to do it. Tell the web team what words to use for the text on those fancy buttons, so that the whole main entrance is presenented in the same language.
4. When you are satisfied with the appearance and function of enough of the new web, ask the web team to add a line to the main entrance at http://www.asi.org/ to offer a link to the new version.

Adding and Maintaining Documents with WebSite Director

Now for the tricky part: How WebSite Director does what it does, and what you can do with it. With this new directory setup, you can use WSD's headers and footers, translated in your language wherever it's required. You also can enter document titles in your language.

Tables of Contents

In every directory from /adb on down the hiearchy, WebSite Director automatically maintains the table of contents in the index.html files. Each time a file is added to a given section, WSD will update the index.html in that directory.

There are two key files that tell WSD how to do this: the Summary file, and the Index Template.

Summary File

In each directory, there a file named .summary which contains the paragraphs that appear at the top of the Table of Contents for that section. For example, take a look at http://www.asi.org/adb/.summary and compare the results with http://www.asi.org/adb/index.html. See how it works? Each directory in the Artemis Data Book should have a .summary file. (Many don't; that's another big project we're working on.)

Index Template

The index.html files get formatted according to a template, stored in a file cleverly named 'index.template'. If WSD finds a file named index.template in a given directory, it uses that template. If WSD doesn't find an index.template file, it uses its default template to build the table of contents.

Below is the default index.template file. If you can translate this one into Dutch, we can put a copy of it into each directory in the /dutch hiearchy, and even the index templates will come out right.

I've been bugging Randall to modify WSD so that subdirectories inherit their index templates from their parents. That's another thing on the great list of things to do. Until then, we will have to copy the your version of index.template into each new directory we create.

In the index.template file, you'll see a lot of <$...> tags. Those tags are part of WSD's template processing language. You don't have to learn the template language unless you want to create new templates, but it might be helpful to understand them so you can see what to translate and what not to.

For example, in the 7th line of index.template, you'll see the <$include .summary> tag. That tells WSD to look for a file named '.summary' and include it in the table of contents.

Now, if we translate the English in the above index.template into your language, and create new headers and footers, and use your language for titles in the documents, then the whole table of contents will come out in your language. Pretty cool, eh?

We can also add a note to the index.templates for the your edition, giving a link to the parallel English version. That way, if someone is reading the translation and wants to read a document that hasn't been translated yet, he will have the option of looking up the English version.

Top of the Artemis Data Book, the translated edition

There's one more tricky part. This template looks for information about the parent directory. The top of the Artemis Data Book, /adb, has no parent, so it has its own index.template file. You can look at that file by going to 'http://www.asi.org/adb/index.template'. Use WSD to copy this index.template file in the /dutch/yourlanguage/ directory.

Hiding Files from WebSite Director

We don't want the index.template and .summary files to show up in the table of contents. That's why, in the Document Info screen in WebSite Director, you can set the Index Position of a file to "None".

ASI Online News

The main /index.html document is hard-coded, not generated by WebSite Director. (Every other index.html file is automatically generated by WSD.) However, it does have a program that maintains it -- Cronkite, our newsmonger utility. If you look at the html source for /nl/index.html, you'll see some odd tags: .... Cronkite looks for those tags, and puts its news headlines in there.

Ask Tim Cadell newsmonger@asi.org, who wrote the current version of Cronkite, to modify the program to update your index.html every time it updates the main entrance. He can do this by adding your main entrance to Cronkite's list.

Priorities for Translating Things

To keep track of what you're doing, do things in this order:

1. Main entrance at http://www.asi.org/yourlanguage

   In addition to translating the main entrance page at http://www.asi.org/index.html, you'll need to rework the graphics for the image buttons to create new ones in our language. If you don't have the resources to create these images yourself, ask the ASI Web Team for help.

2. Documents that the main entrance points to

   To find the English versions, follow the links from the main entrance at http://www.asi.org/.

   1. http://www.asi.org/adb/01/04/tour-01.html
   2. http://www.asi.org/adb/06/05/asi_member.html
   3. http://www.asi.org/adb/index.html

      (Need to translate the .summary in this directory.)

   4. http://www.asi.org/adb/10/artemis-project-team.html
   5. http://www.asi.org/adb/06/09/04/index.html

      (Or maybe we could just change this to point at the English version of the ASI Online News? Perhaps a summary in your language with a pointer to the English version?)

   6. http://www.asi.org/util/search.html

      (Our search engine isn't working very well, but when we finally get it going, we could create a new version of this page.)

   7. http://www.asi.org/adb/09/communication-resources.html

      (This one is all about the electronic communication resources -- mailing lists and so on. Maybe we should just point to the English version until we have enough people who would like to have a mailing list just for communicating in Dutch.)

3. Documents listed in the Tour

   See http://www.asi.org/adb/01/04/tour-01.html