language.api.php 9.35 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 15 16 17 18 19 20 21 22 23 24 25 26
/**
 * Allows modules to act after language initialization has been performed.
 *
 * This is primarily needed to provide translation for configuration variables
 * in the proper bootstrap phase. Variables are user-defined strings and
 * therefore should not be translated via t(), since the source string can
 * change without notice and any previous translation would be lost. Moreover,
 * since variables can be used in the bootstrap phase, we need a bootstrap hook
 * to provide a translation early enough to avoid misalignments between code
 * using the original values and code using the translated values. However
 * modules implementing hook_boot() should be aware that language initialization
 * did not happen yet and thus they cannot rely on translated variables.
 */
function hook_language_init() {
27
  global $conf;
28

29
  switch (language(LANGUAGE_TYPE_INTERFACE)->langcode) {
30
    case 'it':
31
      $conf['system.site']['name'] = 'Il mio sito Drupal';
32 33 34
      break;

    case 'fr':
35
      $conf['system.site']['name'] = 'Mon site Drupal';
36 37 38 39
      break;
  }
}

40
/**
41
 * Perform alterations on language switcher links.
42
 *
43 44 45
 * 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.
46 47 48
 *
 * @param $links
 *   Nested array of links keyed by language code.
49 50
 * @param $type
 *   The language type the links will switch.
51 52 53
 * @param $path
 *   The current path.
 */
54
function hook_language_switch_links_alter(array &$links, $type, $path) {
55
  $language_interface = language(LANGUAGE_TYPE_INTERFACE);
56

57 58
  if ($type == LANGUAGE_TYPE_CONTENT && isset($links[$language_interface->langcode])) {
    foreach ($links[$language_interface->langcode] as $link) {
59
      $link['attributes']['class'][] = 'active-language';
60 61 62 63
    }
  }
}

64
/**
65
 * Define language types.
66 67
 *
 * @return
68 69 70 71 72 73 74 75 76 77
 *   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.
78
 *
79 80
 * @see hook_language_types_info_alter()
 * @ingroup language_negotiation
81 82 83 84 85 86 87
 */
function hook_language_types_info() {
  return array(
    'custom_language_type' => array(
      'name' => t('Custom language'),
      'description' => t('A custom language type.'),
    ),
88
    'fixed_custom_language_type' => array(
89
      'fixed' => array('custom_language_negotiation_method'),
90
    ),
91 92 93 94 95 96 97 98
  );
}

/**
 * Perform alterations on language types.
 *
 * @param $language_types
 *   Array of language type definitions.
99 100 101
 *
 * @see hook_language_types_info()
 * @ingroup language_negotiation
102 103 104 105 106 107 108 109
 */
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.');
  }
}

/**
110
 * Define language negotiation methods.
111 112
 *
 * @return
113 114 115 116
 *   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
117 118
 *     method does not specify which language types it should be used with, it
 *     will be available for all the configurable language types.
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
 *   - 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
139 140 141
 */
function hook_language_negotiation_info() {
  return array(
142
    'custom_language_negotiation_method' => array(
143
      'callbacks' => array(
144 145 146
        'negotiation' => 'custom_negotiation_callback',
        'language_switch' => 'custom_language_switch_callback',
        'url_rewrite' => 'custom_url_rewrite_callback',
147 148 149 150
      ),
      'file' => drupal_get_path('module', 'custom') . '/custom.module',
      'weight' => -4,
      'types' => array('custom_language_type'),
151 152
      'name' => t('Custom language negotiation method'),
      'description' => t('This is a custom language negotiation method.'),
153
      'cache' => 0,
154 155 156 157 158
    ),
  );
}

/**
159
 * Perform alterations on language negotiation methods.
160
 *
161 162
 * @param $negotiation_info
 *   Array of language negotiation method definitions.
163 164 165
 *
 * @see hook_language_negotiation_info()
 * @ingroup language_negotiation
166
 */
167 168 169
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';
170 171 172
  }
}

173 174 175 176 177 178 179 180 181
/**
 * 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);
182 183
}

184 185 186
/**
 * @} End of "addtogroup hooks".
 */
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230

/**
 * @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.
 */

/**
231
 * Provide language-specific overrides for transliteration.
232 233
 *
 * @param array $overrides
234
 *   Associative array of language-specific overrides whose keys are integer
235 236 237 238 239 240 241 242 243 244 245
 *   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.
246
    $overrides[0xC4] = 'A';
247 248 249 250 251 252
  }
}

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