language.api.php 8.31 KB
Newer Older
1 2 3 4
<?php

/**
 * @file
5
 * Hooks provided by the base system for language support.
6 7 8 9 10 11 12
 */

/**
 * @addtogroup hooks
 * @{
 */

13
/**
14
 * Perform alterations on language switcher links.
15
 *
16 17 18
 * A language switcher 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.
19 20 21
 *
 * @param $links
 *   Nested array of links keyed by language code.
22 23
 * @param $type
 *   The language type the links will switch.
24 25 26
 * @param $path
 *   The current path.
 */
27
function hook_language_switch_links_alter(array &$links, $type, $path) {
28
  $language_interface = language(LANGUAGE_TYPE_INTERFACE);
29

30 31
  if ($type == LANGUAGE_TYPE_CONTENT && isset($links[$language_interface->langcode])) {
    foreach ($links[$language_interface->langcode] as $link) {
32
      $link['attributes']['class'][] = 'active-language';
33 34 35 36
    }
  }
}

37
/**
38
 * Define language types.
39 40
 *
 * @return
41 42 43 44 45 46 47 48 49 50
 *   An associative array of language type definitions. The keys are the
 *   identifiers, which are also used as names for global variables representing
 *   the types in the bootstrap phase. The values are associative arrays that
 *   may contain the following elements:
 *   - name: The human-readable language type identifier.
 *   - description: A description of the language type.
 *   - fixed: A fixed array of language negotiation method identifiers to use to
 *     initialize this language. Defining this key makes the language type
 *     non-configurable, so it will always use the specified methods in the
 *     given priority order. Omit to make the language type configurable.
51
 *
52 53
 * @see hook_language_types_info_alter()
 * @ingroup language_negotiation
54 55 56 57 58 59 60
 */
function hook_language_types_info() {
  return array(
    'custom_language_type' => array(
      'name' => t('Custom language'),
      'description' => t('A custom language type.'),
    ),
61
    'fixed_custom_language_type' => array(
62
      'fixed' => array('custom_language_negotiation_method'),
63
    ),
64 65 66 67 68 69 70 71
  );
}

/**
 * Perform alterations on language types.
 *
 * @param $language_types
 *   Array of language type definitions.
72 73 74
 *
 * @see hook_language_types_info()
 * @ingroup language_negotiation
75 76 77 78 79 80 81 82
 */
function hook_language_types_info_alter(array &$language_types) {
  if (isset($language_types['custom_language_type'])) {
    $language_types['custom_language_type_custom']['description'] = t('A far better description.');
  }
}

/**
83
 * Define language negotiation methods.
84 85
 *
 * @return
86 87 88 89
 *   An associative array of language negotiation method definitions. The keys
 *   are method identifiers, and the values are associative arrays definining
 *   each method, with the following elements:
 *   - types: An array of allowed language types. If a language negotiation
90 91
 *     method does not specify which language types it should be used with, it
 *     will be available for all the configurable language types.
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
 *   - callbacks: An associative array of functions that will be called to
 *     perform various tasks. Possible elements are:
 *     - negotiation: (required) Name of the callback function that determines
 *       the language value.
 *     - language_switch: (optional) Name of the callback function that
 *       determines links for a language switcher block associated with this
 *       method. See language_switcher_url() for an example.
 *     - url_rewrite: (optional) Name of the callback function that provides URL
 *       rewriting, if needed by this method.
 *   - file: The file where callback functions are defined (this file will be
 *     included before the callbacks are invoked).
 *   - weight: The default weight of the method.
 *   - name: The translated human-readable name for the method.
 *   - description: A translated longer description of the method.
 *   - config: An internal path pointing to the method's configuration page.
 *   - cache: The value Drupal's page cache should be set to for the current
 *     method to be invoked.
 *
 * @see hook_language_negotiation_info_alter()
 * @ingroup language_negotiation
112 113 114
 */
function hook_language_negotiation_info() {
  return array(
115
    'custom_language_negotiation_method' => array(
116
      'callbacks' => array(
117 118 119
        'negotiation' => 'custom_negotiation_callback',
        'language_switch' => 'custom_language_switch_callback',
        'url_rewrite' => 'custom_url_rewrite_callback',
120 121 122 123
      ),
      'file' => drupal_get_path('module', 'custom') . '/custom.module',
      'weight' => -4,
      'types' => array('custom_language_type'),
124 125
      'name' => t('Custom language negotiation method'),
      'description' => t('This is a custom language negotiation method.'),
126
      'cache' => 0,
127 128 129 130 131
    ),
  );
}

/**
132
 * Perform alterations on language negotiation methods.
133
 *
134 135
 * @param $negotiation_info
 *   Array of language negotiation method definitions.
136 137 138
 *
 * @see hook_language_negotiation_info()
 * @ingroup language_negotiation
139
 */
140 141 142
function hook_language_negotiation_info_alter(array &$negotiation_info) {
  if (isset($negotiation_info['custom_language_method'])) {
    $negotiation_info['custom_language_method']['config'] = 'admin/config/regional/language/detection/custom-language-method';
143 144 145
  }
}

146 147 148 149 150 151 152 153 154
/**
 * Perform alterations on the language fallback candidates.
 *
 * @param $fallback_candidates
 *   An array of language codes whose order will determine the language fallback
 *   order.
 */
function hook_language_fallback_candidates_alter(array &$fallback_candidates) {
  $fallback_candidates = array_reverse($fallback_candidates);
155 156
}

157 158 159
/**
 * @} End of "addtogroup hooks".
 */
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203

/**
 * @defgroup transliteration Transliteration
 * @{
 * Transliterate from Unicode to US-ASCII
 *
 * Transliteration is the process of translating individual non-US-ASCII
 * characters into ASCII characters, which specifically does not transform
 * non-printable and punctuation characters in any way. This process will always
 * be both inexact and language-dependent. For instance, the character Ö (O with
 * an umlaut) is commonly transliterated as O, but in German text, the
 * convention would be to transliterate it as Oe or OE, depending on the context
 * (beginning of a capitalized word, or in an all-capital letter context).
 *
 * The Drupal default transliteration process transliterates text character by
 * character using a database of generic character transliterations and
 * language-specific overrides. Character context (such as all-capitals
 * vs. initial capital letter only) is not taken into account, and in
 * transliterations of capital letters that result in two or more letters, by
 * convention only the first is capitalized in the Drupal transliteration
 * result. So, the process has limitations; however, since the reason for
 * transliteration is typically to create machine names or file names, this
 * should not really be a problem. After transliteration, other transformation
 * or validation may be necessary, such as converting spaces to another
 * character, removing non-printable characters, lower-casing, etc.
 *
 * Here is a code snippet to transliterate some text:
 * @code
 * // Use the current default interface language.
 * $langcode = language(LANGUAGE_TYPE_INTERFACE)->langcode;
 * // Instantiate the transliteration class.
 * $trans = drupal_container()->get('transliteration');
 * // Use this to transliterate some text.
 * $transformed = $trans->transliterate($string, $langcode);
 * @endcode
 *
 * Drupal Core provides the generic transliteration character tables and
 * overrides for a few common languages; modules can implement
 * hook_transliteration_overrides_alter() to provide further language-specific
 * overrides. Modules can also completely override the transliteration classes
 * in \Drupal\Core\CoreBundle.
 */

/**
204
 * Provide language-specific overrides for transliteration.
205 206
 *
 * @param array $overrides
207
 *   Associative array of language-specific overrides whose keys are integer
208 209 210 211 212 213 214 215 216 217 218
 *   Unicode character codes, and whose values are the transliterations of those
 *   characters in the given language, to override default transliterations.
 * @param string $langcode
 *   The code for the language that is being transliterated.
 *
 * @ingroup hooks
 */
function hook_transliteration_overrides_alter(&$overrides, $langcode) {
  // Provide special overrides for German for a custom site.
  if ($langcode == 'de') {
    // The core-provided transliteration of Ä is Ae, but we want just A.
219
    $overrides[0xC4] = 'A';
220 221 222 223 224 225
  }
}

/**
 * @} End of "defgroup transliteration".
 */