Difference between revisions of "Crowdsourcing Translations/Developer Documentation"

From GeeklogWiki
Jump to: navigation, search
Line 142: Line 142:
 
|-
 
|-
 
|| array || $matches || matches matches found using the regex, for includes and LANG's
 
|| array || $matches || matches matches found using the regex, for includes and LANG's
 +
|-
 
|| array || & $push_array || the array holding all found matches without duplicates
 
|| array || & $push_array || the array holding all found matches without duplicates
 
|}
 
|}
Line 286: Line 287:
 
|-
 
|-
 
||boolean|| true if user has award
 
||boolean|| true if user has award
 +
|}
 +
 +
 +
=====Function check_post_variable=====
 +
Check if post variable is set and non=empty
 +
 +
{| class="wikitable"
 +
|-
 +
! Parameters summary
 +
|-
 +
||mixed|| $post_var
 +
|}
 +
 +
{| class="wikitable"
 +
|-
 +
!Return value summary
 +
|-
 +
||boolean|| True if the POST variable specified is set and non-empty
 +
|}
 +
 +
=====Function delete_translation=====
 +
Removing a single translation from translations table as well as its votes from votes table
 +
 +
{| class="wikitable"
 +
|-
 +
! Parameters summary
 +
|-
 +
||integer|| $id = null|| id the unique id of the translation to be removed
 +
|}
 +
{| class="wikitable"
 +
|-
 +
! Return value summary
 +
|-
 +
||boolean|| true if the deletion was successful, false otherwise
 +
|}
 +
 +
=====Function display_badge=====
 +
When displaying badges this is where the actual HTML code is assembled
 +
 +
{| class="wikitable"
 +
|-
 +
! Parameters summary
 +
|-
 +
||object|| $gem|| gem The badge data retrieved from database
 +
|-
 +
||integer|| $count|| count Keeps count on number of displayed gems, gems will be displayed 4 in a row
 +
|-
 +
||mixed $lvl = ''||
 +
|-
 +
||mixed $disabled = '' ||
 +
|}
 +
 +
=====Function extract_metadata=====
 +
 +
{| class="wikitable"
 +
|-
 +
! Parameters summary
 +
|-
 +
||string|| $metadata|| metadata passed on via POST
 +
|-
 +
||string|| & $language_array|| language_array empty - the value will be extracted from the metadata string
 +
|-
 +
||string|| & $array_key|| language_array empty - the value will be extracted from the metadata string
 +
|-
 +
||mixed|| & $array_subindex||
 +
|}
 +
 +
 +
Function get_array
 +
Returns the array name from the metadata string
 +
 +
{| class="wikitable"
 +
|-
 +
! Parameters summary
 +
|-
 +
||string|| $string|| string metadata string
 +
|}
 +
 +
{| class="wikitable"
 +
|-
 +
! Return value summary
 +
|-
 +
||string|| array name
 
|}
 
|}
  

Revision as of 02:04, 20 September 2013

What is it?

This is a plugin that allows "crowdsourcing" the translation of Geeklog, i.e. once installed, it allows users to contribute translations of Geeklog's user interface texts for other languages.

This is a being developed by Benjamin Talic as a project during the Google Summer of Code 2013.

Major Design Decisions

  • Any logged-in user should be able to contribute a translation
  • Users can be blocked from contributing by the Admin
  • Ideally, the plugin should also allow translations of plugins (bundled and 3rd party). We'll start with core texts but try to keep things generic, adding plugin support later when possible.
  • To be able to find translations on a page at plugin installation pages are mapped into the database, data on which phrases on which pages is saved along with which pages are included in it
  • Remote contribution is allowed via a form
  • Gamification is added to the plugin
  • The plugin is placed on the left side block - the left side block is shown on more pages

PHP Documentation

plugins/crowdtranslator

sql

translations table

Saves the submitted translations

originals table

Saves the original phrase values, changing HTML and PHP code with <tag> and

votes table

Saves data on votes for translations

gems table

'List' of available gems

awarded_gems table

Data on which user got which gem awarded

language_map table

Saves data on which phrases are used on which page and which page is included on it

blocked_users table

A list of users blocked from submitting

remote_credentials table

List of sites allowed to submit translations

autoinstall

Take a look at Geeklog plugin developer Guide

custom_string_replace.php

Code is taken from stackoverflow, provided by user bfrohs

