1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* Translation provider interface for multi-provider translation support.
7	*
8	* This Source Code Form is subject to the terms of the Mozilla Public License,
9	* v. 2.0. If a copy of the MPL was not distributed with this file, You can
10	* obtain one at https://mozilla.org/MPL/2.0/.
11	*
12	* @package   phpMyFAQ
13	* @author    Thorsten Rinne <thorsten@phpmyfaq.de>
14	* @copyright 2026 phpMyFAQ Team
15	* @license   http://www.mozilla.org/MPL/2.0/ Mozilla Public License Version 2.0
16	* @link      https://www.phpmyfaq.de
17	* @since     2026-01-17
18	*/
19
20	namespace phpMyFAQ\Translation;
21
22	use phpMyFAQ\Translation\Exception\TranslationException;
23
24	/**
25	* Interface TranslationProviderInterface
26	*
27	* Defines the contract for translation service providers (Google, DeepL, Azure, LibreTranslate).
28	*/
29	interface TranslationProviderInterface
30	{
31	/**
32	* Translate a single text string.
33	*
34	* @param string $text Text to translate
35	* @param string $sourceLang Source language code (ISO 639-1)
36	* @param string $targetLang Target language code (ISO 639-1)
37	* @param bool $preserveHtml Whether to preserve HTML tags in the text
38	* @return string Translated text
39	* @throws TranslationException
40	*/
41	public function translate(string $text, string $sourceLang, string $targetLang, bool $preserveHtml = false): string;
42
43	/**
44	* Translate multiple texts in a single batch request.
45	*
46	* @param array<string> $texts Array of texts to translate
47	* @param string $sourceLang Source language code (ISO 639-1)
48	* @param string $targetLang Target language code (ISO 639-1)
49	* @param bool $preserveHtml Whether to preserve HTML tags
50	* @return array<string> Array of translated texts
51	* @throws TranslationException
52	*/
53	public function translateBatch(
54	array $texts,
55	string $sourceLang,
56	string $targetLang,
57	bool $preserveHtml = false,
58	): array;
59
60	/**
61	* Check if this provider supports a language pair.
62	*
63	* @param string $sourceLang Source language code
64	* @param string $targetLang Target language code
65	* @return bool True if the language pair is supported
66	*/
67	public function supportsLanguagePair(string $sourceLang, string $targetLang): bool;
68
69	/**
70	* Get a list of supported language codes.
71	*
72	* @return array<string> Array of ISO 639-1 language codes
73	*/
74	public function getSupportedLanguages(): array;
75
76	/**
77	* Get the provider name.
78	*
79	* @return string Provider name (e.g., "Google Cloud Translation", "DeepL")
80	*/
81	public function getProviderName(): string;
82	}