www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/locale/locale.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks provided by the Locale module.
   6  */
   7
   8 /**
   9  * @defgroup interface_translation_properties Interface translation properties
  10  * @{
  11  * .info.yml file properties for interface translation settings.
  12  *
  13  * For modules hosted on drupal.org, a project definition is automatically added
  14  * to the .info.yml file. Only modules with this project definition are
  15  * discovered by the update module and use it to check for new releases. Locale
  16  * module uses the same data to build a list of modules to check for new
  17  * translations. Therefore modules not hosted at drupal.org, such as custom
  18  * modules, custom themes, features and distributions, need a way to identify
  19  * themselves to the Locale module if they have translations that require to be
  20  * updated.
  21  *
  22  * Custom modules which contain new strings should provide po file(s) containing
  23  * source strings and string translations in gettext format. The translation
  24  * file can be located both local and remote. Use the following .info.yml file
  25  * properties to inform Locale module to load and import the translations.
  26  *
  27  * Example .info.yml file properties for a custom module with a po file located
  28  * in the module's folder.
  29  * @code
  30  * 'interface translation project': example_module
  31  * 'interface translation server pattern': modules/custom/example_module/%project-%version.%language.po
  32  * @endcode
  33  *
  34  * Streamwrappers can be used in the server pattern definition. The interface
  35  * translations directory (Configuration > Media > File system) can be addressed
  36  * using the "translations://" streamwrapper. But also other streamwrappers can
  37  * be used.
  38  * @code
  39  * 'interface translation server pattern': translations://%project-%version.%language.po
  40  * @endcode
  41  * @code
  42  * 'interface translation server pattern': public://translations/%project-%version.%language.po
  43  * @endcode
  44  *
  45  * Multiple custom modules or themes sharing the same po file should have
  46  * matching definitions. Such as modules and sub-modules or multiple modules in
  47  * the same project/code tree. Both "interface translation project" and
  48  * "interface translation server pattern" definitions of these modules should
  49  * match.
  50  *
  51  * Example .info.yml file properties for a custom module with a po file located
  52  * on a remote translation server.
  53  * @code
  54  * 'interface translation project': example_module
  55  * 'interface translation server pattern': http://example.com/files/translations/%core/%project/%project-%version.%language.po
  56  * @endcode
  57  *
  58  * Custom themes, features and distributions can implement these .info.yml file
  59  * properties in their .info.yml file too.
  60  *
  61  * To change the interface translation settings of modules and themes hosted at
  62  * drupal.org use hook_locale_translation_projects_alter(). Possible changes
  63  * include changing the po file location (server pattern) or removing the
  64  * project from the translation update list.
  65  *
  66  * Available .info.yml file properties:
  67  * - "interface translation project": project name. Required.
  68  *   Name of the project a (sub-)module belongs to. Multiple modules sharing
  69  *   the same project name will be listed as one the translation status list.
  70  * - "interface translation server pattern": URL of the .po translation files
  71  *   used to download the files from. The URL contains tokens which will be
  72  *   replaced by appropriate values. The file can be locate both at a local
  73  *   relative path, a local absolute path and a remote server location.
  74  *
  75  * The following tokens are available for the server pattern:
  76  * - "%core": Core version. Value example: "8.x".
  77  * - "%project": Project name. Value examples: "drupal", "media_gallery".
  78  * - "%version": Project version release. Value examples: "8.1", "8.x-1.0".
  79  * - "%language": Language code. Value examples: "fr", "pt-pt".
  80  *
  81  * @see i18n
  82  * @}
  83  */
  84
  85 /**
  86  * @addtogroup hooks
  87  * @{
  88  */
  89
  90 /**
  91  * Alter the list of projects to be updated by locale's interface translation.
  92  *
  93  * Locale module attempts to update the translation of those modules returned
  94  * by \Drupal\Update\UpdateManager::getProjects(). Using this hook, the data
  95  * returned by \Drupal\Update\UpdateManager::getProjects() can be altered or
  96  * extended.
  97  *
  98  * Modules or distributions that use a dedicated translation server should use
  99  * this hook to specify the interface translation server pattern, or to add
 100  * additional custom/non-Drupal.org modules to the list of modules known to
 101  * locale.
 102  * - "interface translation server pattern": URL of the .po translation files
 103  *   used to download the files from. The URL contains tokens which will be
 104  *   replaced by appropriate values.
 105  * The following tokens are available for the server pattern:
 106  * - "%core": Core version. Value example: "8.x".
 107  * - "%project": Project name. Value examples: "drupal", "media_gallery".
 108  * - "%version": Project version release. Value examples: "8.1", "8.x-1.0".
 109  * - "%language": Language code. Value examples: "fr", "pt-pt".
 110  *
 111  * @param array $projects
 112  *   Project data as returned by \Drupal\Update\UpdateManager::getProjects().
 113  *
 114  * @see locale_translation_project_list()
 115  * @ingroup interface_translation_properties
 116  */
 117 function hook_locale_translation_projects_alter(&$projects) {
 118   // The translations are located at a custom translation sever.
 119   $projects['existing_project'] = [
 120     'info' => [
 121       'interface translation server pattern' => 'http://example.com/files/translations/%core/%project/%project-%version.%language.po',
 122     ],
 123   ];
 124 }
 125
 126 /**
 127  * @} End of "addtogroup hooks".
 128  */