### Translation guidelines

Traditionally, it is hard to translate strings dealing with database technologies. We will first try to outline the difficulties of translation, before proposing writing and translating guidelines. If you are translating pgAdmin3, skip directly to Translating guidelines at the bottom of the page.

### Translation problems

Structured Query Language (SQL) is based on the English language. SQL queries cannot be translated into another language. For example, "SELECT * FROM table_foo WHERE clause;" will not be translated.

Sometimes, the border between the SQL language and the English language is not obvious, because SQL was designed to be close as possible to natural language. For example, there are three possible translations for "Create View" into French, depending on the context: "Crer vue" or "Create View" or "Crer Vue".

The difficulty for the user is to keep in mind the correspondence between English and translated words. In our example "View" is translated into "Vue", which is an easy correspondence (called "translation pair" afterwards). But with dozens of translation pairs like "Trigger/Déclencheur", "Row/Ligne", "Column/Colonne", you need to keep in mind many variations and turn yourself into a translator, which was not the aim of the translation.

In some languages, translation of SQL keywords and database objects do not exist yet, because the community of users is not large enough to define a language consensus. In such cases, translators try to innovate, creating translated words which enrich vocabulary but do not clarify the software interface. The problem is that other translators may not be aware of the new vocabulary, trying to impose their own translation choices.

As a result, translations lack consistency, users have difficulties to find the corresponding SQL keywords to write their queries and finally ... turn to the English version of the software.

Also, we should keep in mind that English has very few grammar rules compared to other European languages, which have complex cases (feminine/neutral/masculine) and derivation (nominative, accusative, dative, etc...). Non-European languages sometimes do not have verbs, adjectives and others aggregate nouns. This causes many translation problems when programmers try to build sentences like "Create a new %s" to handle cases like "Create a new View", "Create a new Table", etc... Let's study this example in more detail:

- "Create a new %s" is translated into French by "Crer nouveau/nouvelle %s" to handle feminine/masculine cases, which is not very obvious. In German, "%s" will not be replaced safely by a noun, because it must be derivated in accusative case. In several European languages, the replacement of "%s" by a noun may fail.

- Some aggregative languages will not express the two words "new %s" separately but will join them, either writing "%snew" or "new%s" in a single noun, with derivation and cases. Hungarian is an example where "%s" constructions will sometimes fail.

- Also, in non-European languages, adjectives like "new" or verbs like "create" may not exist and be expressed by a suffix or a prefix. In such cases, translating "Create a new %s" is simply impossible.

When you start translating pgAdmin3, PhpPgAdmin3 or PostgreSQL into your mother tongue, you will soon notice this kind of problem. The only solution is to define writing and translation guidelines and to stick to them.

### Writing guidelines

We propose a very simple solution based on the idea that a developer/writer should always try to make a clear difference between SQL keywords and natural language. If possible, SQL keywords and database objects should be written in capital letters. For example, "Create a new view" should be written "Create a new VIEW".

Avoid the use of "%s" unless the replaced sting is invariable, like it is the case for a product name,a username, a password, etc... As such, "Successfully connected to host: %s" and "User %s was disconnected" are valid strings.

Never write a string like "Create a new %s" for the reasons explained previously. You should write "Create a new VIEW", "Create a new TABLE", "Create a new INDEX", etc...

### Translating guidelines

Never translate SQL keywords written in upper-case letters for the reasons explained before. In some cases you might even break pgAdmin3 if you do!

Stick as much as possible to words which are close to the original SQL syntax. For example, in French, you may use "vue" for "view", because both words start with the letter "v". Do not choose distant words, like "déclencheur" for "trigger", because entry-level users may not be able to make a good use of the SQL syntax ... and ultimately switch to the English version. Sometimes it's better to simply leave these keywords untranslated, instead of creating a fancy word nobody will recognize.

Please take special care about including all %s and %d variable placeholders correctly. If you make a typo error, the application might crash. On rare occasions, it might be necessary to reorder placeholders. In the following (fictive) example, both parameter positions are exchanged: "Server %s user %s is logged in." could be translated by "L'utilisateur %2$s est connect au serveur %1$s.". At the moment, pgAdmin3 does not require any reorder placehorders, but it might change in the future. Just be aware of it!

Keyboard shortcuts are denoted by a leading "&". For example "&Add", which is translated into French by "&Ajouter", can be triggered from keyboard using Alt + A. Be careful when changing letters, to avoid keyboard entry conflicts within one menu. If you deviate from the original shortcut keys, pgAdmin3 users might have problems remembering shortcuts in both English and translated pgAdmin3 versions. Therefore, be careful creating new shortcuts if you cannot choose the same letter.

Menu strings also contain hard coded shortcuts (Ctrl-X) or function keys (F5). These can be identified by a preceding \t (tab). If appropriate, the modifier key name may be translated (Ctrl-), but the key combination must remain the same in any case, because the behaviour is coded in pgAdmin3 source.

Most forms are not designed with resizing capabilities, because this is quite hard work. The only resizing forms are the function, view and rule property windows. Therefore, you may need to shrink the translated text to the English size. In general, we tried to leave enough space for translation texts, but if you believe there are certain places we should spend more space please let us know.