language.inc 18.2 KB
Newer Older
1
2
3
4
<?php

/**
 * @file
5
6
7
 * Language Negotiation API.
 *
 * @see http://drupal.org/node/1497272
8
9
10
 */

/**
11
12
 * No language negotiation. The default language is used.
 */
13
const LANGUAGE_NEGOTIATION_DEFAULT = 'language-default';
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
 * @defgroup language_negotiation Language Negotiation API functionality
 * @{
 * Functions to customize the language types and the negotiation process.
 *
 * 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: functions 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 (see
 *   @link field_language Field Language API @endlink for details).
 * - 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
 *
 * 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.
 * - Browser: Determine the language from the browser's language settings.
 * - Default language: Use the default site language.
 * Language negotiation methods are simple callback functions 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 through
 * hook_language_negotiation_info(), 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 core function with our own function.
 *   module_load_include('language', 'inc', 'language.negotiation');
 *   $negotiation_info[LANGUAGE_NEGOTIATION_URL]['callbacks']['negotiation'] = 'mymodule_from_url';
 *   $negotiation_info[LANGUAGE_NEGOTIATION_URL]['file'] = drupal_get_path('module', 'mymodule') . '/mymodule.module';
 * }
 *
 * function mymodule_from_url($languages) {
 *   // Use the core URL language negotiation method to get a valid language
 *   // code.
 *   module_load_include('language', 'inc', 'language.negotiation');
 *   $langcode = language_from_url($languages);
 *
 *   // If we are on an administrative path, override with the default language.
 *   if (isset($_GET['q']) && strtok($_GET['q'], '/') == 'admin') {
 *     return language_default()->langcode;
 *   }
 *   return $langcode;
 * }
 * ?>
 * @endcode
 *
 * For more information, see
 * @link http://drupal.org/node/1497272 Language Negotiation API @endlink
 */

/**
 * Chooses a language based on language negotiation method settings.
106
107
 *
 * @param $type
108
 *   The language type key to find the language for.
109
 *
110
111
112
 * @param $request
 *   The HttpReqeust object representing the current request.
 *
113
114
115
 * @return
 *   The negotiated language object.
 */
116
function language_types_initialize($type, $request = NULL) {
117
118
  // Execute the language negotiation methods in the order they were set up and
  // return the first valid language found.
119
120
  $negotiation = variable_get("language_negotiation_$type", array());

121
  foreach ($negotiation as $method_id => $method) {
122
123
124
125
    // Skip negotiation methods not appropriate for this type.
    if (isset($method['types']) && !in_array($type, $method['types'])) {
      continue;
    }
126
    $language = language_negotiation_method_invoke($method_id, $method, $request);
127
    if ($language) {
128
129
      // Remember the method ID used to detect the language.
      $language->method_id = $method_id;
130
131
132
133
134
135
      return $language;
    }
  }

  // If no other language was found use the default one.
  $language = language_default();
136
  $language->method_id = LANGUAGE_NEGOTIATION_DEFAULT;
137
138
139
140
141
  return $language;
}

/**
 * Returns information about all defined language types.
142
143
 *
 * @return
144
145
146
147
 *   An associative array of language type information arrays keyed by type
 *   names. Based on information from hook_language_types_info().
 *
 * @see hook_language_types_info().
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 */
function language_types_info() {
  $language_types = &drupal_static(__FUNCTION__);

  if (!isset($language_types)) {
    $language_types = module_invoke_all('language_types_info');
    // Let other modules alter the list of language types.
    drupal_alter('language_types_info', $language_types);
  }

  return $language_types;
}

/**
162
 * Returns only the configurable language types.
163
164
 *
 * A language type maybe configurable or fixed. A fixed language type is a type
165
166
 * whose language negotiation methods are module-defined and not altered through
 * the user interface.
167
 *
168
 * @param $stored
169
170
171
172
173
 *   (optional) By default, retrieves values from the 'language_types' variable
 *   to avoid unnecessary hook invocations. If set to FALSE, retrieves values
 *   from the actual language type definitions. This allows reaction to
 *   alterations performed on the definitions by modules installed after the
 *   'language_types' variable is set.
174
 *
175
176
177
 * @return
 *   An array of language type names.
 */
178
function language_types_get_configurable($stored = TRUE) {
179
180
  $configurable = &drupal_static(__FUNCTION__);

181
  if ($stored && !isset($configurable)) {
182
    $types = variable_get('language_types', language_types_get_default());
183
184
185
    $configurable = array_keys(array_filter($types));
  }

186
187
188
189
190
191
192
193
194
195
  if (!$stored) {
    $result = array();
    foreach (language_types_info() as $type => $info) {
      if (!isset($info['fixed'])) {
        $result[] = $type;
      }
    }
    return $result;
  }

196
197
198
199
  return $configurable;
}

/**
200
 * Disables the given language types.
201
202
203
204
205
 *
 * @param $types
 *   An array of language types.
 */
function language_types_disable($types) {
206
  $enabled_types = variable_get('language_types', language_types_get_default());
207
208
209
210
211
212
213
214

  foreach ($types as $type) {
    unset($enabled_types[$type]);
  }

  variable_set('language_types', $enabled_types);
}

215
216
217
218
219
220
221
222
223
224
225
226
227
/**
 * Updates the language type configuration.
 */
function language_types_set() {
  // Ensure that we are getting the defined language negotiation information. An
  // invocation of module_enable() or module_disable() could outdate the cached
  // information.
  drupal_static_reset('language_types_info');
  drupal_static_reset('language_negotiation_info');

  // Determine which language types are configurable and which not by checking
  // whether the 'fixed' key is defined. Non-configurable (fixed) language types
  // have their language negotiation settings stored there.
228
  $language_types = array();
229
  $negotiation_info = language_negotiation_info();
230
231
232
  foreach (language_types_info() as $type => $info) {
    if (isset($info['fixed'])) {
      $language_types[$type] = FALSE;
233
234
235
236
      $method_weights = array();
      foreach ($info['fixed'] as $weight => $method_id) {
        if (isset($negotiation_info[$method_id])) {
          $method_weights[$method_id] = $weight;
237
238
        }
      }
239
      language_negotiation_set($type, $method_weights);
240
241
242
243
244
245
    }
    else {
      $language_types[$type] = TRUE;
    }
  }

246
  // Save enabled language types.
247
248
  variable_set('language_types', $language_types);

249
250
251
  // Ensure that subsequent calls of language_types_get_configurable() return
  // the updated language type information.
  drupal_static_reset('language_types_get_configurable');
252
253
}

254
/**
255
 * Returns the ID of the language type's first language negotiation method.
256
257
 *
 * @param $type
258
 *   The language type.
259
260
261
262
 *
 * @return
 *   The identifier of the first language negotiation method for the given
 *   language type, or the default method if none exists.
263
 */
264
function language_negotiation_method_get_first($type) {
265
  $negotiation = variable_get("language_negotiation_$type", array());
266
  return empty($negotiation) ? LANGUAGE_NEGOTIATION_DEFAULT : key($negotiation);
267
268
269
}

/**
270
 * Checks whether a language negotiation method is enabled for a language type.
271
 *
272
273
274
275
276
 * @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.
277
278
 *
 * @return
279
280
 *   TRUE if the method is enabled for at least one of the given language
 *   types, or FALSE otherwise.
281
 */
282
283
284
285
286
287
function language_negotiation_method_enabled($method_id, $type = NULL) {
  $language_types = !empty($type) ? array($type) : language_types_get_configurable();

  foreach ($language_types as $type) {
    $negotiation = variable_get("language_negotiation_$type", array());
    if (isset($negotiation[$method_id])) {
288
289
290
291
292
293
294
295
      return TRUE;
    }
  }

  return FALSE;
}

/**
296
 * Returns the language switch links for the given language type.
297
298
 *
 * @param $type
299
 *   The language type.
300
301
302
303
304
305
306
307
308
309
 * @param $path
 *   The internal path the switch links will be relative to.
 *
 * @return
 *   A keyed array of links ready to be themed.
 */
