LanguageNegotiatorInterface.php 7.87 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
<?php

/**
 * @file
 * Contains \Drupal\language\LanguageNegotiatorInterface
 */

namespace Drupal\language;

use Drupal\Core\Session\AccountInterface;
use Symfony\Component\HttpFoundation\Request;

/**
 * Common interface for language negotiation services.
 *
 * The language negotiation API is based on two major concepts:
 * - Language types: types of translatable data (the types of data that a user
 *   can view or request).
 * - Language negotiation methods: responsible for determining which language to
 *   use to present a particular piece of data to the user.
 * Both language types and language negotiation methods are customizable.
 *
 * Drupal defines three built-in language types:
 * - Interface language: The page's main language, used to present translated
 *   user interface elements such as titles, labels, help text, and messages.
 * - Content language: The language used to present content that is available
 *   in more than one language.
 * - URL language: The language associated with URLs. When generating a URL,
 *   this value will be used by url() as a default if no explicit preference is
 *   provided.
 * Modules can define additional language types through
 * hook_language_types_info(), and alter existing language type definitions
 * through hook_language_types_info_alter().
 *
 * Language types may be configurable or fixed. The language negotiation
 * methods associated with a configurable language type can be explicitly
 * set through the user interface. A fixed language type has predetermined
 * (module-defined) language negotiation settings and, thus, does not appear in
 * the configuration page. Here is a code snippet that makes the content
 * language (which by default inherits the interface language's values)
 * configurable:
 * @code
 * function mymodule_language_types_info_alter(&$language_types) {
 *   unset($language_types[Language::TYPE_CONTENT]['fixed']);
 * }
 * @endcode
 *
 * The locked configuration property prevents one language type from being
 * switched from customized to not customized, and vice versa.
 * @see \Drupal\language\LanguageNegotiator::updateConfiguration()
 *
 * Every language type can have a different set of language negotiation methods
 * assigned to it. Different language types often share the same language
 * negotiation settings, but they can have independent settings if needed. If
 * two language types are configured the same way, their language switcher
 * configuration will be functionally identical and the same settings will act
 * on both language types.
 *
 * Drupal defines the following built-in language negotiation methods:
 * - URL: Determine the language from the URL (path prefix or domain).
 * - Session: Determine the language from a request/session parameter.
 * - User: Follow the user's language preference.
 * - User admin language: Identifie admin language from the user preferences.
 * - Browser: Determine the language from the browser's language settings.
 * - Selected language: Use the default site language.
 * Language negotiation methods are simple plugin classes that implement a
 * particular logic to return a language code. For instance, the URL method
 * searches for a valid path prefix or domain name in the current request URL.
 * If a language negotiation method does not return a valid language code, the
 * next method associated to the language type (based on method weight) is
 * invoked.
 *
 * Modules can define additional language negotiation methods by simply provide
 * the related plugins, and alter existing methods through
 * hook_language_negotiation_info_alter(). Here is an example snippet that lets
 * path prefixes be ignored for administrative paths:
 * @code
 * function mymodule_language_negotiation_info_alter(&$negotiation_info) {
 *   // Replace the original plugin with our own implementation.
 *   $method_id = \Drupal\language\Plugin\LanguageNegotiation\LanguageNegotiationUrl::METHOD_ID;
 *   $negotiation_info[$method_id]['class'] = 'Drupal\my_module\Plugin\LanguageNegotiation\MyLanguageNegotiationUrl';
 * }
 *
 * class MyLanguageNegotiationUrl extends LanguageNegotiationUrl {
 *   public function getCurrentLanguage(Request $request = NULL) {
 *     if ($request) {
 *       // Use the original URL language negotiation method to get a valid
 *       // language code.
 *       $langcode = parent::getCurrentLanguage($request);
 *
 *       // If we are on an administrative path, override with the default
 *       language.
 *       if ($request->query->has('q') && strtok($request->query->get('q'), '/') == 'admin') {
 *         return $this->languageManager->getDefaultLanguage()->id;
 *       }
 *       return $langcode;
 *     }
 *   }
 * }
 * ?>
 * @endcode
 *
 * For more information, see
 * @link http://drupal.org/node/1497272 Language Negotiation API @endlink
 */
interface LanguageNegotiatorInterface {

  /**
   * The language negotiation method id for the language negotiator itself.
   */
  const METHOD_ID = 'language-default';

  /**
   * Resets the negotiated languages and the method instances.
   */
  public function reset();

  /**
   * Sets the current active user and resets all language types.
   *
   * @param \Drupal\Core\Session\AccountInterface $current_user
   *   The current active user.
   */
  public function setCurrentUser(AccountInterface $current_user);

  /**
   * Sets the active request and resets all language types.
   *
   * @param \Symfony\Component\HttpFoundation\Request $request
   *   The HttpRequest object representing the current request.
   */
  public function setRequest(Request $request);

  /**
   * Initializes the specified language type.
   *
   * @param string $type
   *   The language type to be initialized.
   *
   * @return \Drupal\Core\Language\Language
   *   Return either the language of the specified type or the default language.
   */
  public function initializeType($type);

  /**
   * Returns the language negotiation methods enabled for a language type.
   *
   * @param string $type
   *   (optional) The language type. If no type is specified all the method
   *   definitions are returned.
   *
   * @return array
   *   An array of language negotiation method definitions keyed by method id.
   */
  public function getNegotiationMethods($type = NULL);

  /**
   * Returns an instance of the specified language negotiation method.
   *
   * @param string $method_id
   *   The method identifier.
   *
   * @return \Drupal\language\LanguageNegotiationMethodInterface
   */
  public function getNegotiationMethodInstance($method_id);

  /**
   * Returns the ID of the language type's primary language negotiation method.
   *
   * @param $type
   *   The language type.
   *
   * @return
   *   The identifier of the primary language negotiation method for the given
   *   language type, or the default method if none exists.
   */
  public function getPrimaryNegotiationMethod($type);

  /**
   * Checks whether a language negotiation method is enabled for a language type.
   *
   * @param $method_id
   *   The language negotiation method ID.
   * @param $type
   *   (optional) The language type. If none is passed, all the configurable
   *   language types will be inspected.
   *
   * @return
   *   TRUE if the method is enabled for at least one of the given language
   *   types, or FALSE otherwise.
   */
  public function isNegotiationMethodEnabled($method_id, $type = NULL);

  /**
   * Saves a list of language negotiation methods for a language type.
   *
   * @param string $type
   *   The language type.
199
   * @param array $enabled_methods
200 201
   *   An array of language negotiation method weights keyed by method ID.
   */
202
  function saveConfiguration($type, $enabled_methods);
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217

  /**
   * Resave the configuration to purge missing negotiation methods.
   */
  function purgeConfiguration();

  /**
   * Updates the configuration based on the given language types.
   *
   * @param array $types
   *   An array of configurable language types.
   */
  function updateConfiguration(array $types);

}