The Amiga community has always been uniquely active and constructive. Several volunteers have contributed to the creation of new user interface localizations for popular Cloanto packages like Personal Paint, which are designed to work with easily editable external localization modules. This document, inspired by our internal translation guidelines, is dedicated to all the volunteers who are helping Cloanto and other developers and users with their passion and linguistic knowledge. It contains some guidelines to simplify certain choices, avoid unnecessary work, and ensure style consistency and technical functionality.
We do not wish to open a debate or write a book on man-machine interaction. However, we have chosen to follow a specific style in the way our software user interfaces communicate with the user. We encourage all translators to be consistent with this style.
There are different viewpoints on how a computer should communicate in a textual form with the user. We tend to disagree with systems in which machines use the words "I" and "You", as in "I just found an error here", or "You MUST do this" (the use of capitals and imperatives addressed to the user is also arguable). These are not abstract examples: even the German Amiga operating system complains that it "Benötige UNBEDINGT/wieder den Datenträger %s", where "Der Datenträger %s wird unbedingt benötigt" could have done the job. We do not like this use of the first person because:
While we are open-minded about a future in which the difference between machines and self-conscious biological entities blurs away, for our current software we prefer messages like "An error was found in...", or "This can be done by...", in which the style is self-descriptive, impersonal, and attention is focused on the action or the message object. For messages, please try to use a style in which actions become the subject or the object. The computer does not "speak" in the first person, e.g.: not "I will delete the text", or "You will loose the text", but "The text will be lost". Writing in an impersonal style may appear to be difficult at first (a bit like writing in a genderless style, where an author does not use "he or she" all the time), but once the basic constructions are set, one tends to proceed very smoothly. For menus and commands, try to formulate the texts so that the user does not select actions in imperative form, if the language allows for alternatives such as infinitive. It is not possible to briefly set one rule for all languages: infinitives may do the job in one language, whereas passives may be the standard in another. In any case, consistency has priority: please use only one style. Prefer clear, simple, short sentences wherever possible.
If there is no way but to have the computer address the user with an imperative, please do not forget that there are words like "please". Style is also a matter of... style. If the user is to be addressed directly, the most formal and polite of all courtesy forms should be considered (e.g. German "Sie" or Italian "Voi", but in these languages it is easy to reformulate a sentence in an impersonal way).
Style guides from companies like IBM, Apple and Microsoft are very interesting reading. However, at least in some languages, these companies have followed different directions. We think that IBM often went too far in translating almost every single English word in languages like Italian, creating new meanings for Italian words which had a widely used English standard name. Apple, on the other hand, often uses a style in which the computer speaks in the first person as if it were the user's best friend. We prefer to avoid these extremes, accepting the use of English words which have no well-known local equivalent, and preferring an impersonal style to an artificially friendly and personal style.
We recommend to use the English user interface as a translation basis, perhaps looking at various translations for inspiration and consistency. When using the English texts as a source, please note that the use of capital initials for words appearing in titles is due to the English style of writing titles, and is not applicable to all languages.
Before beginning the translation, please make sure that you are going to work with the latest version of the software. If you do not have it, you can get one for free from us. We do offer free software to all volunteers who participate in a new localization. In any case, we would recommend to contact us first, in order to avoid possible duplications of efforts.
Once the translation is complete, we would ask that you send it to us, rather than uploading it directly to sites such as Aminet. This allows us to test it in different screen resolutions, test the keyboard shortcuts, and create versions of the same translation for older program versions, which we also support. Then we will prepare all the files in a format consistent with the other files, and upload everything to the "biz/cloan" directory on Aminet. Your name and E-mail address will remain in the "Author" field, and you will also receive the latest version of Personal Paint from us.
If you do not wish your translation, your name and/or your E-mail address to be freely distributed, please express this explicitly.
This section explains some technical aspects of the user interface files of Personal Paint. Amiga programs like ColorType, Personal Fonts Maker 2 and Personal Write use similar formats.
To make the user interface files easily editable with standard tools and compatible with all versions of the operating system, we chose to store them as plain text files, instead of using the Amiga locale format (which, by the way, was introduced after our main packages were first released). For Personal Paint, these files are stored in the "PPaint_Prefs" directory, located in the program installation directory. The user interface files are named "UIText.xxx", where "xxx" indicates a three-letter language suffix. Personal Paint 7 currently recognizes the following suffixes:
ID LANGUAGE SUFFIX00 English .eng 01 German .deu 02 Italian .ita 03 French .fra 04 Spanish .esp 05 Dutch .hol 06 Swedish .swe 07 Danish .dan 08 Norwegian .nor 09 Finnish .fin 10 Portuguese .prt 11 Polish .pol 12 Hungarian .hun 13 Czech .cze 14 Slowak .svk 15 Slovenian .svn 16 Croatian .hrv99 Custom .custom
The ".custom" file name suffix is associated to the menu item with the same name, which was designed to support languages not defined by other suffixes. The ID value is used for the LANG program setting, which is usually included in the "Startup_A.set" startup setting file to determine the program startup language. If the LANG parameter is not set, or if it is set to 0xFFFFFFFF, then the software will try to run in the current system default language, and fall back to the first available language, in order of ID, if the desired language file is not found.
Personal Paint, like most Cloanto applications, can change user interface language while it is running. The software can also reload the current language. This is useful for interactive testing. When loading a user interface file, Personal Paint performs some simple length-checks and issues warning messages to indicate texts which are too long or should be made splittable. While this feature is useful for quickly testing a file as it is being edited, the only guarantee that the file will actually work properly is to manually display all menus and requesters in the lowest possible screen resolution (320x200 for Personal Paint and other graphics packages, 640x200 for Personal Write). It is also important to check that there are no conflicts with the keyboard shortcuts in the various requesters, especially with common gadgets like Proceed, OK and Cancel.
The user interface files can be loaded, modified and saved again as plain text with any text editor or word processor (e.g. with the "Load Document" command of Personal Write). If Personal Write is used to edit the text, "TAB step" should be set to 8, and "TABs in output file" should be set to "Automatic". Both are the default values for these settings.
A few very important rules must be followed to create a new file with the user interface texts. The easiest way to create such a file is to use an existing file as a point of departure. The file must be stored as a plain ASCII text file, without control sequences. TAB characters separating the shortcuts from the menu text must be preserved. Each line in the file must contain either one or more valid texts (separated with TABs), a comment, or no characters at all (blank line used as an optical separator). Leading space and TAB characters are skipped. Comments begin with a ';' (ASCII decimal code 59) sign and end at the end of the line. Each line (including the last one) must terminate with a LF character (ASCII code 10).
An optional keyboard suffix may be written, enclosed between the "< >" (less than and greater than) signs and separated by one or more TABs, after each menu item text. The shortcut must be in the <Qualifier-Key> format. The qualifier field is optional. The qualifiers which are supported are: "Shift", "Alt", "Ctrl", "Amiga", and "Num" (numeric keypad). For example, "<Shift-Up>" would mean "this command should be executed by pressing the <Cursor Up> key while <Shift> is held down."
The keyboard shortcuts at the end of the file are associated to functions which have no menu-equivalent.
Double assignments of the same shortcut should be avoided, as only one menu item can be associated with a key combination. <Ctrl> and <Alt> have special meanings in in the Screen Grab function and in combination with the left mouse button. These local uses cannot be redefined.
"Left", "Right", "Up" and "Down" are used to indicate the four cursor keys. Other textual representations include: "SP", "Tab", "BS", "Del", "Help", "Esc" and "F1" to "F10".
When input by the user, lower case letters are treated differently than capitals in cycle gadgets, proportional gadgets and listviews. The former force the gadget to "go forward", while the latter make it "go back". In other gadget types, upper and lower case letters are treated as identical.
<Shift> should not be used as a qualifier for keys which already have a system-defined shifted representation (e.g., <Shift-a> is wrong, while <A> is correct). For commands which must remain accessible in a text editing session, only function key shortcuts and shortcuts having an <Amiga> key qualifier should be used. Other keys would be interpreted as a character to be typed, rather than a command to be executed.
The texts should be designed and tested in such a way that all menus and requesters can be displayed in a low resolution screen 320 pixels wide and 200 lines tall. Message texts ("TMS" section of the file) which exceed the horizontal limit may be made "splittable" by inserting underscore characters ('_') where Personal Paint may bring the text to a new line, if necessary. Normally, these characters are automatically replaced with spaces.
Due to the new Animation features, more menus have to share the same horizontal screen space. The underscore character can be used to indicate where a menu title text can be abbreviated (this may be necessary when using low-resolution screen modes). For example, the program could abbreviate "Anim_ation" to "Anim.", should this be necessary. Otherwise, the menu would be displayed normally ("Animation").
The underscore character can be used in sections TXW (window texts) and TXG (gadget texts) of the user interface text files. The character following the underscore will be underlined and used as a keyboard shortcut, in accordance with the Amiga user interface specifications. Supported gadget types are: cycle gadgets, checkboxes, sliders, listviews (scrollboxes) and action gadget texts (e.g. "_OK").
The user interface text files contain a version number, used to identify the release version of the text file. This number is read by Personal Paint, and should normally not be changed.