Topic

Translation Guide

Dec 14, 2006 / pixtur
Feb 11, 2011 / guest
 

Attached files

encoding.jpg
encoding.jpg

#7741 by brasti, 37k
 
How to translate streber into other languages.

How Translation works in streber π

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

Translation filesπ

    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.php contains the actual translation table as an 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 ;-)

At the end of some lines there might be comments starting with "#". You can ignore them.

Inside the codeπ

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

echo __("Home", "Label inside navigation tab");

Translation keys (Home) are defined in plain English and will be used for the English version of streber. They can have an additional description to clarify its meaning or usage (Label inside navigation tab). In this examples, the translation should be very short, because it will be used inside navigation. The two underscores are actually a function name. This function looks into the translation table of the current language and searches the Key Home|Label inside navigation tab. If found, it will be used. Otherwise we try the key withough clarification (Home), and if this fails too, the original English string will be printed (of course without the context part).

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

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

If translation keys are not found (e.g. for "No"), they are 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.php :

confChange('LIST_UNDEFINED_LANG_KEYS',true);

Updating translationsπ

Although this might be good for testing a tranlation, it is cumbsersome to get all strings that need translation. For this we 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.php
  • Rename the copy to the shortform of your language (like uk.inc.php,es.inc.php, etc).
  • Open the new file with a text editor capable of utf8 editing
  • Add your translation into the quotes. (Keep in mind to ignore the part after "|")
  • Save the file using the "UTF-8 without BOM" encoding.
  • Open /conf/conf.inc.php
  • Search for g_languages and add your language like:

    $g_languages=array(
       'en'=>'English',
       'de'=>'German',
       'pt-br'=>'Portugese', 
    ); 
  • Add the following lines to your customize.inc.php. This will warn you on missing translation keys when testing the translation.

from customize.inc.php

    confChange('LIST_UNDEFINED_LANG_KEYS',true);
  • For testing make your language the default-language or adjust your profile accordingly. To customize.inc add:

from customize.inc.php

    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 a comment to ?. Pixtur will check this.
  • If you are done...
    • Don't forget to place your credits into the header.
    • Add a new Folder at Translations and attach the new file. We 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.

Localization of datesπ

Localization of dates is being performed though the PHP functions gmstrftime, which needs the proper locale to be set with function setlocale. Each language file must provide a list of locales to be passed to setlocale as a translation of the string 'en_US.utf8,en_US,enu|list of locales'. You should provide at least three locale names in the translation. For example the Italian translation would be 'it_IT.utf8,it_IT,ita', where:
  1. 'it_IT.utf8' is the name of the locale for libc-based PHP implementation (for example under Linux) with proper utf-8 support. Names in this form are language_country with two letter ISO names for both language and country;
  2. 'it_IT' is the same name for those platforms who lack proper utf-8 support;
  3. 'ita' is the three letter name for Windows-based platforms.
See http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/_crt_language_strings.asp for a list of supported names.

The formatting string themselves needs to be translated. In particular:
  • '%b %e, %Y|strftime format string' for dates like Jan 16, 2007 used in very many places;
  • '%I:%M%P|strftime format string' for time strings like 4:48pm used in very many places (the only meaningful translation for this string is '%H:%M' for those languages that prefer 24-hour format);
  • '%a %b %e, %Y %I:%M%P|strftime format string' for long timestamps like Tue Jan 16, 2007 4:48pm used in many places;
  • '%A, %B %e|strftime format string' for dates like Tuesday, January 16, currently used only in page titles.
Attention: pixtur reports that some PHP implementation do not handle the %e formatter (day of the month from '1' to '31') properly. In those cases the %d formatter (which is the same but from '01' to '31') although not as good-looking should be used instead.

For further details about strftime/gmstrftime and setlocale, please refer to the respective doc pages: http://php.net/manual/en/function.strftime.php and http://php.net/manual/en/function.setlocale.php .

Thanks for your support!

13 Comments

ganesh:swapping arguments in printf-formatted strings

11 years ago

