language.inc 20 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
use Drupal\Core\Language\Language;

12
/**
13 14
 * No language negotiation. The default language is used.
 */
15
const LANGUAGE_NEGOTIATION_SELECTED = 'language-selected';
16

17 18 19 20 21
/**
 * The language is determined using the current interface language.
 */
const LANGUAGE_NEGOTIATION_INTERFACE = 'language-interface';

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
 * @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) {
56
 *   unset($language_types[Language::TYPE_CONTENT]['fixed']);
57 58 59
 * }
 * @endcode
 *
60 61 62 63
 * The locked configuration property prevents one language type from being
 * switched from customized to not customized, and vice versa.
 * @see language_types_set()
 *
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
 * 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') {
104
 *     return language_default()->id;
105 106 107 108 109 110 111 112 113 114 115 116
 *   }
 *   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.
117 118
 *
 * @param $type
119
 *   The language type key to find the language for.
120
 *
121 122 123
 * @param $request
 *   The HttpReqeust object representing the current request.
 *
124 125 126
 * @return
 *   The negotiated language object.
 */
127
function language_types_initialize($type, $request = NULL) {
128 129
  // Execute the language negotiation methods in the order they were set up and
  // return the first valid language found.
130 131
  $negotiation = variable_get("language_negotiation_$type", array());

132
  foreach ($negotiation as $method_id => $method) {
133 134 135 136
    // Skip negotiation methods not appropriate for this type.
    if (isset($method['types']) && !in_array($type, $method['types'])) {
      continue;
    }
137
    $language = language_negotiation_method_invoke($method_id, $method, $request);
138
    if ($language) {
139 140
      // Remember the method ID used to detect the language.
      $language->method_id = $method_id;
141 142 143 144 145 146
      return $language;
    }
  }

  // If no other language was found use the default one.
  $language = language_default();
147
  $language->method_id = LANGUAGE_NEGOTIATION_SELECTED;
148 149 150 151 152
  return $language;
}

/**
 * Returns information about all defined language types.
153 154
 *
 * @return
155 156 157 158
 *   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().
159 160 161 162 163
 */
function language_types_info() {
  $language_types = &drupal_static(__FUNCTION__);

  if (!isset($language_types)) {
164
    $language_types = \Drupal::moduleHandler()->invokeAll('language_types_info');
165 166 167 168 169 170 171 172
    // Let other modules alter the list of language types.
    drupal_alter('language_types_info', $language_types);
  }

  return $language_types;
}

/**
173
 * Returns only the configurable language types.
174 175
 *
 * A language type maybe configurable or fixed. A fixed language type is a type
176 177
 * whose language negotiation methods are module-defined and not altered through
 * the user interface.
178 179 180 181
 *
 * @return
 *   An array of language type names.
 */
182
function language_types_get_configurable() {
183
  $configurable = \Drupal::config('system.language.types')->get('configurable');
184
  return $configurable ? $configurable : array();
185 186 187
}

/**
188
 * Disables the given language types.
189 190 191 192 193
 *
 * @param $types
 *   An array of language types.
 */
function language_types_disable($types) {
194
  $configurable = language_types_get_configurable();
195
  \Drupal::config('system.language.types')->set('configurable', array_diff($configurable, $types))->save();
196 197
}

198 199
/**
 * Updates the language type configuration.
200 201 202
 *
 * @param array $configurable_language_types
 *   An array of configurable language types.
203
 */
204
function language_types_set(array $configurable_language_types) {
205
  // Ensure that we are getting the defined language negotiation information. An
206 207 208
  // invocation of \Drupal\Core\Extension\ModuleHandler::install() or
  // \Drupal\Core\Extension\ModuleHandler::uninstall() could invalidate the
  // cached information.
209 210 211
  drupal_static_reset('language_types_info');
  drupal_static_reset('language_negotiation_info');

212
  $language_types = array();
213
  $negotiation_info = language_negotiation_info();
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
  $language_types_info = language_types_info();

  foreach ($language_types_info as $type => $info) {
    $configurable = in_array($type, $configurable_language_types);

    // Check whether the language type is unlocked. Only the status of unlocked
    // language types can be toggled between configurable and non-configurable.
    // The default language negotiation settings, if available, are stored in
    // $info['fixed'].
    if (empty($info['locked'])) {
      // If we have a non-locked non-configurable language type without default
      // language negotiation settings, we use the values negotiated for the
      // interface language which should always be available.
      if (!$configurable && !empty($info['fixed'])) {
        $method_weights = array(LANGUAGE_NEGOTIATION_INTERFACE);
        $method_weights = array_flip($method_weights);
        language_negotiation_set($type, $method_weights);
231 232 233
      }
    }
    else {
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
      // Locked language types with default settings are always considered
      // non-configurable. In turn if default settings are missing, the language
      // type is always considered configurable.
      $configurable = empty($info['fixed']);

      // If the language is non-configurable we need to store its language
      // negotiation settings.
      if (!$configurable) {
        $method_weights = array();
        foreach ($info['fixed'] as $weight => $method_id) {
          if (isset($negotiation_info[$method_id])) {
            $method_weights[$method_id] = $weight;
          }
        }
        language_negotiation_set($type, $method_weights);
      }
250
    }
251 252

    $language_types[$type] = $configurable;
253 254
  }

255
  // Store the language type configuration.
256
  $config = \Drupal::config('system.language.types');
257 258
  $config->set('configurable', array_keys(array_filter($language_types)))->save();
  $config->set('all', array_keys($language_types))->save();
259

260 261 262
  // Ensure that subsequent calls of language_types_get_configurable() return
  // the updated language type information.
  drupal_static_reset('language_types_get_configurable');
263 264
}

