yaffs.net Git - yaffs-website/blob - web/core/modules/language/src/LanguageNegotiatorInterface.php

   1 <?php
   2
   3 namespace Drupal\language;
   4
   5 use Drupal\Core\Session\AccountInterface;
   6
   7 /**
   8  * Common interface for language negotiation services.
   9  *
  10  * The language negotiation API is based on two major concepts:
  11  * - Language types: types of translatable data (the types of data that a user
  12  *   can view or request).
  13  * - Language negotiation methods: responsible for determining which language to
  14  *   use to present a particular piece of data to the user.
  15  * Both language types and language negotiation methods are customizable.
  16  *
  17  * Drupal defines three built-in language types:
  18  * - Interface language: The page's main language, used to present translated
  19  *   user interface elements such as titles, labels, help text, and messages.
  20  * - Content language: The language used to present content that is available
  21  *   in more than one language.
  22  * - URL language: The language associated with URLs. When generating a URL,
  23  *   this value will be used for URL's as a default if no explicit preference is
  24  *   provided.
  25  * Modules can define additional language types through
  26  * hook_language_types_info(), and alter existing language type definitions
  27  * through hook_language_types_info_alter().
  28  *
  29  * Language types may be configurable or fixed. The language negotiation
  30  * methods associated with a configurable language type can be explicitly
  31  * set through the user interface. A fixed language type has predetermined
  32  * (module-defined) language negotiation settings and, thus, does not appear in
  33  * the configuration page. Here is a code snippet that makes the content
  34  * language (which by default inherits the interface language's values)
  35  * configurable:
  36  * @code
  37  * function mymodule_language_types_info_alter(&$language_types) {
  38  *   unset($language_types[LanguageInterface::TYPE_CONTENT]['fixed']);
  39  * }
  40  * @endcode
  41  *
  42  * The locked configuration property prevents one language type from being
  43  * switched from customized to not customized, and vice versa.
  44  * @see \Drupal\language\LanguageNegotiator::updateConfiguration()
  45  *
  46  * Every language type can have a different set of language negotiation methods
  47  * assigned to it. Different language types often share the same language
  48  * negotiation settings, but they can have independent settings if needed. If
  49  * two language types are configured the same way, their language switcher
  50  * configuration will be functionally identical and the same settings will act
  51  * on both language types.
  52  *
  53  * Drupal defines the following built-in language negotiation methods:
  54  * - URL: Determine the language from the URL (path prefix or domain).
  55  * - Session: Determine the language from a request/session parameter.
  56  * - User: Follow the user's language preference.
  57  * - User admin language: Identify admin language from the user preferences.
  58  * - Browser: Determine the language from the browser's language settings.
  59  * - Selected language: Use the default site language.
  60  * Language negotiation methods are simple plugin classes that implement a
  61  * particular logic to return a language code. For instance, the URL method
  62  * searches for a valid path prefix or domain name in the current request URL.
  63  * If a language negotiation method does not return a valid language code, the
  64  * next method associated with the language type (based on method weight) is
  65  * invoked.
  66  *
  67  * Modules can define additional language negotiation methods by simply provide
  68  * the related plugins, and alter existing methods through
  69  * hook_language_negotiation_info_alter(). Here is an example snippet that lets
  70  * path prefixes be ignored for administrative paths:
  71  * @code
  72  * function mymodule_language_negotiation_info_alter(&$negotiation_info) {
  73  *   // Replace the original plugin with our own implementation.
  74  *   $method_id = \Drupal\language\Plugin\LanguageNegotiation\LanguageNegotiationUrl::METHOD_ID;
  75  *   $negotiation_info[$method_id]['class'] = 'Drupal\my_module\Plugin\LanguageNegotiation\MyLanguageNegotiationUrl';
  76  * }
  77  *
  78  * class MyLanguageNegotiationUrl extends LanguageNegotiationUrl {
  79  *   public function getCurrentLanguage(Request $request = NULL) {
  80  *     if ($request) {
  81  *       // Use the original URL language negotiation method to get a valid
  82  *       // language code.
  83  *       $langcode = parent::getCurrentLanguage($request);
  84  *
  85  *       // If we are on an administrative path, override with the default
  86  *       language.
  87  *       if ($request->query->has('q') && strtok($request->query->get('q'), '/') == 'admin') {
  88  *         return $this->languageManager->getDefaultLanguage()->getId();
  89  *       }
  90  *       return $langcode;
  91  *     }
  92  *   }
  93  * }
  94  * ?>
  95  * @endcode
  96  *
  97  * For more information, see
  98  * @link https://www.drupal.org/node/1497272 Language Negotiation API @endlink
  99  */
 100 interface LanguageNegotiatorInterface {
 101
 102   /**
 103    * The language negotiation method id for the language negotiator itself.
 104    */
 105   const METHOD_ID = 'language-default';
 106
 107   /**
 108    * Resets the negotiated languages and the method instances.
 109    */
 110   public function reset();
 111
 112   /**
 113    * Sets the current active user and resets all language types.
 114    *
 115    * @param \Drupal\Core\Session\AccountInterface $current_user
 116    *   The current active user.
 117    */
 118   public function setCurrentUser(AccountInterface $current_user);
 119
 120   /**
 121    * Initializes the specified language type.
 122    *
 123    * @param string $type
 124    *   The language type to be initialized.
 125    *
 126    * @return \Drupal\Core\Language\LanguageInterface[]
 127    *   Returns an array containing a single language keyed by the language
 128    *   negotiation method ID used to determine the language of the specified
 129    *   type. If negotiation is not possible the default language is returned.
 130    */
 131   public function initializeType($type);
 132
 133   /**
 134    * Returns the language negotiation methods enabled for a language type.
 135    *
 136    * @param string $type
 137    *   (optional) The language type. If no type is specified all the method
 138    *   definitions are returned.
 139    *
 140    * @return array[]
 141    *   An array of language negotiation method definitions keyed by method id.
 142    */
 143   public function getNegotiationMethods($type = NULL);
 144
 145   /**
 146    * Returns an instance of the specified language negotiation method.
 147    *
 148    * @param string $method_id
 149    *   The method identifier.
 150    *
 151    * @return \Drupal\language\LanguageNegotiationMethodInterface
 152    */
 153   public function getNegotiationMethodInstance($method_id);
 154
 155   /**
 156    * Returns the ID of the language type's primary language negotiation method.
 157    *
 158    * @param string $type
 159    *   The language type.
 160    *
 161    * @return string
 162    *   The identifier of the primary language negotiation method for the given
 163    *   language type, or the default method if none exists.
 164    */
 165   public function getPrimaryNegotiationMethod($type);
 166
 167   /**
 168    * Checks whether a language negotiation method is enabled for a language type.
 169    *
 170    * @param string $method_id
 171    *   The language negotiation method ID.
 172    * @param string $type
 173    *   (optional) The language type. If none is passed, all the configurable
 174    *   language types will be inspected.
 175    *
 176    * @return bool
 177    *   TRUE if the method is enabled for at least one of the given language
 178    *   types, or FALSE otherwise.
 179    */
 180   public function isNegotiationMethodEnabled($method_id, $type = NULL);
 181
 182   /**
 183    * Saves a list of language negotiation methods for a language type.
 184    *
 185    * @param string $type
 186    *   The language type.
 187    * @param int[] $enabled_methods
 188    *   An array of language negotiation method weights keyed by method ID.
 189    */
 190   public function saveConfiguration($type, $enabled_methods);
 191
 192   /**
 193    * Resave the configuration to purge missing negotiation methods.
 194    */
 195   public function purgeConfiguration();
 196
 197   /**
 198    * Updates the configuration based on the given language types.
 199    *
 200    * Stores the list of the language types along with information about their
 201    * configurable state. Stores the default settings if the language type is
 202    * not configurable.
 203    *
 204    * @param string[] $types
 205    *   An array of configurable language types.
 206    */
 207   public function updateConfiguration(array $types);
 208
 209 }