annotate core/lib/Drupal/Core/Language/language.api.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /**
Chris@0 4 * @file
Chris@0 5 * Hooks provided by the base system for language support.
Chris@0 6 */
Chris@0 7
Chris@0 8 use Drupal\Core\Language\LanguageInterface;
Chris@0 9
Chris@0 10 /**
Chris@0 11 * @defgroup i18n Internationalization
Chris@0 12 * @{
Chris@0 13 * Internationalization and translation
Chris@0 14 *
Chris@0 15 * The principle of internationalization is that it should be possible to make a
Chris@0 16 * Drupal site in any language (or a multi-lingual site), where only content in
Chris@0 17 * the desired language is displayed for any particular page request. In order
Chris@0 18 * to make this happen, developers of modules, themes, and installation profiles
Chris@0 19 * need to make sure that all of the displayable content and user interface (UI)
Chris@0 20 * text that their project deals with is internationalized properly, so that it
Chris@0 21 * can be translated using the standard Drupal translation mechanisms.
Chris@0 22 *
Chris@0 23 * @section internationalization Internationalization
Chris@0 24 * Different @link info_types types of information in Drupal @endlink have
Chris@0 25 * different methods for internationalization, and different portions of the
Chris@0 26 * UI also have different methods for internationalization. Here is a list of
Chris@0 27 * the different mechanisms for internationalization, and some notes:
Chris@0 28 * - UI text is always put into code and related files in English.
Chris@0 29 * - Any time UI text is displayed using PHP code, it should be passed through
Chris@0 30 * either the global t() function or a t() method on the class. If it
Chris@0 31 * involves plurals, it should be passed through either the global
Chris@0 32 * \Drupal\Core\StringTranslation\PluralTranslatableMarkup::createFromTranslatedString()
Chris@0 33 * or a formatPlural() method on the class. Use
Chris@0 34 * \Drupal\Core\StringTranslation\StringTranslationTrait to get these methods
Chris@0 35 * into a class.
Chris@0 36 * - Dates displayed in the UI should be passed through the 'date' service
Chris@0 37 * class's format() method. Again see the Services topic; the method to
Chris@0 38 * call is \Drupal\Core\Datetime\Date::format().
Chris@0 39 * - Some YML files contain UI text that is automatically translatable:
Chris@0 40 * - *.routing.yml files: route titles. This also applies to
Chris@0 41 * *.links.task.yml, *.links.action.yml, and *.links.contextual.yml files.
Chris@0 42 * - *.info.yml files: module names and descriptions.
Chris@0 43 * - For configuration, make sure any configuration that is displayable to
Chris@0 44 * users is marked as translatable in the configuration schema. Configuration
Chris@0 45 * types label, text, and date_format are translatable; string is
Chris@0 46 * non-translatable text. See the @link config_api Config API topic @endlink
Chris@0 47 * for more information.
Chris@0 48 * - For annotation, make sure that any text that is displayable in the UI
Chris@0 49 * is wrapped in \@Translation(). See the
Chris@0 50 * @link plugin_translatable Plugin translatables topic @endlink for more
Chris@0 51 * information.
Chris@0 52 * - Content entities are translatable if they have
Chris@0 53 * @code
Chris@0 54 * translatable = TRUE,
Chris@0 55 * @endcode
Chris@0 56 * in their annotation. The use of entities to store user-editable content to
Chris@0 57 * be displayed in the site is highly recommended over creating your own
Chris@0 58 * method for storing, retrieving, displaying, and internationalizing content.
Chris@0 59 * - For Twig templates, use 't' or 'trans' filters to indicate translatable
Chris@0 60 * text. See https://www.drupal.org/node/2133321 for more information.
Chris@0 61 * - In JavaScript code, use the Drupal.t() and Drupal.formatPlural() functions
Chris@0 62 * (defined in core/misc/drupal.js) to translate UI text.
Chris@0 63 * - If you are using a custom module, theme, etc. that is not hosted on
Chris@0 64 * Drupal.org, see
Chris@0 65 * @link interface_translation_properties Interface translation properties topic @endlink
Chris@0 66 * for information on how to make sure your UI text is translatable.
Chris@0 67 *
Chris@0 68 * @section translation Translation
Chris@0 69 * Once your data and user interface are internationalized, the following Core
Chris@0 70 * modules are used to translate it into different languages (machine names of
Chris@0 71 * modules in parentheses):
Chris@0 72 * - Language (language): Define which languages are active on the site.
Chris@0 73 * - Interface Translation (locale): Translate UI text.
Chris@0 74 * - Content Translation (content_translation): Translate content entities.
Chris@0 75 * - Configuration Translation (config_translation): Translate configuration.
Chris@0 76 *
Chris@0 77 * The Interface Translation module deserves special mention, because besides
Chris@0 78 * providing a UI for translating UI text, it also imports community
Chris@0 79 * translations from the
Chris@0 80 * @link https://localize.drupal.org Drupal translation server. @endlink If
Chris@0 81 * UI text and provided configuration in Drupal Core and contributed modules,
Chris@0 82 * themes, and installation profiles is properly internationalized (as described
Chris@0 83 * above), the text is automatically added to the translation server for
Chris@0 84 * community members to translate, via *.po files that are generated by
Chris@0 85 * scanning the project files.
Chris@0 86 *
Chris@0 87 * @section context Translation string sharing and context
Chris@0 88 * By default, translated strings are only translated once, no matter where
Chris@0 89 * they are being used. For instance, there are many forms with Save
Chris@0 90 * buttons on them, and they all would have t('Save') in their code. The
Chris@0 91 * translation system will only store this string once in the translation
Chris@0 92 * database, so that if the translation is updated, all forms using that text
Chris@0 93 * will get the updated translation.
Chris@0 94 *
Chris@0 95 * Because the source of translation strings is English, and some words in
Chris@0 96 * English have multiple meanings or uses, this centralized, shared translation
Chris@0 97 * string storage can sometimes lead to ambiguous translations that are not
Chris@0 98 * correct for every place the string is used. As an example, the English word
Chris@0 99 * "May", in a string by itself, could be part of a list of full month names or
Chris@0 100 * part of a list of 3-letter abbreviated month names. So, in languages where
Chris@0 101 * the month name for May is longer than 3 letters, you'd need to translate May
Chris@0 102 * differently depending on how it's being used. To address this problem, the
Chris@0 103 * translation system includes the concept of the "context" of a translated
Chris@0 104 * string, which can be used to disambiguate text for translators, and obtain
Chris@0 105 * the correct translation for each usage of the string.
Chris@0 106 *
Chris@0 107 * Here are some examples of how to provide translation context with strings, so
Chris@0 108 * that this information can be included in *.po files, displayed on the
Chris@0 109 * localization server for translators, and used to obtain the correct
Chris@0 110 * translation in the user interface:
Chris@0 111 * @code
Chris@0 112 * // PHP code
Chris@18 113 * t('May', [], ['context' => 'Long month name']);
Chris@0 114 * \Drupal::translation()->formatPlural($count, '1 something',
Chris@18 115 * '@count somethings', [], ['context' => 'My context']);
Chris@0 116 *
Chris@0 117 * // JavaScript code
Chris@0 118 * Drupal.t('May', {}, {'context': 'Long month name'});
Chris@0 119 * Drupal.formatPlural(count, '1 something', '@count somethings', {},
Chris@0 120 * {'context': 'My context'});
Chris@0 121 *
Chris@0 122 * // *.links.yml file
Chris@0 123 * title: 'May'
Chris@0 124 * title_context: 'Long month name'
Chris@0 125 *
Chris@0 126 * // *.routing.yml file
Chris@0 127 * my.route.name:
Chris@0 128 * pattern: '/something'
Chris@0 129 * defaults:
Chris@0 130 * _title: 'May'
Chris@0 131 * _title_context: 'Long month name'
Chris@0 132 *
Chris@0 133 * // Config schema to say that a certain piece of configuration should be
Chris@0 134 * // translatable using the Config Translation API. Note that the schema label
Chris@0 135 * // is also translatable, but it cannot have context.
Chris@0 136 * date_format:
Chris@0 137 * type: string
Chris@0 138 * label: 'PHP date format'
Chris@0 139 * translatable: true
Chris@0 140 * translation context: 'PHP date format'
Chris@0 141 *
Chris@0 142 * // Twig template
Chris@0 143 * {% trans with {'context': 'Long month name'} %}
Chris@0 144 * May
Chris@0 145 * {% endtrans %}
Chris@0 146 * @endcode
Chris@0 147 *
Chris@0 148 * @see transliteration
Chris@0 149 * @see t()
Chris@0 150 * @}
Chris@0 151 */
Chris@0 152
Chris@0 153 /**
Chris@0 154 * @addtogroup hooks
Chris@0 155 * @{
Chris@0 156 */
Chris@0 157
Chris@0 158 /**
Chris@0 159 * Perform alterations on language switcher links.
Chris@0 160 *
Chris@0 161 * A language switcher link may need to point to a different path or use a
Chris@0 162 * translated link text before going through the link generator, which will
Chris@0 163 * just handle the path aliases.
Chris@0 164 *
Chris@0 165 * @param array $links
Chris@0 166 * Nested array of links keyed by language code.
Chris@0 167 * @param string $type
Chris@0 168 * The language type the links will switch.
Chris@0 169 * @param \Drupal\Core\Url $url
Chris@0 170 * The URL the switch links will be relative to.
Chris@0 171 */
Chris@0 172 function hook_language_switch_links_alter(array &$links, $type, \Drupal\Core\Url $url) {
Chris@0 173 $language_interface = \Drupal::languageManager()->getCurrentLanguage();
Chris@0 174
Chris@0 175 if ($type == LanguageInterface::TYPE_CONTENT && isset($links[$language_interface->getId()])) {
Chris@0 176 foreach ($links[$language_interface->getId()] as $link) {
Chris@0 177 $link['attributes']['class'][] = 'active-language';
Chris@0 178 }
Chris@0 179 }
Chris@0 180 }
Chris@0 181
Chris@0 182 /**
Chris@0 183 * @} End of "addtogroup hooks".
Chris@0 184 */
Chris@0 185
Chris@0 186 /**
Chris@0 187 * @defgroup transliteration Transliteration
Chris@0 188 * @{
Chris@0 189 * Transliterate from Unicode to US-ASCII
Chris@0 190 *
Chris@0 191 * Transliteration is the process of translating individual non-US-ASCII
Chris@0 192 * characters into ASCII characters, which specifically does not transform
Chris@0 193 * non-printable and punctuation characters in any way. This process will always
Chris@0 194 * be both inexact and language-dependent. For instance, the character Ö (O with
Chris@0 195 * an umlaut) is commonly transliterated as O, but in German text, the
Chris@0 196 * convention would be to transliterate it as Oe or OE, depending on the context
Chris@0 197 * (beginning of a capitalized word, or in an all-capital letter context).
Chris@0 198 *
Chris@0 199 * The Drupal default transliteration process transliterates text character by
Chris@0 200 * character using a database of generic character transliterations and
Chris@0 201 * language-specific overrides. Character context (such as all-capitals
Chris@0 202 * vs. initial capital letter only) is not taken into account, and in
Chris@0 203 * transliterations of capital letters that result in two or more letters, by
Chris@0 204 * convention only the first is capitalized in the Drupal transliteration
Chris@0 205 * result. Also, only Unicode characters of 4 bytes or less can be
Chris@0 206 * transliterated in the base system; language-specific overrides can be made
Chris@0 207 * for longer Unicode characters. So, the process has limitations; however,
Chris@0 208 * since the reason for transliteration is typically to create machine names or
Chris@0 209 * file names, this should not really be a problem. After transliteration,
Chris@0 210 * other transformation or validation may be necessary, such as converting
Chris@0 211 * spaces to another character, removing non-printable characters,
Chris@0 212 * lower-casing, etc.
Chris@0 213 *
Chris@0 214 * Here is a code snippet to transliterate some text:
Chris@0 215 * @code
Chris@0 216 * // Use the current default interface language.
Chris@0 217 * $langcode = \Drupal::languageManager()->getCurrentLanguage()->getId();
Chris@0 218 * // Instantiate the transliteration class.
Chris@0 219 * $trans = \Drupal::transliteration();
Chris@0 220 * // Use this to transliterate some text.
Chris@0 221 * $transformed = $trans->transliterate($string, $langcode);
Chris@0 222 * @endcode
Chris@0 223 *
Chris@0 224 * Drupal Core provides the generic transliteration character tables and
Chris@0 225 * overrides for a few common languages; modules can implement
Chris@0 226 * hook_transliteration_overrides_alter() to provide further language-specific
Chris@0 227 * overrides (including providing transliteration for Unicode characters that
Chris@0 228 * are longer than 4 bytes). Modules can also completely override the
Chris@0 229 * transliteration classes in \Drupal\Core\CoreServiceProvider.
Chris@0 230 */
Chris@0 231
Chris@0 232 /**
Chris@0 233 * Provide language-specific overrides for transliteration.
Chris@0 234 *
Chris@0 235 * If the overrides you want to provide are standard for your language, consider
Chris@0 236 * providing a patch for the Drupal Core transliteration system instead of using
Chris@0 237 * this hook. This hook can be used temporarily until Drupal Core's
Chris@0 238 * transliteration tables are fixed, or for sites that want to use a
Chris@0 239 * non-standard transliteration system.
Chris@0 240 *
Chris@0 241 * @param array $overrides
Chris@0 242 * Associative array of language-specific overrides whose keys are integer
Chris@0 243 * Unicode character codes, and whose values are the transliterations of those
Chris@0 244 * characters in the given language, to override default transliterations.
Chris@0 245 * @param string $langcode
Chris@0 246 * The code for the language that is being transliterated.
Chris@0 247 *
Chris@0 248 * @ingroup hooks
Chris@0 249 */
Chris@0 250 function hook_transliteration_overrides_alter(&$overrides, $langcode) {
Chris@0 251 // Provide special overrides for German for a custom site.
Chris@0 252 if ($langcode == 'de') {
Chris@0 253 // The core-provided transliteration of Ä is Ae, but we want just A.
Chris@0 254 $overrides[0xC4] = 'A';
Chris@0 255 }
Chris@0 256 }
Chris@0 257
Chris@0 258 /**
Chris@0 259 * @} End of "defgroup transliteration".
Chris@0 260 */