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 Field Language API 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:

function mymodule_language_types_info_alter(&$language_types) {
  unset($language_types[Language::TYPE_CONTENT]['fixed']);
}

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:

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;
}
?>
?><?php

For more information, see Language Negotiation API

File

drupal/core/includes/language.inc, line 17
Language Negotiation API.

Functions

Name Locationsort descending Description
language_types_initialize drupal/core/includes/language.inc Chooses a language based on language negotiation method settings.
language_types_info drupal/core/includes/language.inc Returns information about all defined language types.
language_types_get_configurable drupal/core/includes/language.inc Returns only the configurable language types.
language_types_disable drupal/core/includes/language.inc Disables the given language types.
language_types_set drupal/core/includes/language.inc Updates the language type configuration.
language_negotiation_method_get_first drupal/core/includes/language.inc Returns the ID of the language type's first language negotiation method.
language_negotiation_method_enabled drupal/core/includes/language.inc Checks whether a language negotiation method is enabled for a language type.
language_negotiation_get_switch_links drupal/core/includes/language.inc Returns the language switch links for the given language type.
language_negotiation_purge drupal/core/includes/language.inc Removes any language negotiation methods that are no longer defined.
language_negotiation_set drupal/core/includes/language.inc Saves a list of language negotiation methods for a language type.
language_negotiation_info drupal/core/includes/language.inc Returns all defined language negotiation methods.
language_negotiation_method_invoke drupal/core/includes/language.inc Invokes a language negotiation method and caches the results.
language_from_selected drupal/core/includes/language.inc Identifies language from configuration.
language_url_split_prefix drupal/core/includes/language.inc Splits the given path into prefix and actual path.
language_fallback_get_candidates drupal/core/includes/language.inc Returns the possible fallback languages ordered by language weight.
hook_language_types_info drupal/core/modules/system/language.api.php Define language types.
hook_language_types_info_alter drupal/core/modules/system/language.api.php Perform alterations on language types.
hook_language_negotiation_info drupal/core/modules/system/language.api.php Define language negotiation methods.
hook_language_negotiation_info_alter drupal/core/modules/system/language.api.php Perform alterations on language negotiation methods.