1: <?php
2: /**
3: * This file contains the declaration of the interface ILanguageManager for localization support.
4: *
5: * @package System
6: *
7: * @author Oleg Schildt
8: */
9:
10: namespace SmartFactory\Interfaces;
11:
12: /**
13: * Interface for localization support.
14: *
15: * @author Oleg Schildt
16: */
17: interface ILanguageManager extends IInitable
18: {
19: /**
20: * Initializes the language manager with parameters.
21: *
22: * @param array $parameters
23: * The parameters may vary for each language manager.
24: *
25: * @return void
26: *
27: * @throws \Exception
28: * It might throw an exception in the case of any system errors.
29: *
30: * @author Oleg Schildt
31: */
32: public function init(array $parameters): void;
33:
34: /**
35: * This is function for loading the translations from the source JSON file.
36: *
37: * @return void
38: *
39: * @throws \Exception
40: * It might throw the following exceptions in the case of any errors:
41: *
42: * - if the translation file is invalid.
43: *
44: * @author Oleg Schildt
45: */
46: public function loadDictionary(): void;
47:
48: /**
49: * Adds additional translations to the dictionary.
50: *
51: * @param array $dictionary
52: * The array with additional translations.
53: *
54: * @return void
55: *
56: * @throws \Exception
57: * It might throw an exception in the case of any errors.
58: *
59: * @author Oleg Schildt
60: */
61: public function extendDictionary(array $dictionary): void;
62:
63: /**
64: * Adds additional localization files to the dictionary.
65: *
66: * @param string $localization_file
67: * The path of the additional localization file.
68: *
69: * @return void
70: *
71: * @throws \Exception
72: * It might throw an exception in the case of any errors.
73: *
74: * @author Oleg Schildt
75: */
76: public function addLocalizationFile(string $localization_file): void;
77:
78: /**
79: * This function should detect the current language based on cookies, browser languages etc.
80: *
81: * Some applications may consist of two parts - administration
82: * console and public site. A usual example is a CMS system.
83: *
84: * For example, you are using administration console in English
85: * and editing the public site for German and French.
86: * When you open the public site for preview in German or French,
87: * you want it to be open in the corresponding language, but
88: * the administration console should remain in English.
89: *
90: * With the help of $context, you are able to maintain different
91: * languages for different parts of your application.
92: * If you do not need the $context, just do not specify it.
93: *
94: * @return void
95: *
96: * @author Oleg Schildt
97: */
98: public function detectLanguage(): void;
99:
100: /**
101: * Sets the current context.
102: *
103: * Some applications may consist of two parts - administration
104: * console and public site. A usual example is a CMS system.
105: *
106: * For example, you are using administration console in English
107: * and editing the public site for German and French.
108: * When you open the public site for preview in German or French,
109: * you want it to be open in the corresponding language, but
110: * the administration console should remain in English.
111: *
112: * With the help of $context, you are able to maintain different
113: * languages for different parts of your application.
114: * If you do not need the $context, just do not specify it.
115: *
116: * @param string $context
117: * The name of the context.
118: *
119: * @return void
120: *
121: * @see LanguageManager::getContext()
122: *
123: * @author Oleg Schildt
124: */
125: public function setContext(string $context): void;
126:
127: /**
128: * Returns the current context.
129: *
130: * Some applications may consist of two parts - administration
131: * console and public site. A usual example is a CMS system.
132: *
133: * For example, you are using administration console in English
134: * and editing the public site for German and French.
135: * When you open the public site for preview in German or French,
136: * you want it to be open in the corresponding language, but
137: * the administration console should remain in English.
138: *
139: * With the help of $context, you are able to maintain different
140: * languages for different parts of your application.
141: * If you do not need the $context, just do not specify it.
142: *
143: * @return string
144: * Returns the current context.
145: *
146: * @author Oleg Schildt
147: */
148: public function getContext(): string;
149:
150: /**
151: * Returns the list of supported languages.
152: *
153: * @return array
154: * Returns the list of supported languages.
155: *
156: * @author Oleg Schildt
157: */
158: public function getSupportedLanguages(): array;
159:
160: /**
161: * Sets the current language.
162: *
163: * @param string $language
164: * The language ISO code to be set.
165: *
166: * @return void
167: *
168: * @see ILanguageManager::getCurrentLanguage()
169: *
170: * @author Oleg Schildt
171: */
172: public function setCurrentLanguage(string $language): void;
173:
174: /**
175: * Returns the current language.
176: *
177: * @return string
178: * Returns the current language ISO code.
179: *
180: * @see ILanguageManager::setCurrentLanguage()
181: *
182: * @author Oleg Schildt
183: */
184: public function getCurrentLanguage(): string;
185:
186: /**
187: * Returns the fallback language. If set and a translation
188: * is missing on a language, the translation on this language will be used.
189: *
190: * @return string
191: * Returns the fallback language.
192: *
193: * @author Oleg Schildt
194: */
195: public function getFallbackLanguage(): string;
196:
197: /**
198: * Provides the text translation for the text ID for the given language.
199: *
200: * @param string $text_id
201: * Text ID
202: *
203: * @param string $lng
204: * The language. If it is not specified,
205: * the default language is used.
206: *
207: * @param string $default_text
208: * The default text to be used if there is no translation.
209: *
210: * @return string
211: * Returns the translation text or the $default_text/$text_id if no translation
212: * is found.
213: *
214: * @author Oleg Schildt
215: */
216: public function text(string $text_id, string $lng = "", string $default_text = ""): string;
217:
218: /**
219: * Provides the text translation for the text ID for the given language if the translation exists.
220: * Otherwise, it returns the text ID and emits no warning.
221: *
222: * @param string $text_id
223: * Text ID
224: *
225: * @param string $lng
226: * The language. If it is not specified,
227: * the default language is used.
228: *
229: * @return string
230: * Returns the translation text or the $default_text/$text_id if no translation
231: * is found.
232: *
233: * @author Oleg Schildt
234: */
235: public function try_text(string $text_id, string $lng = ""): string;
236:
237: /**
238: * Checks whether the text translation for the text ID for the given language exists.
239: *
240: * @param string $text_id
241: * Text ID
242: *
243: * @param string $lng
244: * The language. If it is not specified,
245: * the default language is used.
246: *
247: * @return bool
248: * Returns true if the translation exists, otherwise false.
249: *
250: * @author Oleg Schildt
251: */
252: public function hasTranslation(string $text_id, string $lng = ""): bool;
253:
254: /**
255: * Provides the text translation for the language name by the code
256: * for the given language.
257: *
258: * @param string $code
259: * Language ISO code (lowercase, e.g. en, de, fr).
260: *
261: * @param string $lng
262: * The language. If it is not specified,
263: * the default language is used.
264: *
265: * @return string
266: * Returns the translation text for the language name or the $code if no translation
267: * is found.
268: *
269: * @see ILanguageManager::getLanguageCode()
270: * @see ILanguageManager::validateLanguageCode()
271: * @see ILanguageManager::getLanguageList()
272: * @see ILanguageManager::getCountryName()
273: *
274: * @author Oleg Schildt
275: */
276: public function getLanguageName(string $code, string $lng = ""): string;
277:
278: /**
279: * Tries to find the language code by the given name.
280: *
281: * @param string $lang_name
282: * The name of the language in any supported language.
283: *
284: * @return string
285: * Returns the language code if it could be found, otherwise an empty string.
286: *
287: * @see ILanguageManager::getLanguageName()
288: * @see ILanguageManager::validateLanguageCode()
289: * @see ILanguageManager::getLanguageList()
290: * @see ILanguageManager::getCountryCode()
291: *
292: * @author Oleg Schildt
293: */
294: public function getLanguageCode(string $lang_name): string;
295:
296: /**
297: * Checks whether the language code is valid (has translation).
298: *
299: * @param string $code
300: * Language ISO code (lowercase, e.g. en, de, fr).
301: *
302: * @param string $lng
303: * The language. If it is not specified,
304: * the default language is used.
305: *
306: * @return bool
307: * Returns true if the language code is valid (has translation), otherwise false.
308: *
309: * @see ILanguageManager::getLanguageName()
310: * @see ILanguageManager::getLanguageCode()
311: * @see ILanguageManager::getLanguageList()
312: * @see ILanguageManager::validateCountryCode()
313: *
314: * @author Oleg Schildt
315: */
316: public function validateLanguageCode(string $code, string $lng = ""): bool;
317:
318: /**
319: * Provides the list of languages for the given language in the form "code" => "translation".
320: *
321: * @param array &$language_list
322: * Target array where the language list should be loaded.
323: *
324: * @param string $lng
325: * The language. If it is not specified,
326: * the default language is used.
327: *
328: * @param array $display_first
329: * List of the language codes to be displayed first in the order, they appear in the list.
330: *
331: * @return bool
332: * Returns true if the language list is successfully retrieved, otherwise false.
333: *
334: * @see ILanguageManager::getLanguageName()
335: * @see ILanguageManager::getLanguageCode()
336: * @see ILanguageManager::validateLanguageCode()
337: * @see ILanguageManager::getCountryList()
338: *
339: * @author Oleg Schildt
340: */
341: public function getLanguageList(array &$language_list, string $lng = "", array $display_first = []): bool;
342:
343: /**
344: * Provides the text translation for the country name by the code
345: * for the given language.
346: *
347: * @param string $code
348: * Country ISO code (uppercase, e.g. US, DE, FR).
349: *
350: * @param string $lng
351: * The language. If it is not specified,
352: * the default language is used.
353: *
354: * @return string
355: * Returns the translation text for the country name or the $code if no translation
356: * is found.
357: *
358: * @see ILanguageManager::getCountryCode()
359: * @see ILanguageManager::validateCountryCode()
360: * @see ILanguageManager::getCountryList()
361: * @see ILanguageManager::getLanguageName()
362: *
363: * @author Oleg Schildt
364: */
365: public function getCountryName(string $code, string $lng = ""): string;
366:
367: /**
368: * Tries to find the country code by the given name.
369: *
370: * @param string $country_name
371: * The name of the country in any supported language.
372: *
373: * @return string
374: * Returns the country code if it could be found, otherwise an empty string.
375: *
376: * @see ILanguageManager::getCountryName()
377: * @see ILanguageManager::validateCountryCode()
378: * @see ILanguageManager::getCountryList()
379: * @see ILanguageManager::getLanguageCode()
380: *
381: * @author Oleg Schildt
382: */
383: public function getCountryCode(string $country_name): string;
384:
385: /**
386: * Checks whether the country code is valid (has translation).
387: *
388: * @param string $code
389: * Country ISO code (uppercase, e.g. US, DE, FR).
390: *
391: * @param string $lng
392: * The language. If it is not specified,
393: * the default language is used.
394: *
395: * @return bool
396: * Returns true if the country code is valid (has translation), otherwise false.
397: *
398: * @see ILanguageManager::getCountryName()
399: * @see ILanguageManager::getCountryCode()
400: * @see ILanguageManager::getCountryList()
401: * @see ILanguageManager::validateLanguageCode()
402: *
403: * @author Oleg Schildt
404: */
405: public function validateCountryCode(string $code, string $lng = ""): bool;
406:
407: /**
408: * Provides the list of countries for the given language in the form "code" => "translation".
409: *
410: * @param array &$country_list
411: * Target array where the country list should be loaded.
412: *
413: * @param string $lng
414: * The language. If it is not specified,
415: * the default language is used.
416: *
417: * @param array $display_first
418: * List of the country codes to be displayed first in the order, they appear in the list.
419: *
420: * @return bool
421: * Returns true if the country list is successfully retrieved, otherwise false.
422: *
423: * @see ILanguageManager::getCountryName()
424: * @see ILanguageManager::getCountryCode()
425: * @see ILanguageManager::validateCountryCode()
426: * @see ILanguageManager::getLanguageList()
427: *
428: * @author Oleg Schildt
429: */
430: public function getCountryList(array &$country_list, string $lng = "", array $display_first = []): bool;
431: } // ILanguageManager