About %-fields in printf-formatted strings, remember that argument are matched positionally. Occasionally a language needs to use a different order. For example the English "Ganesh's tasks" becomes "Attività di Ganesh" in Italian. If the English string is "%s's %s" the translation "%s di %s" would be incorrect because of the inversion. This case is easily managed using the "numbered" syntax introduced in PHP 4.0.6 (http://php.net/manual/en/function.sprintf.php). The correct translation would thus be "%2$s di %1$s".

pixtur:Reply to swapping arguments in printf-formatted strings

11 years ago

good hint. Does this work without modifing the original string?

ganesh:Reply to Reply to swapping arguments in printf-formatted strings

11 years ago

Yes, you don't need to change the original string. Only the localized string needs the numbered syntax and only if argument reordering (with respect to the base language) is necessary. Cool! The numbered syntax can be used in the base language in the (rare) case you need repetitions, for example:
  printf('%1$s %2$s %1$s', 'a', 'b');
produces
  a b a

madlyr:setLocale gives problems

11 years ago

Hi, I have to switch to new version of Streber due to upgrade server software on one of the Streber installations and I see, that there is other locale managing in Streber now.

I always obtain error:
WARNING: stdcommon.inc.php : 506 Could not set locale to 'pl_PL.utf8,pl_PL,plk'

I tried a lot of other combinations and... nothing helps.
So I tried to read info on setlocale on php.net and here are some more info from there:

from bruno dot cenou at revues dot org 20-Feb-2006 03:31

A little function to test available locales on a sytem :

<?php
function list_system_locales(){
   ob_start();
   system('locale -a');
   $str = ob_get_contents();
   ob_end_clean();
   return split("\n", trim($str));
}

$locale = "fr_FR.UTF8";
$locales = list_system_locales();

if(in_array($locale, $locales)){
       echo "yes yes yes....";
}else{
       echo "no no no.......";
}

?>


When executing this script on one of my web servers I always obtain result: no, no, no....

Another voice:

from pigmeu at pigmeu dot net 18-Oct-2004 10:42


!!WARNING!!

The "locale" always depend on the server configuration.

i.e.:
When trying to use "pt_BR" on some servers you will ALWAYS get false. Even with other languages.

The locale string need to be supported by the server. Sometimes there are diferents charsets for a language, like "pt_BR.utf-8" and "pt_BR.iso-8859-1", but there is no support for a _standard_ "pt_BR".

This problem occours in Windows platform too. Here you need to call "portuguese" or "spanish" or "german" or...

Maybe the only way to try to get success calling the function setlocale() is:
setlocale(LC_ALL, "pt_BR", "pt_BR.iso-8859-1", "pt_BR.utf-8", "portuguese", ...);

But NEVER trust on that when making functions like date conversions or number formating. The best way to make sure you are doing the right thing, is using the default "en_US" or "en_UK", by not calling the setlocale() function. Or, make sure that your server support the lang you want to use, with some tests.

Remember that: Using the default locale setings is the best way to "talk" with other applications, like dbs or rpc servers, too.

[]s

Pigmeu

I think, this method of setting locale is not good or just we should disable warning.
Read more comments on setlocale - some of the folks warns not to use setlocale at all....

Radek

ganesh:

11 years ago

I suggested in to write our own implementation of gmstrftime, based on gmdate() and localization tables. That would remove the need to use setlocale() completely and would make localized dates completely portable. We just need a few more language strings (namely the names of months and weekdays, both long and short). [pixtur] rejected the idea fearing performance problems. My opinion is: if the user wants localized dates, he/she will have to pay for them. If we make them optional so that the user don't have to pay if he/she does not want them, I don't see the reason to worry about performances.

pixtur:Reply to

11 years ago

Hi Ganesh,

I just thought about your suggestion a little bit longer. I know believe, that you are probably right. Probably this will not be too expensive. Although it will be some work, it is still better than a internal php function which seems not to work properly.

Sorry for being to rejective in the first place.






guest:Ru

9 years ago -

Is there any russian translation?

pixtur:yes...

9 years ago

But it needs to be updated a little. It should be 80-90% complete.

rayz:

9 years ago

Should be finished in this week.

brasti:utf-8 without BOM

9 years ago (3. update 9 years ago)

It's important to use "utf-8 without BOM" encoding!

It took me more than a day to figure out why streber wasn't rendering in line images in my language. It showed only red crosses instead.
encoding.jpg

pixtur:@brasti

9 years ago

Could you precise this a little bit? What is BOM?

guest:Polish charachters problem in database

8 years ago -

Polish language works fine with interface, but when I want add for instance company with name "Sączki babuni" the charachter ą is changed to ? .... I checked in database and it is question mark indeed... when I Manually change in phpmyadmin to ą charachter ... it is displayed fine... so I assume there is problem when saving string "Sączki babuni" it is somehow changed to "S?czki babuni"....

regards Peter

guest:pacquiao vs mosley

7 years ago - visible as suggested -

nice hint, Does this work without modifing the original string?