Help:Extension:Translate/Hooks

This documentation is maintained in version control system. See in hooks.txt in Translate extension the authoritative version for your version of Translate. This is a copy of version MLEB 2014.09 for convenience.

This document describes how event hooks work in the Translate extension; how to add hooks for an event; and how to run hooks for an event. See also the main Translate extension documentation page.

Rationale

edit

Hooks allow us to decouple optionally-run code from code that is run for everyone. It allows MediaWiki hackers, third-party developers and local administrators to define code that will be run at certain points in the mainline code, and to modify the data run by that mainline code. Hooks can keep mainline code simple, and make it easier to write extensions. Hooks are a principled alternative to local patches.

Writing hooks

edit

PHP hooks

edit

For a guide to PHP hooks, navigate to your root MediaWiki directory, and find docs/hooks.txt.

JavaScript hooks

edit

JavaScript hooks for the Translate extension are a little different. To use them, declare a dependency on ext.translate.hooks:

$wgResourceModules['...'] = array(
	'scripts' => '...js',
	'dependencies' => array( 'ext.translate.hooks' ),
);

And then in that module use:

mw.translateHooks.add( name, hookFunction );

where name is a string, but hookFunction is not (unlike in the case of PHP hooks) but rather a function reference. Return values from JavaScript hooks are ignored.

Events and parameters

edit

This is a list of known events and parameters; please add to it if you're going to add events to the Translate extension.

PHP events

edit
SpecialTranslate::executeTask
You can output the default task output
RequestContext  $context: For adding output, accessing current interface language etc.
TranslateTask   $task = null: Current task if any
MessageGroup    $group
array           $options: Active options
Translate:MessageGroupStats:isIncluded
Controls whether message group is shown for a given language in language or message group statistics. Mostly used internally by Translate to hide discouraged groups and groups restricted to certain languages.
string          $groupId: Message group id
string          $code: Language code
TranslateBeforeAddModules
Provides an opportunity to load extra modules
array          &$modules: List of resource loader module names
TranslateEventMessageMembershipChange
When group gets new messages or loses messages
MessageHandle   $handle
array           $old Previous groups
array           $new Current groups
TranslateEventMessageGroupStateChange
Event triggered when a message group workflow state is changed in a language
MessageGroup    $group: Message group instance
string          $code: Language code
string          $oldState
string          $newState
TranslateEventTranslationEdit
Event triggered when a translation is created or changed
MessageHandle   $handle
TranslateEventTranslationReview
Event triggered when a translation is proofread
MessageHandle   $handle
TranslateFormatMessageBeforeTable
Provides an opportunity to manipulate the display of translation strings (messages) in the main table
string         &$message: The message that will be displayed
TMessage        $m: Object representing the source object, useful for $m->original() and $m->translation()
MessageGroup    $group: The source message group
string          $targetLanguage: The language for which translations are being shown
array          &$extraAttribs: An array of attributes that will be added to the table row
TranslateGetBoxes
Provides an opportunity to add or remove "boxes" (translation helpers) from the translation interface
MessageGroup    $group: The message group being worked on
MessageHandle   $handle: An object representing the translation page (e.g. 'MediaWiki:Example/qqq')
array          &$boxes: An associative array to be appended to (format: 'name' => 'some HTML string')
TranslateGetAPIMessageGroupsParameterDescs
Provides an opportunity to document any parameters added with 'TranslateGetAPIMessageGroupsParameterList'.
array          &$paramDescs: An associative array of parameters, name => description.
string          $p: The prefix for action=query&meta=messagegroups (currently mg, but could change), useful for documentation
TranslateGetAPIMessageGroupsParameterList
Allows extra parameters to be added to the action=query&meta=messagegroups module
array          &$params: An associative array of possible parameters (name => details; see ApiQueryMessageGroups.php for correct spacing)
TranslateGetAPIMessageGroupsPropertyDescs
Allows extra properties to be added to captured by action=query&meta=messagegroups&mgprop=foo|bar|bat module
array          &$properties: An associative array of properties, name => description.
TranslateGetExtraInputs
Provides an opportunity to add extra form inputs to to the default translation editor
string         &$translation: The translation as it stands
string         &$extraInputs: The extra input space, ready for HTML to be appended
TranslateGetSpecialTranslateOptions
Provides an opportunity for overriding task values
array          &$defaults: Associative array of default values
array          &$nondefaults: Associative array of nondefault (override) values
Translate:GettextFFS:headerFields
Allows to customize headers of exported Gettext files per group. Certain X-headers nor Plural-Forms cannot be customized.
array          &$headers: List of prefilled headers. You can remove, change or add new headers.
MessageGroup    $group: Message group instance
string          $code: Language code
TranslateMessageGroupPathVariables
Allows to manipulate the list of variables for message group path patterns.
MessageGroup    $group
array          &$variables: Variable name => replacement
TranslateMessageTableInit
When creating new MessageTable
MessageTable   &$table: Default implementation that can be accessed or even replaced
IContextSource  $context:
MessageCollection $collection
MessageGroup    $group
Translate:newTranslation
Event triggered when non-fuzzy translation has been made
MessageHandle   $handle
int             $revisionId
string          $text: Content of the new translation
User            $user: User who created or changed the translation
TranslatePostInitGroups
Hook to register new message groups to Translate. Manual cache clear may be needed to have this hook executed.
array          &$groups: Map of message group id to message group instance
array          &$deps: List of dependencies as supported by DependecyWrapper class from MediaWiki
array          &$autoload: List of autoloaded classes. Key is the name of the class and value is filename.
TranslatePrefillTranslation
Provides an opportunity for a new translation to start not from as a carte blanche (the default) but from some prefilled string
string         &$translation: The translation string as it stands
MessageHandle   $handle: The current MessageHandle object
TranslateProcessAPIMessageGroupsProperties
Allows exrra property requests to be acted upon, and the new new properties returned
array          &$a: Associative array of the properties of $group that will be returned
array           $props: Associative array ($name => true) of properties the user has specifically requested
array           $params: Parameter input by the user (unprefixed name => value)
MessageGroup    $g: The group in question
TranslateSupportedLanguages
Allows removing languages from language selectors. For adding $wgExtraLanguage names is recommended.
array          &$list: List of languages indexed by language code
string          $language: Language code of the language of which language names are in
TranslateTranslationAids
Make new translation aids available to any message group (which must choose an implementation in its getTranslationAids() method).
array          &$types: List of translation aid identifiers, numerically indexed
AddNewAccount
Replica of the core hook, see https://www.mediawiki.org/wiki/Manual:Hooks/AddNewAccount

JavaScript events

edit
afterSubmit
Provides an opportunity to modify a Translate translation form immediately after it is submitted
jQuery          form: The form that has just been submitted
beforeSubmit
Provides an opportunity to modify a Translate translation form immediately before it is submitted
jQuery          form: The form being submitted
formatMessageBeforeTable
Provides an opportunity to manipulate the display of translation strings (messages) in the main table
object          message: The message object, with a range of useful (and manipulable) properties
showTranslationHelpers
Provides an opportunity to handle custom translation helpers
object          result.helpers: JSON subset focusing on the helpers returned e.g. result.helpers.definition
jQuery          translateEditor.$editor: The current translation-editing form