function language_negotiation_get_switch_links($type, $path) {
  $links = FALSE;
  $negotiation = variable_get("language_negotiation_$type", array());

310
311
312
313
  foreach ($negotiation as $method_id => $method) {
    if (isset($method['callbacks']['language_switch'])) {
      if (isset($method['file'])) {
        require_once DRUPAL_ROOT . '/' . $method['file'];
314
      }
315

316
      $callback = $method['callbacks']['language_switch'];
317
318
319
320
321
      $result = $callback($type, $path);

      if (!empty($result)) {
        // Allow modules to provide translations for specific links.
        drupal_alter('language_switch_links', $result, $type, $path);
322
        $links = (object) array('links' => $result, 'method_id' => $method_id);
323
        break;
324
      }
325
326
327
328
329
330
    }
  }

  return $links;
}

331
/**
332
 * Removes any language negotiation methods that are no longer defined.
333
334
335
336
337
338
339
340
 */
function language_negotiation_purge() {
  // Ensure that we are getting the defined language negotiation information. An
  // invocation of module_enable() or module_disable() could outdate the cached
  // information.
  drupal_static_reset('language_negotiation_info');
  drupal_static_reset('language_types_info');

341
  $negotiation_info = language_negotiation_info();
342
343
  foreach (language_types_info() as $type => $type_info) {
    $weight = 0;
344
345
346
347
    $method_weights = array();
    foreach (variable_get("language_negotiation_$type", array()) as $method_id => $method) {
      if (isset($negotiation_info[$method_id])) {
        $method_weights[$method_id] = $weight++;
348
349
      }
    }
350
    language_negotiation_set($type, $method_weights);
351
352
  }
}
353
354

/**
355
 * Saves a list of language negotiation methods for a language type.
356
357
 *
 * @param $type
358
359
 *   The language type.
 * @param $method_weights
360
 *   An array of language negotiation method weights keyed by method ID.
361
 */
362
function language_negotiation_set($type, $method_weights) {
363
  // Save only the necessary fields.
364
  $method_fields = array('callbacks', 'file', 'cache');
365
366

  $negotiation = array();
367
  $negotiation_info = language_negotiation_info();
368
  $default_types = language_types_get_configurable(FALSE);
369

370
371
372
373
374
375
376
377
378
  // Order the language negotiation method list by weight.
  asort($method_weights);

  foreach ($method_weights as $method_id => $weight) {
    if (isset($negotiation_info[$method_id])) {
      $method = $negotiation_info[$method_id];
      // If the language negotiation method does not express any preference
      // about types, make it available for any configurable type.
      $types = array_flip(isset($method['types']) ? $method['types'] : $default_types);
379
      // Check whether the method is defined and has the right type.
380
      if (isset($types[$type])) {
381
382
383
384
        $method_data = array();
        foreach ($method_fields as $field) {
          if (isset($method[$field])) {
            $method_data[$field] = $method[$field];
385
386
          }
        }
387
        $negotiation[$method_id] = $method_data;
388
389
      }
    }
390
  }
391

392
393
394
395
  variable_set("language_negotiation_$type", $negotiation);
}

/**
396
 * Returns all defined language negotiation methods.
397
398
 *
 * @return
399
 *   An array of language negotiation methods.
400
401
 */
function language_negotiation_info() {
402
  $negotiation_info = &drupal_static(__FUNCTION__);
403

404
405
406
  if (!isset($negotiation_info)) {
    // Collect all the module-defined language negotiation methods.
    $negotiation_info = module_invoke_all('language_negotiation_info');
407

408
409
    // Add the default language negotiation method.
    $negotiation_info[LANGUAGE_NEGOTIATION_DEFAULT] = array(
410
411
      'callbacks' => array('language' => 'language_from_default'),
      'weight' => 10,
412
      'name' => t('Default language'),
413
      'description' => t('Use the default site language (@language_name).', array('@language_name' => language_default()->name)),
414
      'config' => 'admin/config/regional/language',
415
416
    );

417
418
     // Let other modules alter the list of language negotiation methods.
     drupal_alter('language_negotiation_info', $negotiation_info);
419
  }
420

421
  return $negotiation_info;
422
423
424
}

