locale.api.php

Hooks provided by the Locale module.

File

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

Functions

Namesort descending Description
hook_locale_translation_projects_alter Alter the list of projects to be updated by locale's interface translation.