Translation Guidelines

Introduction

Here you will find recommendations, hints, observations, and policies which will hopefully help you to make better translations for Amiga applications.

Every language has its own peculiarities and it is not possible to cover them here. Instead the aim is to reveal the stumbling blocks common to all translators and how to best avoid them.

Localization

On AmigaOS every application appears in the language which the user has selected as the system language in the Locale preferences editor. In order the application to do that, it needs to be localized (translated).

Three files are used in the localization process:

1. a catalog description file (a .cd file)
2. a catalog translation file (a .ct file)
3. a catalog file (a .catalog file)

Catalog Description File

A catalog description file is a specially formatted text file which is provided by the application developer. It lists the application's built-in strings.

Catalog Translation File

A catalog translation file is a specially formatted text file which contains the localized strings for the application. You need to create the initial file from the catalog description file with CatComp tool. Once created, you can edit the file with any text editor to make the translation.

The first 3 lines of the catalog translation file (a .ct file) must be as follows:

## version $VER: <application>.catalog <ver>.<rev> (<dd>.<mm>.<yyyy>)
## language <language>
## codeset <mibenum>

Replace <application> with the name of the application for which the catalog file is. <ver> should be replaced with the catalog version number. The version number should be the same as the catalog description file's (.cd file's) version number. The catalog revision is written in place of <rev>. You should increase the revision number every time the catalog translation file has been updated.

Replace <dd>.<mm>.<yyyy> with the catalog translation file's release date.

The name of the language for which the application has been translated to (catalog translation file's language) goes in place of <language>. Note that the language name must be in English and in lower case letters.

<mibenum> number tells which character set is used in the catalog translation file. To find the correct MIBenum number for your language, see file "L:Charset/character-sets".

Catalog File

A catalog file is a data file for the application which contains the localized strings. Create this file with CatComp tool from the catalog translation file.

Making the Translation

The default built-in language in all Amiga applications is English. Thus the translation is always from English to your language.

The key to quality translation is an English to your language computer dictionary and how well you master your own written language. You are only as good as your dictionary and your written language skills are.

Get a good dictionary or create your own. The dictionary is essential for unified translations across the system. Without it there will be small differences between applications and the operating system on how the same functions are expressed. All of the translations are understandable but the user experience is incoherent which is undesirable.

Develop your written language skills. Although application strings are mostly short, hardly sentences, you still have to be able to write grammatically correct, error free, and fluent text.

Do not use spoken language expressions and words. They will give the user an unprofessional impression of the application and may lead to misunderstandings and confusion. Respect the user and aim for clear, informative, and polite expression. There is no need for insulting the user for causing an error or trying to be funny.

Machine translation systems are good for creating quick and rough translations for large projects but should be avoided as the only translation method. Both a simple word replacing system and a more sophisticated AI assisted translation system produce more or less low-quality and inaccurate translations. This is because they do not consider the context, cultural differences, and language nuances. It is okay to use machine translation systems but a human should always finalize the translation.

If your text editor has an automatic spelling and/or grammar checking, use it. It will spot even the smallest errors which can easily be missed by a human.

If the application developer allows you to translate menu shortcuts, think twice before translating them. My experience is that translating them do more harm than good. There are universal menus and menu items which appear in nearly all applications (Cut, Copy, Paste, Save, About, Iconify, Quit, etc.). If your translation changes even one of those unifiedly used shortcuts, it is possible that the user will prompt functions unintentionally.

Gadgets have keyboard shortcuts, too. They are marked with an underscore in the gadget's text. For example, button texts

_Edit

E_xit

appear as an Edit button which keyboard shortcut is E, and as an Exit button which keyboard shortcut is X.

The best shortcut key is the gadget text's first letter. The further the letter is from the gadget text's beginning, the awkwarder it is for the user to read the shortcut. If the shortcut moves near the end of the gadget text, consider removing the shortcut entirely.

Format Specifiers

Sometimes the strings to be translated contain cryptic markings, such as "%s" and "%ld". These are format specifiers. When the application runs and a translated string will be displayed, the application replaces the special markings in the string with variable values. The different markings tell what type of a value will replace the marking and how it will be replaced.

The genaral format of a format specifier is:

%[<position>[<case>]$][<flags>][width][.<limit>][<length>]<type>

<position>	The argument's original position in the string
<case>	U = force the first letter uppercase, L = force the first letter lower case
<flags>	Justification: - = justify left
<width>	Field width. If the first character is 0, the field is padded with leading zeros.
<limit>	The maximum number of characters to output from a string. Valid only for %s and %b.
<length>	Number bit width: h = 16-bit numeric value (short) l = 32-bit numeric value (long) ll = 64-bit numeric value (long long)
<type>	Data type: b = string of bytes (BSTR) c = character d = signed decimal D = signed decimal using locale's formatting conventions p = pointer (32-bit memory address) s = string u = unsigned decimal U = unsigned decimal using locale's formatting conventions x = hexadecimal number with lowercase digits X = hexadecimal number with uppercase digits

From the translator's point of view, the relevant information in a format specifier is the data type: is it a character, a string, or some number. To find out the data type, search for letter b, c, d, D, p, s, u, U, x, or X after the % or $ sign.

Learn to use the format specifier's position and case arguments since they allow you to avoid capital letter erros and make fluent translations with a correct word order.

To change the order of the parametered words/values in the translation, use the format specifier's position argument. To give you an idea how to reorder the changing values, I will use English in the translated string.

The string which will be translated is:

%d eyes, %d feet and %d ears.

In the translation we want the number of ears to come first, then the number of eyes, and last comes the number of feet:

%3$d ears, %1$d eyes and %2$d feet.

The 3$ refers to the original string's 3rd %d which is the number of ears, 1$ refers to the 1st %d (number of eyes), and 2$ to the 2nd %d (number of feet).

When you wish to capitalize the first letter of the word in your translation, you need to supply the format specifier's location (like in reordering the paremetered words/values) and a letter U:

%1U$s are good for your health.

To force the variable string to lowercase use a letter L:

%1L$s are good for your health.

Testing the Translation

Use CatComp to create a catalog file from your catalog translation file. CatComp will check that the translated strings are not too long (if there are any restrictions set in the catalog description file) and that the catalog translation file syntax is correct and report you of any problems it has found.

Once you have the catalog file for the application, open the application with your localization and carefully test every function of the application. Search for any instances of wrong context, text clipping, spelling errors, or any anomalies.

Pay special attention to the gadgets' keyboard shortcuts. Test them one by one to reveal overlapping. CatComp or the operating system will not give any warning or error message on overlapping keyboard shortcuts. For example, your translation can contain buttons with identical keyboard shortcuts but only one button reacts to the shortcut due to overlapping. Therefore it is vital that you test every shortcut.

Testing is a good opportunity to take screenshots of the localized application for tutorials, web pages, etc.

Resources

Here you can find links to tools, documentation, and resources that are useful for localizing applications:

• CatComp
• [[AmigaOS_Manual:_AmigaDOS_Glossary|AmigaDOS Glossary)
• Workbench Glossary
• Hyperion's Discussion Forum