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