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