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