265
/**
266
 * Returns the ID of the language type's first language negotiation method.
267 268
 *
 * @param $type
269
 *   The language type.
270 271 272 273
 *
 * @return
 *   The identifier of the first language negotiation method for the given
 *   language type, or the default method if none exists.
274
 */
275
function language_negotiation_method_get_first($type) {
276
  $negotiation = variable_get("language_negotiation_$type", array());
277
  return empty($negotiation) ? LANGUAGE_NEGOTIATION_SELECTED : key($negotiation);
278 279 280
}

/**
281
 * Checks whether a language negotiation method is enabled for a language type.
282
 *
283 284 285 286 287
 * @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.
288 289
 *
 * @return
290 291
 *   TRUE if the method is enabled for at least one of the given language
 *   types, or FALSE otherwise.
292
 */
293 294 295 296 297 298
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])) {
299 300 301 302 303 304 305 306
      return TRUE;
    }
  }

  return FALSE;
}

/**
307
 * Returns the language switch links for the given language type.
308 309
 *
 * @param $type
310
 *   The language type.
311 312 313 314 315 316 317 318 319 320
 * @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());

321 322 323 324
  foreach ($negotiation as $method_id => $method) {
    if (isset($method['callbacks']['language_switch'])) {
      if (isset($method['file'])) {
        require_once DRUPAL_ROOT . '/' . $method['file'];
325
      }
326

327
      $callback = $method['callbacks']['language_switch'];
328 329 330 331 332
      $result = $callback($type, $path);

      if (!empty($result)) {
        // Allow modules to provide translations for specific links.
        drupal_alter('language_switch_links', $result, $type, $path);
333
        $links = (object) array('links' => $result, 'method_id' => $method_id);
334
        break;
335
      }
336 337 338 339 340 341
    }
  }

  return $links;
}

342
/**
343
 * Removes any language negotiation methods that are no longer defined.
344 345 346
 */
function language_negotiation_purge() {
  // Ensure that we are getting the defined language negotiation information. An
347 348 349
  // invocation of \Drupal\Core\Extension\ModuleHandler::install() or
  // \Drupal\Core\Extension\ModuleHandler::uninstall() could invalidate the
  // cached information.
350 351 352
  drupal_static_reset('language_negotiation_info');
  drupal_static_reset('language_types_info');

353
  $negotiation_info = language_negotiation_info();
354 355
  foreach (language_types_info() as $type => $type_info) {
    $weight = 0;
356 357 358 359
    $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++;
360 361
      }
    }
362
    language_negotiation_set($type, $method_weights);
363 364
  }
}
365 366

/**
367
 * Saves a list of language negotiation methods for a language type.
368 369
 *
 * @param $type
370 371
 *   The language type.
 * @param $method_weights
372
 *   An array of language negotiation method weights keyed by method ID.
373
 */
374
function language_negotiation_set($type, $method_weights) {
375
  // Save only the necessary fields.
376
  $method_fields = array('callbacks', 'file', 'cache');
377 378

  $negotiation = array();
379
  $negotiation_info = language_negotiation_info();
380
  $default_types = language_types_get_configurable();
381

382 383 384 385 386 387 388 389 390
  // 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);
391
      // Check whether the method is defined and has the right type.
392
      if (isset($types[$type])) {
393 394 395 396
        $method_data = array();
        foreach ($method_fields as $field) {
          if (isset($method[$field])) {
            $method_data[$field] = $method[$field];
397 398
          }
        }
399
        $negotiation[$method_id] = $method_data;
400 401
      }
    }
402
  }
403

404 405 406 407
  variable_set("language_negotiation_$type", $negotiation);
}

/**
408
 * Returns all defined language negotiation methods.
409 410
 *
 * @return
411
 *   An array of language negotiation methods.
412 413
 */
