Translation guide

From No3wiki

Describes how to translate streber into other languages.

How Translation works in streber

Streber uses translation tables. You can find them in /lang-directory:

   scanLanguages.pl
   de.inc
   de.inc.changes
   _new_.inc
   _new_.inc.changes
   pt-br.inc
   pt-br.inc.changes

There are typically two files for each language. The ??.inc contains the actual translation-table as a associative array. This file looks like:

   <?php
   ...
   $g_lang_table= array(
   
   'English|for language selection'    =>'Englisch',
   'Home|Tab in top navigation'        =>'Home',
   '%s error(s) occured'               =>'%s Fehler is aufgetreten',
   ...
   );
   ?>

As you can see in the example, the orignal string consists of two parts separated by a pipe ( '|' ) symbol. The second part is optional and clarifies the context. Do not translate this ;-)

Behind some lines might be comments starting with "#". You can ignore them.

Inside Streber, strings that require translation are used like this:

   echo __("Home");

The two underscores are actually a function name. This function looks into the translation-table of the current language and searches the Key "Home". If there is one, this one will be used. If not the original string will be used (of cause without the context-part).

Strings containing dynamic attributes contain %s and are built with the sprintf(). Like:

   echo sprintf( __("%s error(s) occured"), __("No")) 

Since the translation for "No" can not be found, it is stored in an internal list of missing language-keys. You can display this list at the footer of each page by adding this line to your customize.inc :

   confChange('LIST_UNDEFINED_LANG_KEYS',true);

Although this might be good for testing a tranlation, it is cumbsersome to get all strings that needs translation. For this I wrote a small perl-script called scanLanguages.pl. It scans all source files in all of the project's directories and looks for strings inside the __() functions. It then looks for languages in /lang/*.inc and writes a list of untranslated strings to files called ??.inc.changes. One file for each language.

If you have translated streber into a language, please check the release of each new version for a ".changes"-file concerning your language and add those keys to your translation.

How to translate Streber into a new language

• Start with a copy of /lang/_new_.inc
• Rename the copy to the shortform of your language (like "uk.inc","es.inc", etc).
• Open the new file with a text editor capable of utf8 editing
• Add your translation into the quotes.
• Save the file
• Open /conf/conf.inc
• Search for "g_languages" and add your language like:

   $g_languages=array(
      'en'=>'English',
      'de'=>'Deutsch',
      'pt-br'=>'Portugese', 
   ); 

• Add the following line to your customize.inc. This will warn you on missing translation keys when testing the translation.

   confChange('LIST_UNDEFINED_LANG_KEYS',true);

• For testing make your language the default-language or adjust your profile accordingly. To customize.inc add:

   confChange('DEFAULT_LANGUAGE','??');   #<- replace ?? with your new language

• Start using Streber and check your translation. Esp. check for layout-problemns when translated words (e.g. column-headers) get too long.
• If the context for the translation is not clear enough, please drop me a mail. I will check this.
• If you are done...
  • Don't forget to place your credits into the header
  • Email it to me. I will add it to the next release

Some hints for translators

• Avoid line breaks inside strings (inside quotes)
• Avoid quotes inside strings
• Keep it short! Long texts not only clutter the layout, but it slows the user down. Be as brief as the context allows.
• Make it shorter! For column-headers do not hesitate to use abbreviations. All column-headers have tooltips.

Thanks for your support!