Function str_lreplace
Parameters summary
mixed $search
mixed $search
mixed $search
Function str_replace_limit
Parameters summary
mixed $search The value being searched for, otherwise known as the needle. An array may be used to designate multiple needles.
mixed $replace The replacement value that replaces found search values. An array may be used to designate multiple replacements.
mixed $subject The string or array being searched and replaced on, otherwise known as the haystack. If subject is an array, then the search and replace is performed with every entry of subject, and the return value is an array as well.
string & $count If passed, this will be set to the number of replacements performed.
integer $limit = -1 The maximum possible replacements for each pattern in each subject string. Defaults to -1 (no limit).
Return value summary
string This function returns a string with the replaced values.
Function valid_integer
Parameters summary
mixed $string
Return value summary
boolean Returns boolean TRUE if string is a valid integer, or FALSE if it is not

functions.inc

Take a look at Geeklog plugin developer Guide

install_defaults.php

Take a look at Geeklog plugin developer Guide

language_maper.php

Will do the LANG array mapping

language_markup.php

Function get_language_array_names

Gets the list of array names used by Geeklog, it connects to the current language file and parses it as a string

Return value summary
array the array of language array names


Function remove_standard
Parameters summary
string & $line the string from which tags are to be removed
string $key_begin the begining of the tag
string $key_end the end of the tag
array & $array
Function remove_tags
Parameters summary
string $line the array element from which the tags are removed
array & $tags after the tags are removed they are keept here for later assembly


language_maper.php

Will do the LANG array mapping

Function extract_from_matches
Parameters summary
array $matches matches matches found using the regex, for includes and LANG's
array & $push_array the array holding all found matches without duplicates
Function extract_from_matches
Parameters summary
string $path path of the current folder


public_html/crowdtranslator

index.php

Function logedin_user_display

Generates the output for loged in users

Return value summary
string HTML output for loged in users
Function get_info_text
Return value summary returns info text for the plugin

lib-translator.php

Function add_form_element
Parameters summary
string &$form The HTML of the translation form
integer $count number of current input field
object $value current translation object, holds all relevant data for the string
string $base_url base url for the required resources
string $disabled_up Will either be empty string or disable if the vote button should be disabled
string $disabled_down Will either be empty string or disable if the vote button should be disabled
Function add_peer

Add new credentials to the database, allowing a new site to submit remote translations

Return value summary
string JSON encoded strying with failiure or success message
Function award_first_vote

award for first vote

Parameters summary
integer $gem_id gem_id
Function award_mark

nth vote award

Parameters summary
integer $gem_id gem_id the id under which the award has been given integer & $award_lvl award_lvl the level of the award - for continuos awards integer & $award_mark award_mark the limit required to get the next award lvl
Function award_nth_translation
Parameters summary
integer $translation_count translation_count number of translation the user has submited integer $gem_id gem_id the id under which the award has been given
Return value summary
boolean true if award is given, false otherwise
Function award_nth_vote

nth vote award

Parameters summary
integer $gem_id gem_id the id under which the award has been given
Function awards

Checks for the awards the user has not received and if criteria is met assigns them for repetitive awards the check is always done

Return value summary
integer number of awards given
Function block_user

Puts specified user on block list, deletes his translations and votes for those translations and awarded gems

Parameters summary
integer $user_id = null user_id ID of user to be blocked
Function check_if_awarded

Check if award with id gem_id is given to user

Parameters summary
integer $gem_id gem_id the id under which the award has been given
Return value summary
boolean true if user has award


Function check_post_variable

Check if post variable is set and non=empty

Parameters summary
mixed $post_var
Return value summary
boolean True if the POST variable specified is set and non-empty
Function delete_translation

Removing a single translation from translations table as well as its votes from votes table

Parameters summary
integer $id = null id the unique id of the translation to be removed
Return value summary
boolean true if the deletion was successful, false otherwise
Function display_badge

When displaying badges this is where the actual HTML code is assembled

Parameters summary
object $gem gem The badge data retrieved from database
integer $count count Keeps count on number of displayed gems, gems will be displayed 4 in a row
mixed $lvl =
mixed $disabled =
Function extract_metadata
Parameters summary
string $metadata metadata passed on via POST
string & $language_array language_array empty - the value will be extracted from the metadata string
string & $array_key language_array empty - the value will be extracted from the metadata string
mixed & $array_subindex


Function get_array Returns the array name from the metadata string

Parameters summary
string $string string metadata string
Return value summary
string array name


packing.php

recieve_remote.php

JavaScript Documentation

Considerations

  • Ideally, translators should be able to see the text strings in context to help with the translation. - implemented
    • If that turns out not to be possible, we'll show them without context.
  • It's acceptable if the translation option slows things down. If it slows down things noticably, add a "translation mode", so users can decide between using the site normally or helping with the translation. - not necessary

More Resources

Read more about this:

Retrieved from "http://wiki.geeklog.net/index.php?title=Crowdsourcing_Translations/Developer_Documentation&oldid=6322"