"Fossies" - the Fresh Open Source Software Archive

Member "drupal-8.9.10/core/lib/Drupal/Core/Language/language.api.php" (26 Nov 2020, 11840 Bytes) of package /linux/www/drupal-8.9.10.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) PHP source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

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