3 namespace Drupal\language;
5 use Drupal\Core\Session\AccountInterface;
8 * Common interface for language negotiation services.
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.
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
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().
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)
37 * function mymodule_language_types_info_alter(&$language_types) {
38 * unset($language_types[LanguageInterface::TYPE_CONTENT]['fixed']);
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()
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.
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
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:
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';
78 * class MyLanguageNegotiationUrl extends LanguageNegotiationUrl {
79 * public function getCurrentLanguage(Request $request = NULL) {
81 * // Use the original URL language negotiation method to get a valid
83 * $langcode = parent::getCurrentLanguage($request);
85 * // If we are on an administrative path, override with the default
87 * if ($request->query->has('q') && strtok($request->query->get('q'), '/') == 'admin') {
88 * return $this->languageManager->getDefaultLanguage()->getId();
97 * For more information, see
98 * @link https://www.drupal.org/node/1497272 Language Negotiation API @endlink
100 interface LanguageNegotiatorInterface {
103 * The language negotiation method id for the language negotiator itself.
105 const METHOD_ID = 'language-default';
108 * Resets the negotiated languages and the method instances.
110 public function reset();
113 * Sets the current active user and resets all language types.
115 * @param \Drupal\Core\Session\AccountInterface $current_user
116 * The current active user.
118 public function setCurrentUser(AccountInterface $current_user);
121 * Initializes the specified language type.
123 * @param string $type
124 * The language type to be initialized.
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.
131 public function initializeType($type);
134 * Returns the language negotiation methods enabled for a language type.
136 * @param string $type
137 * (optional) The language type. If no type is specified all the method
138 * definitions are returned.
141 * An array of language negotiation method definitions keyed by method id.
143 public function getNegotiationMethods($type = NULL);
146 * Returns an instance of the specified language negotiation method.
148 * @param string $method_id
149 * The method identifier.
151 * @return \Drupal\language\LanguageNegotiationMethodInterface
153 public function getNegotiationMethodInstance($method_id);
156 * Returns the ID of the language type's primary language negotiation method.
158 * @param string $type
162 * The identifier of the primary language negotiation method for the given
163 * language type, or the default method if none exists.
165 public function getPrimaryNegotiationMethod($type);
168 * Checks whether a language negotiation method is enabled for a language type.
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.
177 * TRUE if the method is enabled for at least one of the given language
178 * types, or FALSE otherwise.
180 public function isNegotiationMethodEnabled($method_id, $type = NULL);
183 * Saves a list of language negotiation methods for a language type.
185 * @param string $type
187 * @param int[] $enabled_methods
188 * An array of language negotiation method weights keyed by method ID.
190 public function saveConfiguration($type, $enabled_methods);
193 * Resave the configuration to purge missing negotiation methods.
195 public function purgeConfiguration();
198 * Updates the configuration based on the given language types.
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
204 * @param string[] $types
205 * An array of configurable language types.
207 public function updateConfiguration(array $types);