Difference between revisions of "Crowdsourcing Translations/Developer Documentation"
Line 743: | Line 743: | ||
|- | |- | ||
||integer|| returns number of votes casted by current user | ||integer|| returns number of votes casted by current user | ||
+ | |} | ||
+ | |||
+ | =====Function get_users_translating===== | ||
+ | Returns number of users translating | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! Return value summary | ||
+ | |- | ||
+ | ||integer|| number of users using the plugin | ||
+ | |} | ||
+ | |||
+ | =====Function get_votes_count===== | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! 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 | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! 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 | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! 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 | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | !Return value summary | ||
+ | |- | ||
+ | ||string|| JSON encoded string with failure or success message | ||
+ | |} | ||
+ | |||
+ | =====Function save_to_database===== | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | !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 | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | !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 | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | !Return value summary | ||
+ | ||string|| JSON encoded string with failure or success message | ||
|} | |} | ||
Revision as of 02:45, 20 September 2013
Contents
- 1 What is it?
- 2 Major Design Decisions
- 3 PHP Documentation
- 3.1 plugins/crowdtranslator
- 3.2 public_html/crowdtranslator
- 3.2.1 index.php
- 3.2.2 lib-translator.php
- 3.2.2.1 Function add_form_element
- 3.2.2.2 Function add_peer
- 3.2.2.3 Function award_first_vote
- 3.2.2.4 Function award_mark
- 3.2.2.5 Function award_nth_translation
- 3.2.2.6 Function award_nth_vote
- 3.2.2.7 Function awards
- 3.2.2.8 Function block_user
- 3.2.2.9 Function check_if_awarded
- 3.2.2.10 Function check_post_variable
- 3.2.2.11 Function delete_translation
- 3.2.2.12 Function display_badge
- 3.2.2.13 Function extract_metadata
- 3.2.2.14 Function get_array
- 3.2.2.15 Function get_index
- 3.2.2.16 Function get_language_array
- 3.2.2.17 Function get_language_array_references_from_included
- 3.2.2.18 Function get_languages
- 3.2.2.19 Function get_languages_translated_count
- 3.2.2.20 Function get_most_upvotes
- 3.2.2.21 Function get_original_language_values
- 3.2.2.22 Function get_page_url
- 3.2.2.23 Function get_subindex
- 3.2.2.24 Function get_subindex
- 3.2.2.25 Function get_total_approval_for_user
- 3.2.2.26 Function get_translated_count
- 3.2.2.27 Function get_translated_languages
- 3.2.2.28 Function get_translation_percent
- 3.2.2.29 Function get_translations_options
- 3.2.2.30 Function get_translations_table
- 3.2.2.31 Function get_translations_table_finalize
- 3.2.2.32 Function get_translations_table_headers
- 3.2.2.33 Function get_translations_table_query
- 3.2.2.34 Function get_translations_with_negative_vote_count
- 3.2.2.35 Function get_user_badges
- 3.2.2.36 Function get_user_translated_languages
- 3.2.2.37 Function get_user_translations_table
- 3.2.2.38 Function get_user_votes
- 3.2.2.39 Function get_users_translating
- 3.2.2.40 Function get_votes_count
- 3.2.2.41 Function give_award
- 3.2.2.42 Function remove_block
- 3.2.2.43 Function remove_peer
- 3.2.2.44 Function save_to_database
- 3.2.2.45 Function submit_translation
- 3.2.2.46 Function vote
- 3.2.3 packing.php
- 3.2.4 recieve_remote.php
- 4 JavaScript Documentation
- 5 Considerations
- 6 More Resources
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
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: