updated core to 7.58 (right after the site was hacked)

sites/all/modules/contrib/localisation/tmgmt/tmgmt.api.php

@@ -0,0 +1,272 @@
+<?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.
+ */