wiki | forum | trac | otrs | joomla | tech blog | mailman | bewelcome Branches: test.bw | alpha.bw | www.bw Participate: download | get involved

Words module (MOD_words)

The words module allows to display text translated in the user's language.

The translations are stored in the database table 'words', each with a "word code" and a "language code".

How to use (translation team)

People with translation rights can surf the site in 3 modes: browse, translate and edit. Depending on which mode you surf in, you will see translation links, whenever you come across text that wants to be translated.

  • 'browse' mode shows no translation links -> free browsing.
  • 'translate' mode shows translation links on the texts that have a missing or obsolete translation.
  • 'edit' mode shows translation links on every translated text. This allows to improve existing translations.

You can edit translations by clicking the translation links. This will get you into the adminwords tool. Another way to get into this tool is to click the 'TR' button next to the list of flags in the footer, or to click 'AdminWords?' in the volunteer sidebar.

The translation links will look different, depending on the status of the translation. Have a look at the tooltip.

  • 'missing word' / 'define xyz in english': The word has yet to be defined in english language. This is usually a task for the designers, who introduced the word.
  • 'missing translation' / 'translate xyz in lang': The word is defined in english, but not yet translated in your language. Now it's your job to find a good translation!
  • 'obsolete translation' / 'update xyz in lang': The existing translation is older than the english definition. Someone has changed the english definition - most likely for a good reason. So, your job is to update the translation in your language, with respect to the new information.
  • 'successful translation' / 'edit xyz in lang': The existing translation is up to date, but maybe you still know it better. If you think you can improve the existing translation, go for it.

Translation rights

Translators must have the right 'Words', with scope either '"All"', or the language they want to translate in. Usually these rights are given to people joining the translation team, and to system admins.

Code

See

People

  • most of the code is based on the work done by Jean-Yves for the old bw system.
  • Felix (steinwinde) ported the stuff to PlatformPT, with some restructuring and rewriting.
  • Andreas (lemon-head) is currently working on it.

How to use (layouters/coders)

First you need to create an object of type 'MOD_words' (usually named '$words'), then you can use one of the following functions that will return translated text as a string.

  • $words->get($code, ...) -
  • $words->getFormatted($code, ...) - same as above
  • $words->getSilent($code, ...) - don't create translation links
  • new notation $words->Mymessages;
  • new notation $words->NbMembersOnline?(55);

Notation in Old BW

There we had the global-scope function 

<?php
ww('NbMembersOnline', 55);
?>

Ideas for other notations

Using shorter names for $words 

$ww = $this->ww;
echo $ww->Mymessages;

Using more than one $words object, for different purposes
These can all be gateways to one shared component. 

$ww = $this->ww;
$wwsilent = $this->wwsilent;
$wwscript = $this->wwscript;
echo $ww->WordCode;
?>
<img title="<?=$wwsilent->WordCode ?>" scr="..."/>
<script>
var x = "<?=$wwscript->WordCode ?>";
</script>

Using a simpler way to declare the $words objects and other things
See http://us2.php.net/extract 

extract($this->localvars);
echo $ww->WordCode;
echo $wwsilent->WordCode;
echo $wwscript->WordCode;
if ($user->isLoggedIn()) {
    ...
}
?>
<a href="<?=$baseuri ?>/searchmembers"><?=$wwsilent->SearchMembersTitle ?></a>

Using an XML parser for the translations
The parser would replace some predefined tags with translated text. 

<ww Mymessages/>

<ww NbMembersOnline/><arg>55</arg>
<ww NbMembersOnline arg0="55"/>


here the image title will not be escaped
<img src=".." title="<?=$ww->MyImgTitle ?>"/>

the <ww/> tag simply makes a word insertion.
<ww MyImgTitle/>

the <attribute/> tag inserts an attribute, and escapes it
<img src=".."/><attribute title>sun "is" shining</attribute>

the <attribute/> tag can be combined with the <ww/> tag,
to escape a word for using it as an attribute.
<img src=".."/><attribute title><ww MyImgTitle/></attribute>

maybe we can find a shorter notation..
<img src=".."/><x attribute="title"><ww MyImgTitle/></x>

This would become (assuming we are surfing in german 

Nachrichten

55 members are logged in.
55 members are logged in.

version c
55 members are logged in.


here the image title will not be escaped
<img src=".." title="this is "snoopy", my dog"/>

the <ww/> tag simply makes a word insertion.
this is "snoopy", my dog

the <attribute/> tag inserts an attribute, and escapes it
<img src=".." title="sun "is" shining"/>

the <attribute/> tag can be combined with the <ww/> tag,
to escape a word for using it as an attribute.
<img src=".." title="this is \"snoopy\", my dog"/>

maybe we can find a shorter notation..
<img src=".." title="this is \"snoopy\", my dog"/>

Database structure

Table 'words'

Each row is one translation of a word in one language.

  • id - unique id of the translation.
  • code - code identifying the word.
  • ShortCode? - code identifying the language
  • Sentence - translated text, defined by translators. Eventually contains symbols like '%s' or '%d' that will be replaced later.
  • updated - timestamp of last update by a translator
  • donottranslate - words with 'donottranslate' use the english version instead
  • IdLanguage? - unique id of the language (a bit redundant with 'ShortCode?'). English has id 0.
  • Description - description of how the word is supposed to be used. Only used in english version.
  • IdMember? - id of the translator who last updated or created the translation.
  • created - timestamp of the creation of this translation.

Requirements:

  • For every translation there should be an english original (with the same 'code', but 'ShortCode?' being 'en')
  • 'IdLanguage?' and 'ShortCode?' should be in the same row in the 'languages' table.
  • 'code' combined with 'ShortCode?' should be unique.
  • 'id' is unique.

To modify the 'words' table on test (or alpha), you must have the 'Words' right for a language, then use

http://test.bewelcome.org/bw/admin/adminwords.php (also found on the Volunteer Actions sidebar menu).

To download the 'words' table from test (or alpha), you must have the 'Debug' right, then use

http://test.bewelcome.org/admin/wordsdownload.

This page can also be used to import a downloaded words table (after uncompressing) into a localhost DB if run on localhost.

Table 'languages'

This is a list of the languages where translations of BeWelcome are available.

  • id - unique id of the language
  • EnglishName? - english name of the language
  • Name - native name of the language
  • ShortCode? - unique code identifying the language (like 'en' for english, and 'de' for german)
  • WordCode? - code to get the translated language name in other languages
  • FlagSortCriteria? - The criteria for showing the flags first (whatever)

Ideas for Caching / fewer DB Queries

We could print the words as XML tags first, and then let an XML parser (DOMDocument or PHP tidy) replace them by translated text from the db. This would have the advantage that we can look them up all at once.

We could also remember somewhere which words are needed on which page (using the page classnames as keys), and then store them all in one place (a PHP file or text file, which is usually quicker to read than making a DB query).

If we do html caching, we can remember the words as part of the html.

Trac Customization: trac stylesheet
SourceForge.net Logo