locale.module

<?php
// $Id$

/**
 * @file
 *   Add language handling functionality and enables the translation of the
 *   user interface to languages other than English.
 *
 *   When enabled, multiple languages can be set up. The site interface
 *   can be displayed in different languages, as well as nodes can have languages
 *   assigned. The setup of languages and translations is completely web based.
 *   Gettext portable object files are supported.
 */

/**
 * Language written left to right. Possible value of $language->direction.
 */
define('LANGUAGE_LTR', 0);

/**
 * Language written right to left. Possible value of $language->direction.
 */
define('LANGUAGE_RTL', 1);


// ---------------------------------------------------------------------------------
// Hook implementations

/**
 * Implementation of hook_help().
 */
function locale_help($path, $arg) {
  switch ($path) {
    case 'admin/help#locale':
      $output = '<p>'. t('The locale module allows you to present your Drupal site in a language other than the default English. You can use it to set up a multi-lingual website or replace given <em>built-in</em> text with text which has been customized for your site. Whenever the locale module encounters text which needs to be displayed, it tries to translate it into the currently selected language. If a translation is not available, then the string is remembered, so you can look up untranslated strings easily.') .'</p>';
      $output .= '<p>'. t('The locale module provides two options for providing translations. The first is the integrated web interface, via which you can search for untranslated strings, and specify their translations. An easier and less time-consuming method is to import existing translations for your language. These translations are available as <em>GNU gettext Portable Object files</em> (<em>.po</em> files for short). Translations for many languages are available for download from the translation page.') .'</p>';
      $output .= '<p>'. t("If an existing translation does not meet your needs, the <em>.po</em> files are easily edited with special editing tools. The locale module's import feature allows you to add strings from such files into your site's database. The export functionality enables you to share your translations with others, generating Portable Object files from your site strings.") .'</p>';
      $output .= '<p>'. t('For more information please read the configuration and customization handbook <a href="@locale">Locale page</a>.', array('@locale' => 'http://drupal.org/handbook/modules/locale/')) .'</p>';
      return $output;

    case 'admin/settings/language':
      return t("<p>Drupal provides support for the translation of its interface text into different languages. This page provides an overview of the installed languages. You can add a language on the <a href=\"@add-language\">add language page</a>, or directly by <a href=\"@import\">importing a translation</a>. If multiple languages are enabled, registered users will be able to set their preferred language. The site default will be used for anonymous visitors and for users without their own settings.</p><p>Drupal interface translations may be added or extended by several courses: by <a href=\"@import\">importing</a> an existing translation, by <a href=\"@search\">translating everything</a> from scratch, or by a combination of these approaches.</p>", array("@search" => url("admin/build/translate/search"), "@import" => url("admin/build/translate/import"), "@add-language" => url("admin/settings/language/add")));
    case 'admin/settings/language/add':
      return '<p>'. t("You need to add all languages in which you would like to display the site interface. If you can't find the desired language in the quick-add dropdown, then you will need to provide the proper language code yourself. The language code may be used to negotiate with browsers and to present flags, etc., so it is important to pick a code that is standardised for the desired language. You can also add a language by <a href=\"@import\">importing a translation</a>.", array("@import" => url("admin/build/translate/import"))) .'</p>';
    case 'admin/settings/language/configure':
      return '<p>'. t('The language used to display a web page is determined with a negotiation algorithm. You can choose how this algorithm should work. By default, there is no negotiation and the default language is used. You can use path prefixes (like "de" and "it" for German and Italian content) with different fallback options, so you can have web addresses like /de/contact and /it/contact. Alternatively you can use custom domains like de.example.com and it.example.com. Customize path prefixes and set domain names on the <a href="@languages">language editing pages</a>.', array('@languages' => url('admin/settings/language'))) .'</p>';

    case 'admin/build/translate':
      return '<p>'. t("This page provides an overview of interface translation on the site. Drupal groups all translatable strings in so called 'text groups'. Text groups are useful, because you can focus your translation efforts on the groups of text you care most about.  For example, a translation team could choose not to fully translate the text group that includes all the long help texts on the administration pages. Similarly, text groups are useful to ensure that certain aspects of the site are always fully translated.") . '</p>';
    case 'admin/build/translate/import':
      return '<p>'. t("This page allows you to import a translation provided in the gettext Portable Object (.po) format. The easiest way to get your site translated is to obtain an existing Drupal translation and to import it. You can find existing translations on the <a href=\"@url\">Drupal translation page</a>. Note that importing a translation file might take a while.", array('@url' => 'http://drupal.org/project/translations')) .'</p>';
    case 'admin/build/translate/export':
      return '<p>'. t("This page allows you to export Drupal strings. The first option is to export a translation so it can be shared. The second option generates a translation template, which contains all Drupal strings, but without their translations. You can use this template to start a new translation using various software packages designed for this task.") .'</p>';
    case 'admin/build/translate/search':
      return '<p>'. t("It is often convenient to get the strings from your setup on the <a href=\"@export\">export page</a>, and use a desktop Gettext translation editor to edit the translations. On this page you can search in the translated and untranslated strings, and the default English texts provided by Drupal.", array("@export" => url("admin/build/translate/export"))) .'</p>';

    case 'admin/build/block/configure':
      if ($arg[4] == 'locale' && $arg[5] == 0) {
        return '<p>'. t("This block is only shown if you have <a href=\"@languages\">at least two languages enabled</a> and you have a <a href=\"@configuration\">language negotiation setting</a> different from 'none', so you have different web addresses for different language versions.", array('@languages' => url('admin/settings/language'), '@configuration' => url('admin/settings/language/configure'))) .'</p>';
      }
      break;
  }
}

/**
 * Implementation of hook_menu().
 *
 * Locale module only provides administrative menu items, so all
 * menu items are invoked through locale_inc_callback().
 */
function locale_menu() {
  // Manage languages
  $items['admin/settings/language'] = array(
    'title' => 'Languages',
    'description' => 'Configure languages for content and the user interface.',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('drupal_get_form', 'locale_languages_overview_form'),
    'access arguments' => array('administer languages'),
  );
  $items['admin/settings/language/overview'] = array(
    'title' => 'List',
    'weight' => 0,
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['admin/settings/language/add'] = array(
    'title' => 'Add language',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('locale_languages_add_screen'), // two forms concatenated
    'weight' => 5,
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/settings/language/configure'] = array(
    'title' => 'Configure',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('drupal_get_form', 'locale_languages_configure_form'),
    'weight' => 10,
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/settings/language/edit/%'] = array(
    'title' => 'Edit language',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('drupal_get_form', 'locale_languages_edit_form', 4),
    'type' => MENU_CALLBACK,
  );
  $items['admin/settings/language/delete/%'] = array(
    'title' => 'Confirm',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('drupal_get_form', 'locale_languages_delete_form', 4),
    'type' => MENU_CALLBACK,
  );

  // Translation functionality
  $items['admin/build/translate'] = array(
    'title' => 'Translate interface',
    'description' => 'Translate the built in interface as well as menu items and taxonomies.',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('locale_translate_overview_screen'), // not a form, just a table
    'access arguments' => array('translate interface'),
  );
  $items['admin/build/translate/overview'] = array(
    'title' => 'Overview',
    'weight' => 0,
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['admin/build/translate/search'] = array(
    'title' => 'Search',
    'weight' => 10,
    'type' => MENU_LOCAL_TASK,
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('locale_translate_seek_screen'), // search results and form concatenated
  );
  $items['admin/build/translate/import'] = array(
    'title' => 'Import',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('drupal_get_form', 'locale_translate_import_form'),
    'weight' => 20,
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/build/translate/export'] = array(
    'title' => 'Export',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('locale_translate_export_screen'), // possibly multiple forms concatenated
    'weight' => 30,
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/build/translate/edit/%'] = array(
    'title' => 'Edit string',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('drupal_get_form', 'locale_translate_edit_form', 4),
    'type' => MENU_CALLBACK,
  );
  $items['admin/build/translate/delete/%'] = array(
    'title' => 'Delete string',
    'page callback' => 'locale_inc_callback',
    'page arguments' => array('locale_translate_delete', 4),  // directly deletes, no confirmation
    'type' => MENU_CALLBACK,
  );

  return $items;
}

/**
 * Wrapper function to be able to set callbacks in locale.inc
 */
function locale_inc_callback() {
  $args = func_get_args();
  $function = array_shift($args);
  include_once './includes/locale.inc';
  return call_user_func_array($function, $args);
}

/**
 * Implementation of hook_perm().
 */
function locale_perm() {
  return array('administer languages', 'translate interface');
}

/**
 * Implementation of hook_locale().
 */
function locale_locale($op = 'groups') {
  switch ($op) {
    case 'groups':
      return array('default' => t('Built-in interface'));
  }
}

/**
 * Implementation of hook_user().
 */
function locale_user($type, $edit, &$user, $category = NULL) {
  global $language;

  // If we have more then one language and either creating a user on the
  // admin interface or edit the user, show the language selector.
  if (variable_get('language_count', 1) > 1 && ($type == 'register' && user_access('administer users') || $type == 'form' && $category == 'account' )) {
    $languages = language_list('enabled');
    $languages = $languages['1'];

    // If the user is being created, we set the user language to the page language.
    $user_preferred_language = $user ? user_preferred_language($user) : $language;

    $names = array();
    foreach ($languages as $langcode => $language) {
      $names[$langcode] = t($language->name) .' ('. $language->native .')';
    }
    $form['locale'] = array(
      '#type' => 'fieldset',
      '#title' => t('Language settings'),
      '#weight' => 1,
    );

    $form['locale']['language'] = array(
      '#type' => 'radios',
      '#title' => t('Language'),
      '#default_value' => $user_preferred_language->language,
      '#options' => $names,
      '#description' => t('Sets the default site interface and e-mail language for this account.'),
    );
    return $form;
  }
}

/**
 * Implementation of hook_form_alter(). Adds language fields to forms.
 */
function locale_form_alter(&$form, $form_state, $form_id) {
  switch ($form_id) {

    // Language field for paths
    case 'path_admin_edit':
      $form['language'] = array(
        '#type' => 'select',
        '#title' => t('Language'),
        '#options' => array('' => t('All languages')) + locale_language_list('name'),
        '#default_value' => $form['language']['#value'],
        '#weight' => -10,
        '#description' => t('Path aliases added for languages take precedence over path aliases added for all languages for the same Drupal path.'),
      );
      break;

    // Language setting for content types
    case 'node_type_form':
      if (isset($form['identity']['type'])) {
        $form['workflow']['language'] = array(
          '#type' => 'radios',
          '#title' => t('Multilingual support'),
          '#default_value' => variable_get('language_'. $form['#node_type']->type, 0),
          '#options' => array(t('Disabled'), t('Enabled')),
          '#description' => t('Enable multilingual support for this content type. If enabled, a language selection field will be added to the editing form, allowing you to select from one of the <a href="!languages">enabled languages</a>. If disabled, new posts are saved with the default language. Existing content will not be affected by changing this option.', array('!languages' => url('admin/settings/language'))),
        );
      }
      break;

    // Language field for nodes
    default:
      if (isset($form['#id']) && $form['#id'] == 'node-form') {
        if (isset($form['#node']->type) && variable_get('language_' . $form['#node']->type, 0)) {
          $form['language'] = array(
            '#type' => 'select',
            '#title' => t('Language'),
            '#default_value' => (isset($form['#node']->language) ? $form['#node']->language : ''),
            '#options' => array('' => t('Language neutral')) + locale_language_list('name'),
          );
        }
        // Node type without language selector: assign the default for new nodes
        elseif (!isset($form['#node']->nid)) {
          $default = language_default();
          $form['language'] = array(
            '#type' => 'value',
            '#value' => $default->language
          );
        }
      }
  }
}

/**
 * Implementation of hook_theme()
 */
function locale_theme() {
  return array(
    'locale_languages_overview_form' => array(
      'arguments' => array('form' => array()),
    ),
  );
}

// ---------------------------------------------------------------------------------
// Locale core functionality

/**
 * Provides interface translation services.
 *
 * This function is called from t() to translate a string if needed.
 *
 * @param $string
 *   A string to look up translation for. If omitted, all the
 *   cached strings will be returned in all languages already
 *   used on the page.
 * @param $langcode
 *   Language code to use for the lookup.
 */
function locale($string = NULL, $langcode = NULL) {
  global $language;
  static $locale_t;

  // Return all cached strings if no string was specified
  if (!isset($string)) {
    return $locale_t;
  }

  $langcode = isset($langcode) ? $langcode : $language->language;

  // Store database cached translations in a static var.
  if (!isset($locale_t[$langcode])) {
    $locale_t[$langcode] = array();
    // Disabling the usage of string caching allows a module to watch for
    // the exact list of strings used on a page. From a performance
    // perspective that is a really bad idea, so we have no user
    // interface for this. Be careful when turning this option off!
    if (variable_get('locale_cache_strings', 1) == 1) {
      if (!($cache = cache_get('locale:'. $langcode, 'cache'))) {
        locale_refresh_cache();
        $cache = cache_get('locale:'. $langcode, 'cache');
      }
      if ($cache) {
        $locale_t[$langcode] = $cache->data;
      }
    }
  }

  // We have the translation cached (if it is TRUE, then there is no
  // translation, so there is no point in checking the database)
  if (isset($locale_t[$langcode][$string])) {
    $string = ($locale_t[$langcode][$string] === TRUE ? $string : $locale_t[$langcode][$string]);
  }

  // We do not have this translation cached, so get it from the DB.
  else {
    $translation = db_fetch_object(db_query("SELECT s.lid, t.translation FROM {locales_source} s LEFT JOIN {locales_target} t ON s.lid = t.lid WHERE s.source = '%s' AND t.language = '%s' AND s.textgroup = 'default'", $string, $langcode));
    if ($translation) {
      // We have the source string at least.
      if ($translation->lid) {
        // Cache translation string or TRUE if no translation exists.
        $translation = (empty($translation->translation) ? TRUE : $translation->translation);
        $locale_t[$langcode][$string] = $translation;
      }
    }
    else {
      // We don't have the source string, cache this as untranslated.
      db_query("INSERT INTO {locales_source} (location, source, textgroup) VALUES ('%s', '%s', 'default')", request_uri(), $string);
      $locale_t[$langcode][$string] = TRUE;
      // Clear locale cache so this string can be added in a later request.
      cache_clear_all('locale:'. $langcode, 'cache');
    }
  }

  return $string;
}

/**
 * Refreshes database stored cache of translations.
 *
 * We only store short strings to improve performance and consume less memory.
 */
function locale_refresh_cache() {
  $languages = language_list('enabled');
  $languages = $languages['1'];

  foreach ($languages as $language) {
    $result = db_query("SELECT s.source, t.translation, t.language FROM {locales_source} s LEFT JOIN {locales_target} t ON s.lid = t.lid WHERE t.language = '%s' AND s.textgroup = 'default' AND LENGTH(s.source) < 75", $language->language);
    $t = array();
    while ($data = db_fetch_object($result)) {
      $t[$data->source] = (empty($data->translation) ? TRUE : $data->translation);
    }
    cache_set('locale:'. $language->language, $t);
  }
}

/**
 * Returns plural form index for a specific number.
 *
 * The index is computed from the formula of this language.
 *
 * @param $count
 *   Number to return plural for.
 * @param $langcode
 *   Optional language code to translate to a language other than
 *   what is used to display the page.
 */
function locale_get_plural($count, $langcode = NULL) {
  global $language;
  static $locale_formula, $plurals = array();

  $langcode = $langcode ? $langcode : $language->language;

  if (!isset($plurals[$langcode][$count])) {
    if (!isset($locale_formula)) {
      $language_list = language_list();
      $locale_formula[$langcode] = $language_list[$langcode]->formula;
    }
    if ($locale_formula[$langcode]) {
      $n = $count;
      $plurals[$langcode][$count] = @eval('return intval('. $locale_formula[$langcode] .');');
      return $plurals[$langcode][$count];
    }
    else {
      $plurals[$langcode][$count] = -1;
      return -1;
    }
  }
  return $plurals[$langcode][$count];
}


/**
 * Returns a language name
 */
function locale_language_name($lang) {
  static $list = NULL;
  if (!isset($list)) {
    $list = locale_language_list();
  }
  return ($lang && isset($list[$lang])) ? $list[$lang] : t('All');
}

/**
 * Returns array of language names
 *
 * @param $field
 *   'name' => names in current language, localized
 *   'native' => native names
 * @param $all
 *   Boolean to return all languages or only enabled ones
 */
function locale_language_list($field = 'name', $all = FALSE) {
  if ($all) {
    $languages = language_list();
  }
  else {
    $languages = language_list('enabled');
    $languages = $languages[1];
  }
  $list = array();
  foreach ($languages as $language) {
    $list[$language->language] = ($field == 'name') ? t($language->name) : $language->$field;
  }
  return $list;
}

/**
 * Imports translations when new modules or themes are installed or enabled.
 *
 * This function will either import translation for the component change
 * right away, or start a batch if more files need to be imported.
 *
 * @param $components
 *   An array of component (theme and/or module) names to import
 *   translations for.
 */
function locale_system_update($components) {
  include_once 'includes/locale.inc';
  if ($batch = locale_batch_by_component($components)) {
    batch_set($batch);
  }
}

/**
 * Finished callback of system page locale import batch.
 * Inform the user of translation files imported.
 */
function _locale_batch_system_finished($success, $results) {
  if ($success) {
    drupal_set_message(format_plural(count($results), 'One translation file imported for the newly installed modules.', '@count translation files imported for the newly installed modules.'));
  }
}

/**
 * Finished callback of language addition locale import batch.
 * Inform the user of translation files imported.
 */
function _locale_batch_language_finished($success, $results) {
  if ($success) {
    drupal_set_message(format_plural(count($results), 'One translation file imported for the enabled modules.', '@count translation files imported for the enabled modules.'));
  }
}

/**
 * Perform interface translation import as a batch step.
 *
 * @param $filepath
 *   Path to a file to import.
 * @param $results
 *   Contains a list of files imported.
 */
function _locale_batch_import($filepath, &$context) {
  include_once 'includes/locale.inc';
  // The filename is either {langcode}.po or {prefix}.{langcode}.po, so
  // we can extract the language code to use for the import from the end.
  if (preg_match('!(/|\.)([^\.]+)\.po$!', $filepath, $langcode)) {
    $file = (object) array('filename' => basename($filepath), 'filepath' => $filepath);
    _locale_import_read_po('db-store', $file, LOCALE_IMPORT_KEEP, $langcode[2]);
    $context['results'][] = $filepath;
  }
}

// ---------------------------------------------------------------------------------
// Language switcher block

/**
 * Implementation of hook_block().
 * Displays a language switcher. Translation links may be provided by other modules.
 */
function locale_block($op = 'list', $delta = 0) {
  if ($op == 'list') {
    $block[0]['info'] = t('Language switcher');
    return $block;
  }

  // Only show if we have at least two languages and language dependent
  // web addresses, so we can actually link to other language versions.
  elseif ($op == 'view' && variable_get('language_count', 1) > 1 && variable_get('language_negotiation', LANGUAGE_NEGOTIATION_NONE) != LANGUAGE_NEGOTIATION_NONE) {
    $languages = language_list('enabled');
    $links = array();
    foreach ($languages[1] as $language) {
      $links[$language->language] = array(
        'href'       => $_GET['q'],
        'title'      => $language->native,
        'language'   => $language,
        'attributes' => array('class' => 'language-link'),
      );
    }

    // Allow modules to provide translations for specific links.
    // A translation link may need to point to a different path or use
    // a translated link text before going through l(), which will just
    // handle the path aliases.
    drupal_alter('translation_link', $links, $_GET['q']);

    $block['subject'] = t('Languages');
    $block['content'] = theme('links', $links, array());
    return $block;
  }
}