Drupal investigation

locale.api.php 5.4KB

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