273 lines
8.9 KiB
PHP
273 lines
8.9 KiB
PHP
<?php
|
|
|
|
/**
|
|
* @file
|
|
* Hooks provided by the Translation Management module.
|
|
*/
|
|
|
|
/**
|
|
* @addtogroup tmgmt_source
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Provide information about source plugins.
|
|
*
|
|
* @see TMGMTTestSourcePluginController
|
|
*/
|
|
function hook_tmgmt_source_plugin_info() {
|
|
return array(
|
|
'test_source' => array(
|
|
'label' => t('Test source'),
|
|
'description' => t('Simple source for testing purposes.'),
|
|
'controller class' => 'TMGMTTestSourcePluginController',
|
|
),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Alter source plugins information.
|
|
*
|
|
* @param $info
|
|
* The defined source plugin information.
|
|
*
|
|
* @see hook_tmgmt_source_plugin_info()
|
|
*/
|
|
function hook_tmgmt_source_plugin_info_alter(&$info) {
|
|
$info['test_source']['description'] = t('Updated description');
|
|
}
|
|
|
|
/**
|
|
* Return a list of suggested sources for job items.
|
|
*
|
|
* @param array $items
|
|
* An array with TMGMTJobItem objects which must be checked for suggested
|
|
* translations.
|
|
* - TMGMTJobItem A JobItem to check for suggestions.
|
|
* - ...
|
|
* @param TMGMTJob $job
|
|
* The current translation job to check for additional translation items.
|
|
*
|
|
* @return array
|
|
* An array with all additional translation suggestions.
|
|
* - job_item: A TMGMTJobItem instance.
|
|
* - referenced: A string which indicates where this suggestion comes from.
|
|
* - from_job: The main TMGMTJob-ID which suggests this translation.
|
|
*/
|
|
function hook_tmgmt_source_suggestions(array $items, TMGMTJob $job) {
|
|
return array(
|
|
array(
|
|
'job_item' => tmgmt_job_item_create('entity', 'node', 0),
|
|
'reason' => t('Referenced @type of field @label', array('@type' => 'entity', '@label' => 'label')),
|
|
'from_item' => $items[1]->tjiid,
|
|
)
|
|
);
|
|
}
|
|
|
|
/**
|
|
* @} End of "addtogroup tmgmt_source".
|
|
*/
|
|
|
|
/**
|
|
* @addtogroup tmgmt_translator
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* Provide information about translator plugins.
|
|
*
|
|
* @see TMGMTTestTranslatorPluginController
|
|
*/
|
|
function hook_tmgmt_translator_plugin_info() {
|
|
return array(
|
|
'test_translator' => array(
|
|
'label' => t('Test translator'),
|
|
'description' => t('Simple translator for testing purposes.'),
|
|
'plugin controller class' => 'TMGMTTestTranslatorPluginController',
|
|
'ui controller class' => 'TMGMTTestTranslatorUIController',
|
|
'default settings' => array(
|
|
'expose_settings' => TRUE,
|
|
),
|
|
// By default, a translator is automatically created with the default
|
|
// settings. Set auto create to FALSE to prevent this.
|
|
'auto create' => TRUE,
|
|
// If the translator should provide remote languages mappings feature.
|
|
// It defaults to TRUE.
|
|
'map remote languages' => FALSE,
|
|
// Flag defining if job settings are handled by plugin itself.
|
|
// Defaults to FALSE.
|
|
'job settings custom handling' => FALSE,
|
|
),
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Alter information about translator plugins.
|
|
*/
|
|
function hook_tmgmt_translator_plugin_info_alter(&$info) {
|
|
$info['test_source']['description'] = t('Updated description');
|
|
}
|
|
|
|
/**
|
|
* @} End of "addtogroup tmgmt_translator".
|
|
*/
|
|
|
|
/**
|
|
* @defgroup tmgmt_job Translation Jobs
|
|
*
|
|
* A single task to translate something into a given language using a @link
|
|
* translator translator @endlink.
|
|
*
|
|
* Attached to these jobs are job items, which specify which @link source
|
|
* sources @endlink are to be translated.
|
|
*
|
|
* To create a new translation job, first create a job and then assign items to
|
|
* each. Each item needs to specify the source plugin that should be used
|
|
* and the type and id, which the source plugin then uses to identify it later
|
|
* on.
|
|
*
|
|
* @code
|
|
* $job = tmgmt_job_create('en', $target_language);
|
|
*
|
|
* for ($i = 1; $i < 3; $i++) {
|
|
* $job->addItem('test_source', 'test', $i);
|
|
* }
|
|
* @endcode
|
|
*
|
|
* Once a job has been created, it can be assigned to a translator plugin, which
|
|
* is the service that is going to do the translation.
|
|
*
|
|
* @code
|
|
* $job->translator = 'test_translator';
|
|
* // Translator specific settings.
|
|
* $job->settings = array(
|
|
* 'priority' => 5,
|
|
* );
|
|
* $job->save();
|
|
*
|
|
* // Get the translator plugin and request a translation.
|
|
* if ($job->isTranslatable()) {
|
|
* $job->requestTranslation();
|
|
* }
|
|
* @endcode
|
|
*
|
|
* The translation plugin will then request the text from the source plugin.
|
|
* Depending on the plugin, the text might be sent to an external service
|
|
* or assign it to a local user or team of users. At some point, a translation
|
|
* will be returned and saved in the job items.
|
|
*
|
|
* The translation can now be reviewed, accepted and the source plugins be told
|
|
* to save the translation.
|
|
*
|
|
* @code
|
|
* $job->accepted('Optional message');
|
|
* @endcode
|
|
*/
|
|
|
|
/**
|
|
* @defgroup tmgmt_translator Translators
|
|
*
|
|
* A translator plugin integrates a translation service.
|
|
*
|
|
* To define a translator, hook_tmgmt_translator_plugin_info() needs to be
|
|
* implemented and a controller class (specified in the info) created.
|
|
*
|
|
* A translator plugin is then responsible for sending out a translation job and
|
|
* storing the translated texts back into the job and marking it as needs review
|
|
* once it's finished.
|
|
*
|
|
* TBD.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup tmgmt_source Translation source
|
|
*
|
|
* A source plugin represents translatable elements on a site.
|
|
*
|
|
* For example nodes, but also plain strings, menu items, other entities and so
|
|
* on.
|
|
*
|
|
* To define a source, hook_tmgmt_source_plugin_info() needs to be implemented
|
|
* and a controller class (specified in the info) created.
|
|
*
|
|
* A source has three separate tasks.
|
|
*
|
|
* - Allows to create a new @link job translation job @endlink and assign job
|
|
* items to itself.
|
|
* - Extract the translatable text into a nested array when
|
|
* requested to do in their implementation of
|
|
* TMGMTSourcePluginControllerInterface::getData().
|
|
* - Save the accepted translations returned by the translation plugin in their
|
|
* sources in their implementation of
|
|
* TMGMTSourcePluginControllerInterface::saveTranslation().
|
|
*/
|
|
|
|
/**
|
|
* @defgroup tmgmt_remote_languages_mapping Remote languages mapping
|
|
*
|
|
* Logic to deal with different language codes at client and server that stand
|
|
* for the same language.
|
|
*
|
|
* Each tmgmt plugin is expected to support this feature. However for those
|
|
* plugins where such feature has no use there is a plugin setting
|
|
* "map remote languages" which can be set to FALSE.
|
|
*
|
|
* @section mappings_info Mappings info
|
|
*
|
|
* There are several methods defined by
|
|
* TMGMTTranslatorPluginControllerInterface and implemented in
|
|
* TMGMTDefaultTranslatorPluginController that deal with mappings info.
|
|
*
|
|
* - getRemoteLanguagesMappings() - provides pairs of local_code => remote_code.
|
|
* - mapToRemoteLanguage() & mapToLocalLanguage() - helpers to map local/remote.
|
|
* Note that methods with same names and functionality are provided by the
|
|
* TMGMTTranslator entity. These are convenience methods.
|
|
*
|
|
* The above methods should not need reimplementation unless special logic is
|
|
* needed. However following methods provide only the fallback behaviour and
|
|
* therefore it is recommended that each plugin provides its specific
|
|
* implementation.
|
|
*
|
|
* - getDefaultRemoteLanguagesMappings() - we might know some mapping pairs
|
|
* prior to configuring a plugin, this is the place where we can define these
|
|
* mappings. The default implementation returns an empty array.
|
|
* - getSupportedRemoteLanguages() - gets array of language codes in lang_code =>
|
|
* lang_code format. It says with what languages the remote system can deal
|
|
* with. These codes are in the remote format.
|
|
*
|
|
* @section mapping_remote_to_local Mapping remote to local
|
|
*
|
|
* Mapping remote to local language codes is done when determining the
|
|
* language capabilities of the remote system. All following logic should then
|
|
* solely work with local language codes. There are two methods defined by
|
|
* the TMGMTTranslatorPluginControllerInterface interface. To do the mapping
|
|
* a plugin must implement getSupportedTargetLanguages().
|
|
*
|
|
* - getSupportedTargetLanguages() - should return local language codes. So
|
|
* within this method the mapping needs to be executed.
|
|
* - getSupportedLanguagePairs() - gets language pairs for which translations
|
|
* can be done. The language codes must be in local form. The default
|
|
* implementation uses getSupportedTargetLanguages() so mapping occur. However
|
|
* this approach is not effective and therefore each plugin should provide
|
|
* its specific implementation with regard to performance.
|
|
*
|
|
* @section mapping_local_to_remote Mapping local to remote
|
|
*
|
|
* Mapping of local to remote language codes is done upon translation job
|
|
* request in the TMGMTTranslatorPluginControllerInterface::requestTranslation()
|
|
* plugin implementation.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup tmgmt_ui_cart Translation cart
|
|
*
|
|
* The translation cart can collect multiple source items of different types
|
|
* which are meant for translation into a list. The list then provides
|
|
* functionality to request translation of the items into multiple target
|
|
* languages.
|
|
*
|
|
* Each source can easily plug into the cart system utilising the
|
|
* tmgmt_ui_add_cart_form() on either the source overview page as well as the
|
|
* translate tab.
|
|
*/
|