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