/**
425
 * Invokes a language negotiation method and caches the results.
426
 *
427
 * @param $method_id
428
 *   The language negotiation method's identifier.
429
 * @param $method
430
431
432
 *   (optional) An associative array of information about the method to be
 *   invoked (see hook_language_negotiation_info() for details). If not passed
 *   in, it will be loaded through language_negotiation_info().
433
 *
434
435
436
 * @param $request
 *   (optional) The HttpRequest object representing the current request.
 *
437
 * @return
438
 *   A language object representing the language chosen by the method.
439
 */
440
function language_negotiation_method_invoke($method_id, $method = NULL, $request = NULL) {
441
  $results = &drupal_static(__FUNCTION__);
442

443
  if (!isset($results[$method_id])) {
444
445
    global $user;

446
    $languages = language_list();
447

448
449
450
    if (!isset($method)) {
      $negotiation_info = language_negotiation_info();
      $method = $negotiation_info[$method_id];
451
452
    }

453
454
    if (isset($method['file'])) {
      require_once DRUPAL_ROOT . '/' . $method['file'];
455
    }
456
457
458
459
    // If the language negotiation method has no cache preference or this is
    // satisfied we can execute the callback.
    $cache = !isset($method['cache']) || $user->uid || $method['cache'] == variable_get('cache', 0);
    $callback = isset($method['callbacks']['negotiation']) ? $method['callbacks']['negotiation'] : FALSE;
460
    $langcode = $cache && function_exists($callback) ? $callback($languages, $request) : FALSE;
461
    $results[$method_id] = isset($languages[$langcode]) ? $languages[$langcode] : FALSE;
462
  }
463

464
465
466
467
  // Since objects are resources, we need to return a clone to prevent the
  // language negotiation method cache from being unintentionally altered. The
  // same methods might be used with different language types based on
  // configuration.
468
  return !empty($results[$method_id]) ? clone($results[$method_id]) : $results[$method_id];
469
}
470
471

/**
472
 * Returns the default language code.
473
474
475
 *
 * @return
 *   The default language code.
476
 */
477
function language_from_default() {
478
  return language_default()->langcode;
479
}
480

481
482
483
/**
 * Split the given path into prefix and actual path.
 *
484
485
 * Parse the given path and return the language object identified by the prefix
 * and the actual path.
486
487
488
489
490
491
492
493
494
495
496
497
498
 *
 * @param $path
 *   The path to split.
 * @param $languages
 *   An array of valid languages.
 *
 * @return
 *   An array composed of:
 *    - A language object corresponding to the identified prefix on success,
 *      FALSE otherwise.
 *    - The path without the prefix on success, the given path otherwise.
 */
function language_url_split_prefix($path, $languages) {
499
  $args = empty($path) ? array() : explode('/', $path);
500
501
502
  $prefix = array_shift($args);

  // Search prefix within enabled languages.
503
  $prefixes = language_negotiation_url_prefixes();
504
  foreach ($languages as $language) {
505
    if (isset($prefixes[$language->langcode]) && $prefixes[$language->langcode] == $prefix) {
506
507
508
509
510
511
512
      // Rebuild $path with the language removed.
      return array($language, implode('/', $args));
    }
  }

  return array(FALSE, $path);
}
513
514
515
516
517
518
519
520
521
522
523
524
525
526

/**
 * Return the possible fallback languages ordered by language weight.
 *
 * @param
 *   The language type.
 *
 * @return
 *   An array of language codes.
 */
function language_fallback_get_candidates($type = LANGUAGE_TYPE_CONTENT) {
  $fallback_candidates = &drupal_static(__FUNCTION__);

  if (!isset($fallback_candidates)) {
527
    // Get languages ordered by weight, add LANGUAGE_NOT_SPECIFIED at the end.
528
    $fallback_candidates = array_keys(language_list());
529
    $fallback_candidates[] = LANGUAGE_NOT_SPECIFIED;
530
531

    // Let other modules hook in and add/change candidates.
532
    drupal_alter('language_fallback_candidates', $fallback_candidates);
533
534
535
536
  }

  return $fallback_candidates;
}
537
538
539
540

/**
 * @} End of "language_negotiation"
 */