annotate core/modules/locale/locale.api.php @ 19:fa3358dc1485 tip

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