1	<?php
2
3	namespace Dynart\Micro;
4
5	/**
6	* Handles static text translations
7	*
8	* You can set the current locale, load the translation for the current locale and get text
9	* for the current locale with the help of this class.
10	*
11	* Related configuration values:
12	* * app.root_path - used for the `~` symbol in the translations' folder path
13	* * translation.all - the all known translation locales seperated with commas, for example: `hu, en`
14	* * translation.default - if no locale was set this will be the default, for example: `en`
15	*
16	* @see Config
17	*/
18	interface TranslationInterface {
19	/**
20	* Adds a folder path for a namespace
21	*/
22	public function add(string $namespace, string $folder): void;
23
24	/**
25	* Returns with all the known locales
26	*/
27	public function allLocales(): array;
28
29	/**
30	* Does the application has multi locales?
31	*/
32	public function hasMultiLocales(): bool;
33
34	/**
35	* Returns with the current locale
36	*/
37	public function locale(): string;
38
39	/**
40	* Sets the current locale
41	*/
42	public function setLocale(string $locale): void;
43
44	/**
45	* Returns with the text by namespace and text id for the current locale
46	*
47	* You have to have multi locale config within your config.ini.php, for example:
48	*
49	* <pre>
50	* translation.all = en, hu
51	* translation.default = en
52	* </pre>
53	*
54	* then you have to add at least one namespace with a folder path for example in your App::init() method:
55	*
56	* <pre>
57	* class App extends AbstractApp {
58	*   // ...
59	*   public function init() {
60	*     $translation = $this->get(Translation::class);
61	*     $translation->addFolder('test', '~/folder/within/the/app/root/folder');
62	*   }
63	*   // ...
64	* }
65	* </pre>
66	*
67	* In the given folder you have to have the files `en.ini` and `hu.ini`. Both of the files have to have the
68	* text IDs and the translations. The `en.ini` could look like:
69	*
70	* <pre>
71	* welcome = "Hello {name}!"
72	* </pre>
73	*
74	* and then you can use it in your code:
75	*
76	* <pre>
77	* echo $translation->get('test:welcome', ['name' => 'Joe']);
78	* </pre>
79	*
80	* or in your view with the `tr` helper function:
81	*
82	* <pre>
83	* &lt;?= tr('test:welcome', ['name' => 'Joe']); ?&gt;
84	* </pre>
85	*
86	* the result will be with 'en' current locale:
87	*
88	* <pre>
89	* Hello Joe!
90	* </pre>
91	*
92	* If the translation doesn't exist, the result will be the `$id` between # symbols:
93	*
94	* <pre>
95	* #test:welcome#
96	* </pre>
97	*/
98	public function get(string $id, array $params = []): string;
99	}