Methods to access properties of a language and modify translations
This class is used to manage languages and translations. The following functions are supplied
Located in /program/lib/translatetool.class.php (line 56)
construct a TranslateTool object
This initialises the TranslateTool and also dispatches the chore to do.
shorthand for the anchor parameters that lead to the translate tool
hightlight code constructs in texts that are to be translated
this routine highlights the following code constructs:
Note: This assumes that all '{' are eventually followed by a '}'. As long as this is true, we can easily use a str_replace() to sandwich {VARIABLE} between highlights. If there is only a single '{' or '}' the highlights won't match. It _could_ be a problem and if it is, the relevant code should iterate / chomp through the string with something like preg_match('/({[a-zA-Z0-9_]+})/',$string,$matches)
As an added bonus, sequences of two consecutive spaces are replaced with non-breakable spaces. This is handy for phrases that use spaces to indent text, e.g. in simple text-only email messages.
By using a reference we prevent the endless coping of (long) strings to the stack; this should save time & space.
convert an array with key-value-pairs to a php source file that can be included as a user translation
All key-value-pairs are converted to something like this:
We specifially use single quotes in order to prevent any variable expansion within the strings. We do escape embedded single quotes, naturally. Furtermore, some metadata is added to the top of the resulting file, including information about the creation time, the program version that was used, the version of the (English) source file on which this translation is based and finally information about the file version of the system strings which was used to diff against.
Note: If the file with these system strings do not exist (because the language is all new, indicated by a version 'v0', _all_ strings are stored in the diff and thus in the user file. That file could be used as a new starting point for the new language in a next version of the program.
Note: we try very hard to defeat tricks with the contents of the metadata (i.e. we don't trust _full_name and _email to not contain tricks like '*' followed by '/' (which would prematurely end the comment in the header) etc.
construct the language dialog (used for both add and edit)
this constructs a language dialog definition, maybe filled with data The main difference between dialogs for add and edit is that an existing language code ($language_key) cannot be changed; the corresponding field is shown in 'viewonly' mode. Another small difference is that an existing language cannot have itself as a parent language.
Note that we populate the 'edit' dialog with existing data from $this->languages.
construct the translation dialog for selected language and domain
this constructs a translation dialog definition, filled with translations for language $language_key and domain $full_domain. The labels for the fields are derived from the English texts in $full_domain, in the order specified by the English file. If the English file contains comments, these are added to the item too (to be displayed as additional information for the translator). The current translation of the $full_domain is retrieved the usual way, via function t() (shorthand for $LANGUAGE->get_phrase()) but without translating any variables (e.g. {VALUE}). Note that if a translation of a phrase does not exist in the target language, the get_phrase() routine will eventually yield the English translation (after trying the language parents first). Also note that the translated phrases could be retrieved from a user file (ie. a file from $CFG->datadir/languages/$language_key/$full_domain).
return an ordered list of translation domains
this constructs a list of language domains, grouped by 'program','modules','themes' or 'install'. This array is the basis for validating full domains (in $_POST'ed data) and also to construct a menu.
Note that we use the translations from the files themselves in the current language to construct this list. Every translatefile should have at least the string 'translatetool_title' and 'translatetool_description'. Currently the sort order is based on the (internal) name of the modules. This should do the trick for translators: the order of files to translate in the menu does not depend on the translation of the module- or theme-title. (In the page manager and elsewhere it may be different).
construct a clickable icon to edit the properties of this language
fetch a list of languages available as parent language
this constructs a list of languages that can be used as a list of parent language options in a listbox or radiobuttons.
retrieve strings (translations) and comments from an official (system) translation file
This routine reads the system translations for $language_key and $full_domain from a file. For the translations of the main program we look for a single file in $CFG->progdir/languages/$language_key/. For modules, themes and addons we try two different locations: one within the moduel/theme/addon directory tree and subsequently in the generic directory $CFG->progdir/languages/$language_key/.
The names of modules/themes/addons are derived by stripping the 2-character prefix (m_, t_ or a_) from the full domain.
Translations for the installer are searched for in the /program/install/languages tree.
try to calculate a reasonable number of textarea rows based on the contents of $text
By using a reference we prevent the endless coping of (long) strings to the stack; this should save time & space.
display list of languages with edit icons and an option to add a language
this constructs the languages overview: a link to add a language, followed by a list of languages based on the languages in the database. Every language has an icon through which the properties of the language can be modified, including setting/resetting the active flag. (Only active languages can be used on the website and in the CMS). Note that we use _all_ languages here, including inactive ones.
Note that the calling routine (the tools manager) is allowed to display a menu because we set the parameter show_parent_menu to TRUE here.
The constructed list looks something like this:
The clickable icons [E] lead to the Edit language properties. The clickable titles lead to the actual translations The clickable link 'Add an area' leads to the add new language dialog.
present the language dialog where the user can enter properties for a new language
this displays a dialog where the user can enter the properties of a new language. These properties are:
show the language edit dialog
display a dialog where the user can modify language properties. we re-use the routine that created the add language dialog.
validate and save modified data to database
this saves data from the edit language dialog if data validates. If the data does NOT validate, the edit screen is displayed again otherwise the languages overview is displayed again.
save the newly added language to the database
This saves the essential information of a new language to the database, using sensible defaults for the other fields. Also, a data directory is created in $CFG->datadir
If something goes wrong, the user can redo the dialog, otherwise we return to the languages overview, with the newly added language in the list, too.
Apart from the standard checks the following checks are done:
save new or changed translations to a file under CFG->datadir/languages
render a translation dialog based on a dialog definition
This routine looks a bit like the generic dialog_quickform(). The differences are:
display the domain menu via $this->output
This displays a clickable menu on in the menu area on the left of the screen.
allow the caller to use the menu area (or not)
this routine tells the caller if it is OK to use the menu area (TRUE returned) or not (FALSE returned).
send new or changed translations back to the project
This sends an e-mail back to the project with the translation. We do so in the form of an attachment, but with a 'safe' extension (.bin rather than .php). This means that we will be able to traverse any firewalls and spamfilters and malware detectors.
The _notes are used as the body of the message, the file is attached.
Note that we send a copy of the message to the site itself (either the from-addres or the reply-to-address).
show an edit dialog with phrases from $full_domain in $language_key
After some sanity checking this routine shows al dialog where the user can edit translations for the selected language and domain. Note that this could be a huge dialog, depending on the size of the language domein ('admin' is notoriously large). Sending this routine to the browser can take some time.
save the modified translations in a file in the tree CFG->datadir/languages/
this routine validates the dialog data and attempts to save the changes in the file $full_domain in the directory CFG->datadir/languages/$language_key/. Also, we may need to send a message to the Website@School project with our changes (depending on the flag _submit).
Documentation generated on Tue, 28 Jun 2016 19:12:21 +0200 by phpDocumentor 1.4.0