Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2/**
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
17 *
18 * @file
19 */
20
21namespace MediaWiki\Language;
22
23use MediaWiki\Linker\LinkTarget;
24use MediaWiki\Page\PageReference;
25use MediaWiki\Title\Title;
26
27/**
28 * The shared interface for all language converters.
29 *
30 * @ingroup Language
31 * @internal
32 */
33interface ILanguageConverter {
34
35    /**
36     * Get all valid variants.
37     *
38     * @return string[] Contains all valid variants
39     */
40    public function getVariants();
41
42    /**
43     * In case some variant is not defined in the markup, we need
44     * to have some fallback. For example, in zh, normally people
45     * will define zh-hans and zh-hant, but less so for zh-sg or zh-hk.
46     *
47     * When zh-sg is preferred but not defined, we will pick zh-hans
48     * in this case. Right now this is only used by zh.
49     *
50     * @param string $variant The language code of the variant
51     * @return string|array The code of the fallback language or the
52     *   main code if there is no fallback
53     */
54    public function getVariantFallbacks( $variant );
55
56    /**
57     * Get the title produced by the conversion rule.
58     *
59     * @return string|false The converted title text
60     */
61    public function getConvRuleTitle();
62
63    /**
64     * Get preferred language variant.
65     *
66     * @return string The preferred language code
67     */
68    public function getPreferredVariant();
69
70    /**
71     * This function would not be affected by user's settings
72     *
73     * @return string The default variant code
74     */
75    public function getDefaultVariant();
76
77    /**
78     * Validate the variant and return an appropriate strict internal
79     * variant code if one exists. Compare to Language::hasVariant()
80     * which does a strict test.
81     *
82     * @param string|null $variant The variant to validate
83     * @return string|null Returns an equivalent valid variant code if possible,
84     *   null otherwise
85     */
86    public function validateVariant( $variant = null );
87
88    /**
89     * Get the variant specified in the URL
90     *
91     * @return string|null Variant if one found, null otherwise
92     */
93    public function getURLVariant();
94
95    /**
96     * Dictionary-based conversion.
97     * This function would not parse the conversion rules.
98     * If you want to parse rules, try to use convert() or
99     * convertTo().
100     *
101     * @param string $text The text to be converted
102     * @param string|false $toVariant The target language code
103     * @return string The converted text
104     */
105    public function autoConvert( $text, $toVariant = false );
106
107    /**
108     * Translate a string to a variant.
109     * Doesn't parse rules or do any of that other stuff, for that use
110     * convert() or convertTo().
111     *
112     * @param string $text Text to convert
113     * @param string $variant Variant language code
114     * @return string Translated text
115     */
116    public function translate( $text, $variant );
117
118    /**
119     * Call translate() to convert text to all valid variants.
120     *
121     * @param string $text The text to be converted
122     * @return array Variant => converted text
123     */
124    public function autoConvertToAllVariants( $text );
125
126    /**
127     * Automatically converts a LinkTarget or PageReference to a readable string in the
128     * preferred variant, separating the namespace and the main part of the title.
129     *
130     * @since 1.39
131     * @param LinkTarget|PageReference $title
132     * @return string[] Three elements: converted namespace text, converted namespace separator,
133     *   and the converted main part of the title
134     */
135    public function convertSplitTitle( $title );
136
137    /**
138     * Automatically convert a LinkTarget or PageReference to a readable string in the
139     * preferred variant.
140     *
141     * @param LinkTarget|PageReference $title
142     * @return string Converted title text
143     */
144    public function convertTitle( $title );
145
146    /**
147     * Get the namespace display name in the preferred variant.
148     *
149     * @param int $index Namespace id
150     * @param string|null $variant Variant code or null for preferred variant
151     * @return string Namespace name for display
152     */
153    public function convertNamespace( $index, $variant = null );
154
155    /**
156     * Convert text to different variants of a language. The automatic
157     * conversion is done in autoConvert(). Here we parse the text
158     * marked with -{}-, which specifies special conversions of the
159     * text that cannot be accomplished in autoConvert().
160     *
161     * Syntax of the markup:
162     * -{code1:text1;code2:text2;...}-  or
163     * -{flags|code1:text1;code2:text2;...}-  or
164     * -{text}- in which case no conversion should take place for text
165     *
166     * @warning Glossary state is maintained between calls. Never feed this
167     *   method input that hasn't properly been escaped as it may result in
168     *   an XSS in subsequent calls, even if those subsequent calls properly
169     *   escape things.
170     * @param string $text Text to be converted; already html escaped.
171     * @return string Converted text (html)
172     */
173    public function convert( $text );
174
175    /**
176     * Same as convert() except a extra parameter to custom variant.
177     *
178     * @param string $text Text to be converted; already html escaped
179     * @param-taint $text exec_html
180     * @param string $variant The target variant code
181     * @param bool $clearState Whether to clear the converter title before
182     *   conversion (defaults to true)
183     * @return string Converted text
184     * @return-taint escaped
185     */
186    public function convertTo( $text, $variant, bool $clearState = true );
187
188    /**
189     * If a language supports multiple variants, it is possible that
190     * non-existing link in one variant actually exists in another variant.
191     * This function tries to find it. See e.g., LanguageZh.php
192     * The input parameters may be modified upon return
193     *
194     * @param string &$link The name of the link
195     * @param Title &$nt The title object of the link
196     * @param bool $ignoreOtherCond To disable other conditions when
197     *   we need to transclude a template or update a category's link
198     */
199    public function findVariantLink( &$link, &$nt, $ignoreOtherCond = false );
200
201    /**
202     * Returns language specific hash options.
203     *
204     * @return string
205     */
206    public function getExtraHashOptions();
207
208    /**
209     * Guess if a text is written in a variant. This should be implemented in subclasses.
210     *
211     * @param string $text The text to be checked
212     * @param string $variant Language code of the variant to be checked for
213     * @return bool True if $text appears to be written in $variant, false if not
214     *
215     * @author Nikola Smolenski <smolensk@eunet.rs>
216     * @since 1.19
217     */
218    public function guessVariant( $text, $variant );
219
220    /**
221     * Enclose a string with the "no conversion" tag. This is used by
222     * various functions in the Parser.
223     *
224     * @param string $text Text to be tagged for no conversion
225     * @param bool $noParse Unused
226     * @return string The tagged text
227     */
228    public function markNoConversion( $text, $noParse = false );
229
230    /**
231     * Convert the sorting key for category links. This should make different
232     * keys that are variants of each other map to the same key.
233     *
234     * @param string $key
235     *
236     * @return string
237     */
238    public function convertCategoryKey( $key );
239
240    /**
241     * Refresh the cache of conversion tables when
242     * MediaWiki:Conversiontable* is updated.
243     *
244     * @param LinkTarget $linkTarget The LinkTarget of the page being updated
245     */
246    public function updateConversionTable( LinkTarget $linkTarget );
247
248    /**
249     * Check if this is a language with variants
250     *
251     * @since 1.35
252     *
253     * @return bool
254     */
255    public function hasVariants();
256
257    /**
258     * Strict check if the language has the specific variant.
259     *
260     * Compare to LanguageConverter::validateVariant() which does a more
261     * lenient check and attempts to coerce the given code to a valid one.
262     *
263     * @since 1.35
264     * @param string $variant
265     * @return bool
266     */
267    public function hasVariant( $variant );
268
269    /**
270     * Perform output conversion on a string, and encode for safe HTML output.
271     *
272     * @since 1.35
273     *
274     * @param string $text Text to be converted
275     * @return string string converted to be safely used in HTML
276     */
277    public function convertHtml( $text );
278}
279
280/** @deprecated class alias since 1.43 */
281class_alias( ILanguageConverter::class, 'ILanguageConverter' );