GeeklogWiki - User contributions [en]

Crowdsourcing Translations

2013-09-20T09:58:34Z

Bttalic:

== Introduction ==
CrowdTranslator 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 [http://www.linkedin.com/profile/view?id=188717601, Benjamin Talic] under the mentorship of [http://www.linkedin.com/profile/view?id=11473251, Dirk Haun] as a project during the Google Summer of Code 2013.

The plugin uses a side block to provide a form for translation submitting, it will add badges to user profiles, the public page is intended for users to manage their translations, the admin page will allow overall translations management.

==What are the plugins features?==
* Translations submission
* Gamification badges
* Translations management and Simple translation queries
* Remote submission of translations
* Managing local and remote users
* Translation packing

==Translations submission==
[[File:CrowdTranslator_Form.png|thumb|upright=0.5|right|alt=The translation submission form.|The translation submission form]]
The translations are submitted via a form on the left side block. The left side is used because left side blocks are available on more pages than the right side blocks.
[[File:CorwdTranslator_Badges_notification..png|thumb|left||Example of notification]]
The form provides users with the possibility to select or change the selected language. Users can type in any language they want but a list of languages is generated from the database of previously translated and languages Geeklog ships with as a auto suggest for users while typing in. This allows users to create new languages but should prevent creating duplicate entries.

The form provides buttons for highlighting phrases on the page, or removing the highlight. To keep everything as small as possible the form shows a limited number of phrases at once but the users can scroll up and down.

If a certain phrase already has a submitted translation the translation is shown and users have the possibility to vote those translations up or down. After a certain number of negative votes the translation will be deleted.

The form also provides users with guidelines on how to use the translator.
Finally if the user earns a badge a notification will be shown.

==Gamification==
Currently the plugin supports 4 types of badges, 2 of which are continuous. The continuous badges will grow in level once a user has reached the necessary goal.
Additional badges might be added. If you do have requests for badges look up the code documentation, or the authors contact information or Geeklog's developer mailing list.
{|
|[[File:Badge1.png‎|thumb]]
|[[File:Badge2.png‎|thumb]]
|[[File:Badge3.png‎|thumb]]
|[[File:Badge4.png‎|thumb]]
|}

==Translations management==
Translations management is divided into to two "levels" the global,admin management and the single user management. The single user management is available in the CrowdTranslator public page and allows users to manage their own translations. The global translations management is available through the CrowdTranslator admin panel. Visually and functionally the two are very similar.
[[File:CrowdTranslator_Translations_table.png|thumb|center|upright=3.0]]

The table not only provides you with a preview of translated phrases but also lets you:
* Block users/sites(2) from submitting translations(1)
* Delete translations
* Query by:
* User or Site
* Language
* Votes
* Time posted

(1)Note: Blocking a user will also delete their translations
(2)Site refers to websites which you have allowed to submit translations to your website

==Remote submission of translations==

The plugin allows communication between several instances of Geeklog. That is a collection of translations from one site can be transferred to another. In order to achieve this the sender must get approved from the receiver. In fact the only way (currently) is to contact the site admin and request an account. To access this part of the plugin click the 'Manage Remote Submission' from the admin panel. Setting up remote senders is easy enough, as is sending data.

===Allowing remote submission===
[[File:CrowdTranslator_Peers.png|thumb|left||Adding Peers]]
By simply imputing a new site name and password you have allowed a new user(remote site) to submit translations to your database. After that give the credentials to the remote site's Admin and you are ready to go.
Previously submitted translations are not accepted.
Only translations with more than 1 up vote will be sent.

===Sending translations===
[[File:CrowdTranslator_Submit_remote.png|thumb|right||Sending Translations]]
To send translations it is necessary to specify the website you are sending to, if this website is www.geeklog.net you would enter geeklog.net. Other than that you will need to provide the site name and credentials the remote site admin created for you and the language you are sending. (the list of languages is generated from the entries in you database)

===Bragging rights===

A "new" feature is the iframe you can add to your website, if you have submitted translations to a remote website you will get code which can be included in your site. For now it will simply display the number of translations you have submitted to the remote site. In the future instead of this the badges available to local users should be displayed.

==Managing local and remote users==

Most user management is done inside the translations table.(see Translations management section of this document). The difference between sites and users is that users can simply be unblocked from the admin panel, sites however are permanently deleted, to allow a site to submit translations again you have to create a new account for them

==Packing translations==

To pack translations you simply have to click the text pack this in the admin panel. This will create and output a PHP file inside the language folder. It will take translations from your website and generate a file with the same structure Geeklog uses.

==More Resources==
Read more about this:
* [http://summergeeek.blogspot.com/2013/06/big-decisions.html, Blog]
* [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/gsoc-2013-btalic/summary, Repository]
* [http://wiki.geeklog.net/index.php?title=Crowdsourcing_Translations/Developer_Documentation&action=edit, Developer documentation]

[[Category:Development]] [[Category:Summer of Code]]

File:CrowdTranslator Submit remote.png

2013-09-20T09:56:47Z

Bttalic:

File:CrowdTranslator Peers.png

2013-09-20T09:55:54Z

Bttalic:

2013-09-20T09:40:40Z

Bttalic:

File:Badge3.png

2013-09-20T09:40:36Z

Bttalic:

2013-09-20T09:20:23Z

Bttalic:

== 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 [[SoC crowdsourcing translations|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 <var>
=====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 [http://wiki.geeklog.net/index.php/Plugin_Development, Geeklog plugin developer Guide]

====custom_string_replace.php====
Code is taken from stackoverflow, provided by user [http://stackoverflow.com/users/526741/bfrohs, bfrohs]
=====Function str_lreplace=====
{| class="wikitable"
|-
! Parameters summary
|-
| mixed || $search ||
|-
| mixed || $search ||
|-
| mixed || $search ||
|}

=====Function str_replace_limit=====
{| class="wikitable"
|-
! 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).
|}
{| class="wikitable"
|-
! Return value summary
|-
||string|| This function returns a string with the replaced values.
|}

=====Function valid_integer=====
{| class="wikitable"
|-
! Parameters summary
|-
| mixed || $string ||
|}

{| class="wikitable"
|-
! 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 [http://wiki.geeklog.net/index.php/Plugin_Development, Geeklog plugin developer Guide]
====install_defaults.php====
Take a look at [http://wiki.geeklog.net/index.php/Plugin_Development, 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

{| class="wikitable"
|-
! Return value summary
|-
||array || the array of language array names
|}

=====Function remove_standard=====
{| class="wikitable"
|-
! 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=====
{| class="wikitable"
|-
! 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=====
{| class="wikitable"
|-
! 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=====
{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! Return value summary
|-
|| string|| HTML output for loged in users
|}

=====Function get_info_text=====
{| class="wikitable"
|-
! Return value summary
|| returns|| info text for the plugin
|}

====lib-translator.php====
=====Function add_form_element=====

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! Return value summary
|-
||string|| JSON encoded strying with failiure or success message
|}

=====Function award_first_vote=====
award for first vote

{| class="wikitable"
|-
! Parameters summary
|-
||integer|| $gem_id|| gem_id
|}

=====Function award_mark=====
nth vote award

{| class="wikitable"
|-
! 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=====

{| class="wikitable"
|-
! 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
|}

{| class="wikitable"
|-
! Return value summary
|-
||boolean|| true if award is given, false otherwise
|}

=====Function award_nth_vote=====
nth vote award

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! Parameters summary
|-
||integer|| $gem_id|| gem_id the id under which the award has been given
|}

{| class="wikitable"
|-
! Return value summary
|-
||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
|}

=====Function get_index=====
Returns the array index from the metadata string

{| class="wikitable"
|-
! Parameters summary
|-
||string|| $string|| string metadata string
|}

{| class="wikitable"
|-
! Return value summary
|-
||string|| array index
|}

=====Function get_language_array=====
Generates an array of objects holding translations and their metadata

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! Return value summary
|-
||integer|| number of distinct language names in the database
|}

=====Function get_most_upvotes=====
Returns translation with the most up votes

{| class="wikitable"
|-
! 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
|}

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! Return value summary
|-
||string|| JSON encoded data holding the translation form, language strings, tagged strings
|}

=====Function get_page_url=====
Returns current page url

{| class="wikitable"
|-
! Return value summary
|-
||string|| Current page url
|}

=====Function get_subindex=====
Returns the array sub-index from the metadata string

{| class="wikitable"
|-
! 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
|}

{| class="wikitable"
|-
! Return value summary
|-
||string|| array sub-index
|}

=====Function get_subindex=====
Returns the array sub-index from the metadata string

{| class="wikitable"
|-
! 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
|}

{| class="wikitable"
|-
! Return value summary
|-
||string|| array sub-index
|}

=====Function get_total_approval_for_user=====
Get the sum of all approvals across translations for current user

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! Parameters summary
|-
||integer|| $admin|| admin Indicates if the function will return the number of votes submitted by one user or in total
|}

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! Parameters summary
|-
||string|| $language = null|| language The for which the percentage is calculated
|}

{| class="wikitable"
|-
! 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()
{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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'
|}

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! 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'||
|}

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! 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
|}
{| class="wikitable"
|-
! Return value summary
||string|| HTML code for the table header
|}

=====Function get_translations_table_query=====
Assembles query used for the translations table

{| class="wikitable"
|-
! 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
|}

{| class="wikitable"
|-
! Return value summary
|-
||string|| returns The sql query assembled
|}

=====Function get_translations_with_negative_vote_count=====
Returns number of translations with negative approval count

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! 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=====

{| class="wikitable"
|-
! Parameters summary
|-
||integer|| $user_id = null|| user_id If set to null the function will return all languages being translated
|}

{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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'
|}
{| class="wikitable"
|-
! Return value summary
|-
||string|| HTML code of the table
|}

=====Function get_user_votes=====
Get the number of votes casted by current user

{| class="wikitable"
|-
! Return value summary
|-
||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
|}

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

{| class="wikitable"
|-
! 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
|}

{| class="wikitable"
|-
!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

{| class="wikitable"
|-
! 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
|}

{| class="wikitable"
|-
!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

{| class="wikitable"
|-
!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

{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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=====
{| class="wikitable"
|-
! 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=====
{| class="wikitable"
|-
!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=====

{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
!Return value summary
|-
||string|| HTML code for the form
|}

=====Function get_peer_list=====
Get the list of sites allowed to submit translations
{| class="wikitable"
|-
!Return value summary
|-
||string|| HTML code for the list
|}

=====Function get_remote_language_array=====
Generates an array of objects holding translations and their metadata

{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! Parameters summary
|-
||int|| id|| The translation id
|-
||string|| translation|| the translation text
|}

=====Function doSearch=====
The function finds the searched text and highlights it
{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! Parameters summary
|-
||string|| c_name|| Name of the cookie
|}

=====Function get_all_badges=====
Issues AJAX call to display all available badges
{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! Parameters summary
|-
||string|| peer_name|| The string we are searching for
|}

=====Function remove_submited=====
removes successfully submitted inputs
{| class="wikitable"
|-
! Parameters summary
|-
||array|| good_inputs|| array of numbers marking the input id of the successfully saved inputs
|}

=====Function show=====
Shows content of hidden divs
{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! 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
{| class="wikitable"
|-
! 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:
* [http://summergeeek.blogspot.com/2013/06/big-decisions.html, Blog]
* [http://project.geeklog.net/cgi-bin/hgwebdir.cgi/gsoc-2013-btalic/summary, Repository]
* [http://wiki.geeklog.net/index.php?title=Crowdsourcing_Translations, User documentation]

[[Category:Development]] [[Category:Summer of Code]]

2013-09-20T01:15:41Z

Bttalic:

Crowdsourcing Translations/Developer Documentation

2013-09-20T01:03:38Z

Bttalic: