language.api.php 8.98 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(\Drupal\Core\Language\Language::TYPE_INTERFACE);
29

30
  if ($type == \Drupal\Core\Language\Language::TYPE_CONTENT && isset($links[$language_interface->langcode])) {
31
    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

/**
 * @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
180 181 182 183 184 185 186 187
 * result. Also, only Unicode characters of 4 bytes or less can be
 * transliterated in the base system; language-specific overrides can be made
 * for longer Unicode characters. 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.
188 189 190 191
 *
 * Here is a code snippet to transliterate some text:
 * @code
 * // Use the current default interface language.
192
 * $langcode = language(\Drupal\Core\Language\Language::TYPE_INTERFACE)->langcode;
193 194 195 196 197 198 199 200 201
 * // 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
202 203
 * overrides (including providing transliteration for Unicode characters that
 * are longer than 4 bytes). Modules can also completely override the
204
 * transliteration classes in \Drupal\Core\CoreServiceProvider.
205 206 207
 */

/**
208
 * Provide language-specific overrides for transliteration.
209
 *
210 211 212 213 214 215
 * If the overrides you want to provide are standard for your language, consider
 * providing a patch for the Drupal Core transliteration system instead of using
 * this hook. This hook can be used temporarily until Drupal Core's
 * transliteration tables are fixed, or for sites that want to use a
 * non-standard transliteration system.
 *
216
 * @param array $overrides
217
 *   Associative array of language-specific overrides whose keys are integer
218 219 220 221 222 223 224 225 226 227 228
 *   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.
229
    $overrides[0xC4] = 'A';
230 231 232 233 234 235
  }
}

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