function language_negotiation_info() {
414
  $negotiation_info = &drupal_static(__FUNCTION__);
415

416 417
  if (!isset($negotiation_info)) {
    // Collect all the module-defined language negotiation methods.
418
    $negotiation_info = \Drupal::moduleHandler()->invokeAll('language_negotiation_info');
419 420 421
    $languages = language_list();
    $selected_language = $languages[language_from_selected($languages)];
    $description = 'Language based on a selected language. ';
422
    $description .= ($selected_language->id == language_default()->id) ? "(Site's default language (@language_name))" : '(@language_name)';
423
    // Add the default language negotiation method.
424 425 426 427 428 429 430 431
    $negotiation_info[LANGUAGE_NEGOTIATION_SELECTED] = array(
      'callbacks' => array(
        'negotiation' => 'language_from_selected',
      ),
      'weight' => 12,
      'name' => t('Selected language'),
      'description' => t($description, array('@language_name' => $selected_language->name)),
      'config' => 'admin/config/regional/language/detection/selected',
432 433
    );

434 435
     // Let other modules alter the list of language negotiation methods.
     drupal_alter('language_negotiation_info', $negotiation_info);
436
  }
437

438
  return $negotiation_info;
439 440 441
}

/**
442
 * Invokes a language negotiation method and caches the results.
443
 *
444
 * @param $method_id
445
 *   The language negotiation method's identifier.
446
 * @param $method
447 448 449
 *   (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().
450
 *
451 452 453
 * @param $request
 *   (optional) The HttpRequest object representing the current request.
 *
454
 * @return
455
 *   A language object representing the language chosen by the method.
456
 */
457
function language_negotiation_method_invoke($method_id, $method = NULL, $request = NULL) {
458
  $results = &drupal_static(__FUNCTION__);
459

460
  if (!isset($results[$method_id])) {
461 462
    global $user;

463
    $languages = language_list();
464

465 466 467
    if (!isset($method)) {
      $negotiation_info = language_negotiation_info();
      $method = $negotiation_info[$method_id];
468 469
    }

470 471
    if (isset($method['file'])) {
      require_once DRUPAL_ROOT . '/' . $method['file'];
472
    }
473 474
    // If the language negotiation method has no cache preference or this is
    // satisfied we can execute the callback.
475
    $cache = !isset($method['cache']) || $user->isAuthenticated() || $method['cache'] == variable_get('cache', 0);
476
    $callback = isset($method['callbacks']['negotiation']) ? $method['callbacks']['negotiation'] : FALSE;
477
    $langcode = $cache && function_exists($callback) ? $callback($languages, $request) : FALSE;
478
    $results[$method_id] = isset($languages[$langcode]) ? $languages[$langcode] : FALSE;
479
  }
480

481 482 483 484
  // 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.
485
  return !empty($results[$method_id]) ? clone($results[$method_id]) : $results[$method_id];
486
}
487

488 489 490 491 492 493 494 495 496 497
 /**
  * Identifies language from configuration.
  *
  * @param $languages
  *   An array of valid language objects.
  *
  * @return
  *   A valid language code on success, FALSE otherwise.
  */
function language_from_selected($languages) {
498
  $langcode = (string) \Drupal::config('language.negotiation')->get('selected_langcode');
499 500
  // Replace the site's default langcode by its real value.
  if ($langcode == 'site_default') {
501
    $langcode = language_default()->id;
502
  }
503
  return isset($languages[$langcode]) ? $langcode : language_default()->id;
504
}
505

506
/**
507
 * Splits the given path into prefix and actual path.
508
 *
509 510
 * Parse the given path and return the language object identified by the prefix
 * and the actual path.
511 512 513 514 515 516 517 518 519 520 521 522 523
 *
 * @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) {
524
  $args = empty($path) ? array() : explode('/', $path);
525 526 527
  $prefix = array_shift($args);

  // Search prefix within enabled languages.
528
  $prefixes = language_negotiation_url_prefixes();
529
  foreach ($languages as $language) {
530
    if (isset($prefixes[$language->id]) && $prefixes[$language->id] == $prefix) {
531 532 533 534 535 536 537
      // Rebuild $path with the language removed.
      return array($language, implode('/', $args));
    }
  }

  return array(FALSE, $path);
}
538 539

/**
540
 * Returns the possible fallback languages ordered by language weight.
541 542
 *
 * @param
543
 *   (optional) The language type. Defaults to Language::TYPE_CONTENT.
544 545 546 547
 *
 * @return
 *   An array of language codes.
 */
548
function language_fallback_get_candidates($type = Language::TYPE_CONTENT) {
549 550 551
  $fallback_candidates = &drupal_static(__FUNCTION__);

  if (!isset($fallback_candidates)) {
552
    // Get languages ordered by weight, add Language::LANGCODE_NOT_SPECIFIED at the end.
553
    $fallback_candidates = array_keys(language_list());
554
    $fallback_candidates[] = Language::LANGCODE_NOT_SPECIFIED;
555 556

    // Let other modules hook in and add/change candidates.
557
    drupal_alter('language_fallback_candidates', $fallback_candidates);
558 559 560 561
  }

  return $fallback_candidates;
}
562 563 564 565

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