Difference between revisions of "Crowdsourcing Translations/Developer Documentation"

From GeeklogWiki
Jump to: navigation, search
 
(One intermediate revision by the same user not shown)
Line 1,198: Line 1,198:
  
 
* Ideally, translators should be able to see the text strings in context to help with the translation. - implemented
 
* 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
 
* 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
  
Line 1,206: Line 1,205:
 
* [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/gsoc-2013-btalic/summary, Repository]
 
* [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/gsoc-2013-btalic/summary, Repository]
 
* [http://wiki.geeklog.net/index.php?title=Crowdsourcing_Translations, User documentation]
 
* [http://wiki.geeklog.net/index.php?title=Crowdsourcing_Translations, User documentation]
 +
 +
[[Category:Development]] [[Category:Summer of Code]]

Latest revision as of 09:20, 20 September 2013

Contents

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
Function get_translations_table_headers

The html code of the table header for the table displaying translations


Parameters summary
integer $admin admin if set to 1 the table will have a username header
integer $limit limit number of translations to be shown, used for onclick method setting inside the headers
Return value summary string HTML code for the table header
Function get_translations_table_query

Assembles query used for the translations table

Parameters summary
integer $criterion criterions If 1 we are using admin mode where the translators user name has to be shown
integer $start start First translation to be shown
string $order_by order_by The ordering rule used in the query
integer $limit limit The number of translations to be shown
Return value summary
string returns The sql query assembled
Function get_translations_with_negative_vote_count

Returns number of translations with negative approval count

Return value summary
integer number of translations with negative aproval_count
Function get_user_badges

Retrieves badges accumulated in admin mode retrieves all available badges

Parameters summary
integer $limit = -1 limit The number of badges to be displayed
integer $admin = 0 admin Weather to use user or admin mode
mixed $show_not_awarded = true
Function get_user_translated_languages
Parameters summary
integer $user_id = null user_id If set to null the function will return all languages being translated
Return value summary
string The HTML of the progress bars for each retrieved language
Function get_user_translations_table

Makes the translations table for users

See: get_translations_table_table for translations table in admin 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_user_votes

Get the number of votes casted by current user

Return value summary
integer returns number of votes casted by current user
Function get_users_translating

Returns number of users translating

Return value summary
integer number of users using the plugin
Function get_votes_count
Return value summary
integer number of votes casted across translations
Function give_award

The award is given to the user by saving it to the awarded_gems table

Parameters summary
integer $gem_id = null gem_id the id under which the award has been given
integer $award_lvl = 0 award_lvl the level of the award
Function remove_block

Removes specified user from block list

Parameters summary
integer $user_id = null user_id ID of user to be un-blocked
Function remove_peer

Removes remote submission credentials from the database as well as translations submitted by the remote site

Return value summary
string JSON encoded string with failure or success message
Function save_to_database
Parameters summary
array $process_q process_q array of objects/translations to be saved to the database
Function submit_translation

After translations are submitted an AJAX call is issued to this functions, it will process the submitted translations

Return value summary
string json encoded string holding data on number of valid and invalid translations, number of given awards and the percent of translation for the current language


Function vote

Saves the user vote or updates existing vote notifies the JS if the page has to be reloaded-this happens if a translation is deleted

Return value summary
string JSON encoded string with failure or success message


packing.php

Function addslashesPacking

In order to prevent escaping phrase caracters (e.g. Don't => Don\'t) this function will do custom escaping

Parameters summary
string this_quote_type The quote type used for the current line (s for ' or d for ")
string value The actual string we are escaping
Return value summary
string the escaped string


Function getPhraseFromDB

Checks if current LANG element is translated (inside the database) if it is it will be formated and returned

Parameters summary
array current_array currently processed array
string array_key the current array key
string value2 the curretn phrase
string array_subindex if set the index of the sub-array default value = -1
Return value summary
string eaither value2 or the translation found in the database


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 print_array

Will format the array output for the new language file, the output is generated line by line - each line is one array element

Parameters summary
string file_content the previously generated content of the file
array current_array The currently processed array
string spacing The indentation used
array quote_type The type of quotes (' or ") used for the current line
array quote_type_count counter keeping track on which quote should be used
Function print_sub_array

Will format the array output for the new language file, the output is generated line by line - each line is one array element

Parameters summary
string file_conten the previously generated content of the file
array value2 The currently processed sub array
array key2 The currently processed sub array name/index
string spacing The indentation used
array quote_type The type of quotes (' or ") used for the current line
array quote_type_count counter keeping track on which quote should be used


recieve_remote.php

Function extract_metadata
Parameters summary
string metadata passed on via POST
string language_array empty - the value will be extracted from the metadata string
Function save_to_database
Parameters summary
array $process_q process_q array of objects/translations to be saved to the database


public_html/admin/crowdtranslator

send_remote.php

Function add_remote_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 credentials_form

Generates the form for submiting translations to a remote web page

Return value summary
string HTML code for the form
Function get_peer_list

Get the list of sites allowed to submit translations

Return value summary
string HTML code for the list
Function get_remote_language_array

Generates an array of objects holding translations and their metadata

Return value summary
array Objects holding translations and their metadata



JavaScript Documentation

public_html/crowdtranslator

string_extract.js

Members

language_strings

Function add_autocomplete_to_language_input

Gets list of available languages for translation via AJAX call and uses jQueryUI to create auto-complete option for the language selection input

Function add_notification

Adds notification to side view if awards have been given

Parameters summary
int awards award number of awards given
Function add_peer

Does a AJAX call to lib-translator.php a new peer is created

Function block_user

Issuing AJAX call to put a user on the block list

Function del_cookie

Deletes a cookie, it is used to delete the selected_language cookie


Function delete_translation

Issuing AJAX call to delete a translation from the database

Parameters summary
int id The translation id
string translation the translation text


Function doSearch

The function finds the searched text and highlights it

Parameters summary
string text The string we are searching for
string value The value, either color or inherit
Function getCookie

Gets the script saved cookie

Parameters summary
string c_name Name of the cookie
Function get_all_badges

Issues AJAX call to display all available badges

Parameters summary
int admin Indicating if showing all badges awarded to a user or all badges available


Function get_base_url

Creates the base url for AJAX calls and resource retrieval (e.g. images)

Function get_original_language_values

Sends a AJAX request to get formatted LANG strings and the actual translation form

Function getCookie

Gets the script saved cookie

Function hide_guidelines

Hides guidelines for translator usage

Function hide_language_input

if a language for translation if picked by the user the form is hidden

Function mark_bad_inputs

Adds a css class to faulty inputs so they are easily recognizable, Gives a preview of those at the beginning of the form

Parameters summary
array bad_inputs array of numbers marking the input id of the faulty inputs
Function pack_translation

Does the AJAX call to pack_translation.php which will do the actual translation packing

Parameters summary
string language the language name which should be packed
Function highlight

adds CSS class to highlight selected string(s) on page


Function prep_doSearch

Prepares the search removing and from passed strings

Parameters summary
string text The string we are searching for
string value The value, either color or inherit
Function remove_block

Issuing AJAX call to remove a user from the block list


Function remove_highlight

removes CSS class of highlighted string(s) on page


Function remove_peer

Does a AJAX call to lib-translator.php a peer is deleted

Parameters summary
string peer_name The string we are searching for
Function remove_submited

removes successfully submitted inputs

Parameters summary
array good_inputs array of numbers marking the input id of the successfully saved inputs
Function show

Shows content of hidden divs

Parameters summary
integer id the id of the function calls
Function show_guidelines

Shows guidelines for CrowdTranslator usage

Function show_language_input

if the user wants to change the picked language this function will show the translation form again and reset navigation variables

Function show_more_translations

Issues AJAX call to retrieve next/previous translations, change order of translations or increase translations display per page

Parameters summary
integer id number of translations per page
integer start first translation to be shown
integer admin indicating if admin mode or user mode
string order_by indicating the ordering of the table


Function show_next

Will show the next 6 (or less) input fields of the translation form If neccessary disables the arrow for showing next translations

Function show_previous

Will show the previous 6 (or less) input fields of the translation form If neccessary disables the arrow for showing previous translations

Function show_progress_bar

Will show a graphical representation of the amount of translated strings to the current language

Function translation_table_change_limit

Changing the number of translations shown per page

Function translator_form_submit

The call is handled via AJAX after the response is sent faulty inputs, if any will be marked as such the user is notified about successfully saved inputs, those input boxes will be removed

Function vote

A request is sent to mark the vote in the database if the translation is deleted because of too many bad votes (currently 5) the translation is deleted and the page reloaded othervise the object which made the request is highlighted and disabled

Parameters summary
integer sign the vote -1 or 1 depending on user choice
string id the id of the language_string associated with the string which is voted
object object the object which made the call

Considerations

  • Ideally, translators should be able to see the text strings in context to help with the translation. - implemented
  • 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=6334"