Help:Extension:Translate/Hooks

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
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.

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

JavaScript hooks
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
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
RequestContext $context: For adding output, accessing current interface language etc. TranslateTask   $task = null: Current task if any MessageGroup   $group array          $options: Active options
 * SpecialTranslate::executeTask : You can output the default task output

string         $groupId: Message group id string          $code: Language code
 * 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.

array         &$modules: List of resource loader module names
 * TranslateBeforeAddModules : Provides an opportunity to load extra modules

MessageHandle  $handle array          $old Previous groups array          $new Current groups
 * TranslateEventMessageMembershipChange : When group gets new messages or loses messages

MessageGroup   $group: Message group instance string         $code: Language code string         $oldState string         $newState
 * TranslateEventMessageGroupStateChange : Event triggered when a message group workflow state is changed in a language

MessageHandle  $handle
 * TranslateEventTranslationEdit : Event triggered when a translation is created or changed

MessageHandle  $handle
 * TranslateEventTranslationReview : Event triggered when a translation is proofread

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
 * TranslateFormatMessageBeforeTable : Provides an opportunity to manipulate the display of translation strings (messages) in the main table

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')
 * TranslateGetBoxes : Provides an opportunity to add or remove "boxes" (translation helpers) from the translation interface

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
 * TranslateGetAPIMessageGroupsParameterDescs : Provides an opportunity to document any parameters added with 'TranslateGetAPIMessageGroupsParameterList'.

array         &$params: An associative array of possible parameters (name => details; see ApiQueryMessageGroups.php for correct spacing)
 * TranslateGetAPIMessageGroupsParameterList : Allows extra parameters to be added to the action=query&meta=messagegroups module

array         &$properties: An associative array of properties, name => description.
 * TranslateGetAPIMessageGroupsPropertyDescs : Allows extra properties to be added to captured by action=query&meta=messagegroups&mgprop=foo|bar|bat module

string        &$translation: The translation as it stands string        &$extraInputs: The extra input space, ready for HTML to be appended
 * TranslateGetExtraInputs : Provides an opportunity to add extra form inputs to to the default translation editor

array         &$defaults: Associative array of default values array         &$nondefaults: Associative array of nondefault (override) values
 * TranslateGetSpecialTranslateOptions : Provides an opportunity for overriding task values

array         &$headers: List of prefilled headers. You can remove, change or add new headers. MessageGroup   $group: Message group instance string         $code: Language code
 * Translate:GettextFFS:headerFields : Allows to customize headers of exported Gettext files per group. Certain X-headers nor Plural-Forms cannot be customized.

MessageGroup   $group array         &$variables: Variable name => replacement
 * TranslateMessageGroupPathVariables : Allows to manipulate the list of variables for message group path patterns.

MessageTable  &$table: Default implementation that can be accessed or even replaced IContextSource $context: MessageCollection $collection MessageGroup   $group
 * TranslateMessageTableInit : When creating new MessageTable

MessageHandle  $handle int            $revisionId string         $text: Content of the new translation User           $user: User who created or changed the translation
 * Translate:newTranslation : Event triggered when non-fuzzy translation has been made

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.
 * TranslatePostInitGroups : Hook to register new message groups to Translate. Manual cache clear may be needed to have this hook executed.

string        &$translation: The translation string as it stands MessageHandle  $handle: The current MessageHandle object
 * TranslatePrefillTranslation : Provides an opportunity for a new translation to start not from as a carte blanche (the default) but from some prefilled string

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
 * TranslateProcessAPIMessageGroupsProperties : Allows exrra property requests to be acted upon, and the new new properties returned

array         &$list: List of languages indexed by language code string         $language: Language code of the language of which language names are in
 * TranslateSupportedLanguages : Allows removing languages from language selectors. For adding $wgExtraLanguage names is recommended.

array         &$types: List of translation aid identifiers, numerically indexed
 * TranslateTranslationAids : Make new translation aids available to any message group (which must choose an implementation in its getTranslationAids method).


 * AddNewAccount : Replica of the core hook, see https://www.mediawiki.org/wiki/Manual:Hooks/AddNewAccount

JavaScript events
jQuery         form: The form that has just been submitted
 * afterSubmit : Provides an opportunity to modify a Translate translation form immediately after it is submitted

jQuery         form: The form being submitted
 * beforeSubmit : Provides an opportunity to modify a Translate translation form immediately before it is submitted

object         message: The message object, with a range of useful (and manipulable) properties
 * formatMessageBeforeTable : Provides an opportunity to manipulate the display of translation strings (messages) in the main table

object         result.helpers: JSON subset focusing on the helpers returned e.g. result.helpers.definition jQuery         translateEditor.$editor: The current translation-editing form
 * showTranslationHelpers : Provides an opportunity to handle custom translation helpers