REALbasic University Translation Guide
REALbasic University Translation Guide
Created: July 17, 2001
Modified: February 9, 2003
Introduction
If you are reading this document, you are presumably interested in translating the REALbasic University programming columns into another language. This is a guide to assist you in that process.
First, let me thank you for your interest and potential commitment. Translation is complicated and a lot of work, and translating technical material is even worse: I, and your readers, appreciate your effort. This kit has been put together to make the translation process easier for you. It includes tools that automate much of the process, which should help save you time. You don't have to use these tools, but you can if you like.
To translate RBU, you will need the following:
The basic steps you'll take to translate the columns is as follows:
Translation Kit Contents
This kit contains the following items:
The RBU Website Structure
An important part of the RBU website is the structure of the site. It's simple, but a good understanding of the structure is critical for maintaining links to images and pages.
At the root level, there are three key items:
Also at the root level, you should have a separate folder for each column. The column folders are all numbered with a consecutive three digit number, starting with 001.
Within each column folder, you should have an index.html file which is the actual column. Separately in the folder you'll put all the related graphics and resource files for that column.
So a typical RBU website will look something like this:
RBU root:
index.html
images
rbu.css
001:
index.html
graphic1.gif
graphic2.gif
rbuproject1.hqx
002:
index.html
graphic1.gif
screenshot.gif
rbuproject2.hqx
003:
index.html
screenshot.gif
photo.jpg
rbuproject3.hqx
For each new column that you translate, you'll need to create a new, numbered folder, and then upload the column (index.html) and support files into that folder.
The easiest way to work is to create an identical structure on your hard drive. It's important that each column folder be a number and each original text file for the columns be a number.
The RBU Markup System
The RBU columns are written in text-only BBEdit, using a very simple markup system. The markup is basic HTML with the occasional CSS tag. When a column is finished, it is translated into full HTML via the included RBU-2-HTML program.
Since you're not writing these columns from scratch, you really don't need to know much about the specifics of these markup tags, but it might be helpful for you to understand what you are seeing.
RBU uses the header tags <h1>, <h2>, and <h3> to indicated various headlines within a column.
The next most important tag is <tt> -- this is used to highlight REALbasic reserved words, variables, or a single line of REALbasic code.
Next, we've got a special CSS class of the anchor tag: this one highlights a glossary item in a special way. Here's an example of the way that looks:
<a class="glossary" href="../glossary.html#module">module</a>
Glossary tags are used to mark words that are found in the RBU Glossary. Note that the format of the glossary reference is critical to maintain the link: see the BRU Glossary below for more on how to do this correctly.
The <pre> tag is used to highlight REALbasic code snippets. You'll notice there are no special tags within the code itself: RBU-2-HTML does the work of highlighting reserved words and comments within the <tt> tagged text.
There are a few other tags, such as the "In Detail" tables and a special tag for reader letters, but in general you don't need to mess with any of these tags.
Your job should simply be to translate the basic text leaving the tags as is. If you like, translate the text on the comment lines within REALbasic code snippets.
It is suggested that you don't change variable names or other parts of the code as that will break the program.
Using the RBU-2-HTML Program
The RBU-2-HTML program is incredibly simple. You simply drag one or more text files to the main program window and click the "Convert" button. That's it!
Important Note: it is vital you name your original text-only file as the column number. It should be a three digit number with no extension. This is important, as RBU-2-HTML uses this name as the column number (for the page title, etc.). So "024" is good, but "024.txt" is bad.
When a file is converted, RBU-2-HTML will create a new file in the same folder as the original, with the same name as the original except with an .html extension. For instance, "024" would be saved as "024.html" (note that your original file is not modified). You are then free to look at the HTML file in your web browser to see if it converted correctly.
When you are ready to upload the column to your website, you'll want to first rename the column to index.html. You also don't need to upload the original text-only file to the website: only the index.html and the resource files are required.
The most important file is "rbu_template.html" -- it contains the RBU header and footer information. This text is added to every HTML file it generates. The basic English text is included: translate it and include any appropriate reference to yourself and/or your website or company. (Note that the Marc Zeedar copyright and link to the English Applelinks site are required elements for you to be given permission to publish a translated version of RBU.)
Within the template file, two special phrases, "{TITLE}" and "{BODY}" are replaced by the document's title and the column text respectively. Anything else within the template is put into every file generated, so you could frame the RBU data with your own website's normal navigation system or graphical look and that will be repeated for all pages generated.
One final note: there's a "local" checkbox within the RBU-2-HTML window. Ignore it. It defaults to checked and that's the way it should be. This option is only required for the Applelinks version of RBU.
Using the RBU Glossary Program
One of the features of REALbasic University is a glossary page of definitions of various REALbasic terms. The page is designed to be easily updated with new terms, and allows columns to link directly with a specific term.
Within this kit you will find a program, RBU Glossary, which is used to create and edit terms, and which automatically generates the appropriately formatted HTML file.
The program has a simple list of terms on the left. Selecting a term lets you edit the definition on the right. Basic HTML tags (bold, italic, etc.) may be used within the definition. NEW: The "pre" tag is used to mark code and RBU Glossary will mark reserved words of this code just like RBU-2-HTML does.
Note the popup menu at the lower portion of the window. This menu contains a list of all the terms: selecting a term inserts a link to that term within the current definition. This is used to create links between terms.
A Note About Links
Each term is published with a unique anchor tag attached to it. The tag is the term itself. The anchor is all lowercase and no spaces. So the term "Boolean Logic" becomes "booleanlogic" when used as part of an anchor.A typical link to a glossary term might look like this:
This is <a href="#booleanlogic">Boolean Logic</a>. Generally this is all handled automatically for you via the RBU Glossary program and/or established in the original columns. But if you are translating terms, you'll need to replace the English term with the translated term, both in the raw text and within the HREF link. When you do this, make sure the link works properly before uploading the file.
RBU Glossary stores terms and definitions in a text-only file with a simple format. Each line of the file contains the term, a tab character, and the one paragraph definition. You are free to open this file, glossary.data, in a text editor (such as BBEdit) and translate the terms there, but just make sure you don't modify the file format. The file format must be strictly observed. Each line must be a term, a tab, and a definition. That's it.
When you are finished editing the glossary terms, simply launch RBU Glossary and press the Publish button to generate the HTML file. Upload that file to your RBU website's root directory.
Like RBU-2-HTML, RBU Glossary uses a separate template document as the basis for the HTML document it produces. You should edit the template and translate the English text there.
Changes for 2003
The current version of this translation package includes all new versions of RBU Glossary and RBU-2-HTML. This versions include improvements and fix bugs, however, they are also more geared toward the Applelinks version of RBU. You may find they need minor tweaking. For instance, a number of files now generate ".shtml" files instead of ".html" files. These are server-side include (SSI) files and if you're not using SSI, you'll simply need to rename the files.
Also note that because RBU Glossary and RBU-2-HTML now both do syntax marking of code, they need to be in the same folder. I've eliminated the old "templates css" folder and files that were in it: everything is now inside the "templates" folder and the template files are named appropriately (i.e. instead of "template.html" it's now "rbu_template.html"). You'll need to edit these new template files to add your translated code. If you encounter other problems with these new versions, please let me know so I can fix them.
Conclusion
Hopefully this document and this customized RBU publishing system will make your translation job much easier. The idea is for you to concentrate on translating, not messing with ugly HTML. If you have any questions or suggestions, or find bugs in the software, please let me know.
Also feel free to contact me if there's a portion of the text you don't understand, such as when I use an American colloquialism. I'd be happy to help!