Crowdsourcing Translations/Developer Documentation

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

Function get_index

Returns the array index from the metadata string

Parameters summary
string	$string	string metadata string

Return value summary
string	array index

Function get_language_array

Generates an array of objects holding translations and their metadata

Return value summary
array	Objects holding translations and their metadata

Function get_language_array_references_from_included

Generates a list of LANG array elements which are used in pages included in the current page

See: documentation on language mapping and how the plugin works

Parameters summary
array	& $reference	&reference the array of previously found LANG references
array	$included	included the array of previously processed included url's
array	& $includes	includes the array of url's to be processed

Function get_languages

the script will return all available languages for translation it will make a list of both languages from the language folder and previously user created languages

Function get_languages_translated_count

Returns number of languages being translated

Return value summary
integer	number of distinct language names in the database

Function get_most_upvotes

Returns translation with the most up votes

Parameters summary
integer	$criterion	criterion if set to zero returns the bigest number of upvotes for translations by current user, otherwise the bigest number of upvotes

Return value summary
integer biggest number of up votes for single translation

Function get_original_language_values

Script will take extracted array data find the original array values from the database where all variables and html tags have been replaced with <tag> and create the HTML of the translation form before it is saved to the database

Return value summary
string	JSON encoded data holding the translation form, language strings, tagged strings

Function get_page_url

Returns current page url

Return value summary
string	Current page url

Function get_subindex

Returns the array sub-index from the metadata string

Parameters summary
string	$array	array array name from the metadata string
string	$index	index array index from the metadata string
string	$string	string metadata string

Return value summary
string	array sub-index

Function get_subindex

Returns the array sub-index from the metadata string

Parameters summary
string	$array	array array name from the metadata string
string	$index	index array index from the metadata string
string	$string	string metadata string

Return value summary
string	array sub-index

Function get_total_approval_for_user

Get the sum of all approvals across translations for current user

Return value summary
integer	the sum of all approvals for a single user

Function get_translated_count

Returns number of translations submitted by single user or in total depending on rge $admin param

Parameters summary
integer	$admin	admin Indicates if the function will return the number of votes submitted by one user or in total

Return value summary
integer	returns number of translations submitted by current user/in total

Function get_translated_languages

Returns HTML code for the progress bars of languages being translated

Return value summary
string	HTML code of progress bars for languages being translated

Function get_translation_percent

Calculates the percentage of translation for a language

Parameters summary
string	$language = null	language The for which the percentage is calculated

Return value summary
float	The percentage of translations

Function get_translations_options

When an AJAX call is used to show the table with translations the params are retrieved here See: get_translations_table_query()

Parameters summary
integer	& $limit	&limit the number of translations to be shown
integer	& $start	&start the first translation to be shown
string	& $order_by	&order_by the ordering of translations

Function get_translations_table

Makes the translations table for admins

See: get_user_translations_table for translations table in user mode

Parameters summary
integer	$limit = 5	limit number of translations shown per page, default value is 5
integer	$start = -1	start first translation to be shown , default value -1
string	$order_by = '`posted`, `id` DESC'	order_by the ordering of the translation default value 'posted, id DESC'

Return value summary
string HTML code of the table

Function get_translations_table_finalize

Assembles last row of the translations table ncludes the click for Previous show, Next show and input box for limit

Parameters summary
integer	$previous	previous indicates the first translation to be shown
integer	$next	next indicates the first translation to be shown
integer	$admin	admin used for onclick method inside the code indicating if the table is admin mode or user mode
integer	$limit	limit used for onclick method inside the code indicating the number of translations to be shown
mixed	$order_by = '`posted`, `id` DESC'

Return value summary
string display HTML code of the last table row which includes the click for Previous show, Next show and input box for limit

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:

• Blog
• Repository
• User documentation