sureforms / inc / compatibility / multilingual / providers / provider.php

provider.php in SureForms – Contact Form Builder, AI Forms, Payment Form, Survey & Quiz 2.12.8, at inc/compatibility/multilingual/providers/provider.php

177 lines 6.2 KB

Raw Download Zip

1	<?php
2	/**
3	* Multilingual Provider Interface.
4	*
5	* Defines the contract that every multilingual plugin adapter (WPML, Polylang, Null)
6	* must implement so the rest of SureForms can stay agnostic of the underlying plugin.
7	*
8	* @package sureforms.
9	* @since 2.11.0
10	*/
11
12	namespace SRFM\Inc\Compatibility\Multilingual\Providers;
13
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit; // Exit if accessed directly.
16	}
17
18	/**
19	* Provider.
20	*
21	* Common surface area exposed by every multilingual provider adapter.
22	*
23	* @since 2.11.0
24	*/
25	interface Provider {
26	/**
27	* Whether the underlying multilingual plugin is active and usable.
28	*
29	* @since 2.11.0
30	* @return bool True when the provider can perform translations, false otherwise.
31	*/
32	public function is_active(): bool;
33
34	/**
35	* Current visitor language code.
36	*
37	* @since 2.11.0
38	* @return string Language code (e.g. 'en', 'de'). Empty string when not active.
39	*/
40	public function current_language(): string;
41
42	/**
43	* Site default language code.
44	*
45	* @since 2.11.0
46	* @return string Language code (e.g. 'en'). Empty string when not active.
47	*/
48	public function default_language(): string;
49
50	/**
51	* Register a translatable string with the multilingual plugin's String Translation registry.
52	*
53	* @param string $name Unique string identifier within the domain.
54	* @param string $value Original string value to register.
55	* @param string $domain Translation domain. Defaults to the sureforms text domain.
56	* @since 2.11.0
57	* @return void
58	*/
59	public function register_string( string $name, string $value, string $domain = 'sureforms' ): void;
60
61	/**
62	* Translate a previously registered string.
63	*
64	* @param string $value Original string value (used as fallback).
65	* @param string $name Unique string identifier within the domain.
66	* @param string $domain Translation domain. Defaults to the sureforms text domain.
67	* @param string\|null $language Optional target language code. When null, uses the current language.
68	* @since 2.11.0
69	* @return string Translated string, or the original value when no translation is found.
70	*/
71	public function translate( string $value, string $name, string $domain = 'sureforms', ?string $language = null ): string;
72
73	/**
74	* Switch the active language context.
75	*
76	* Pushes the new language onto an internal stack so {@see restore_language()} can revert it.
77	*
78	* @param string $language Target language code to switch to.
79	* @since 2.11.0
80	* @return void
81	*/
82	public function switch_language( string $language ): void;
83
84	/**
85	* Restore the previous language context after {@see switch_language()}.
86	*
87	* @since 2.11.0
88	* @return void
89	*/
90	public function restore_language(): void;
91
92	/**
93	* Render a language switcher widget as HTML.
94	*
95	* Used by templates that don't include the theme's footer (e.g., the
96	* SureForms instant-form template) so visitors can still change languages
97	* without depending on theme integration.
98	*
99	* Returns an empty string when no provider is active or when the provider
100	* can't produce a switcher (e.g., only one language configured).
101	*
102	* @since 2.11.0
103	* @return string Rendered switcher HTML.
104	*/
105	public function render_language_switcher(): string;
106
107	/**
108	* Whether the provider supports translation "string packages" — groups of
109	* strings bound to a single object (e.g. a form) that surface together in the
110	* multilingual plugin's Translation Editor, instead of as flat, global strings.
111	*
112	* @since 2.11.0
113	* @return bool True when package registration/translation is available.
114	*/
115	public function supports_packages(): bool;
116
117	/**
118	* Begin (re)registering a string package. Call before registering its strings
119	* so strings no longer present can be pruned by {@see finish_package()}.
120	*
121	* @param array<string,string> $package Package descriptor: kind, name, title, edit_link.
122	* @since 2.11.0
123	* @return void
124	*/
125	public function start_package( array $package ): void;
126
127	/**
128	* Finish registering a string package, removing any strings that were not
129	* re-registered since {@see start_package()} (e.g. fields deleted from a form).
130	*
131	* @param array<string,string> $package Package descriptor.
132	* @since 2.11.0
133	* @return void
134	*/
135	public function finish_package( array $package ): void;
136
137	/**
138	* Register a single string within a package.
139	*
140	* @param array<string,string> $package Package descriptor.
141	* @param string $name Stable string identifier within the package.
142	* @param string $value Original string value.
143	* @param string $title Human-readable label shown in the Translation Editor.
144	* @param string $type Editor field type: LINE, AREA or VISUAL.
145	* @since 2.11.0
146	* @return void
147	*/
148	public function register_package_string( array $package, string $name, string $value, string $title = '', string $type = 'LINE' ): void;
149
150	/**
151	* Translate a single package string for the current language.
152	*
153	* @param array<string,string> $package Package descriptor.
154	* @param string $name Stable string identifier within the package.
155	* @param string $value Original value (fallback when untranslated).
156	* @since 2.11.0
157	* @return string Translated value, or the original when no translation exists.
158	*/
159	public function translate_package_string( array $package, string $name, string $value ): string;
160
161	/*
162	* NOTE: delete_package( array $package ): void is deliberately NOT declared here.
163	*
164	* This interface is a public extension point — Multilingual_Manager::resolve_provider()
165	* accepts any object via the `srfm_multilingual_provider` filter (@since 2.11.0) and
166	* instanceof-checks it. Adding a bodyless method to a shipped interface is a
167	* fatal-error BC break: a third-party provider written against 2.11.0-2.12.2 would
168	* fail at class-declaration time on update, producing a white screen rather than a
169	* degraded feature. Guarding the call site does not help, because the fatal happens
170	* when the implementor's class is declared, not when the method is called.
171	*
172	* Both first-party providers implement delete_package(), and String_Collector
173	* feature-detects it before calling. If it is ever promoted into this contract, that
174	* must be a major release with a migration note for custom providers.
175	*/
176	}
177