polylang / include / api.php

api.php in Polylang 3.2.6, at include/api.php

448 lines 13.0 KB

Raw Download Zip

1	<?php
2	/**
3	* @package Polylang
4	*/
5
6	/**
7	* Template tag: displays the language switcher.
8	* The function does nothing if used outside the frontend.
9	*
10	* @api
11	* @since 0.5
12	*
13	* @param array $args {
14	* Optional array of arguments.
15	*
16	* @type int $dropdown The list is displayed as dropdown if set to 1, defaults to 0.
17	* @type int $echo Echoes the list if set to 1, defaults to 1.
18	* @type int $hide_if_empty Hides languages with no posts ( or pages ) if set to 1, defaults to 1.
19	* @type int $show_flags Displays flags if set to 1, defaults to 0.
20	* @type int $show_names Shows language names if set to 1, defaults to 1.
21	* @type string $display_names_as Whether to display the language name or its slug, valid options are 'slug' and 'name', defaults to name.
22	* @type int $force_home Will always link to the homepage in the translated language if set to 1, defaults to 0.
23	* @type int $hide_if_no_translation Hides the link if there is no translation if set to 1, defaults to 0.
24	* @type int $hide_current Hides the current language if set to 1, defaults to 0.
25	* @type int $post_id Returns links to the translations of the post defined by post_id if set, defaults to not set.
26	* @type int $raw Return a raw array instead of html markup if set to 1, defaults to 0.
27	* @type string $item_spacing Whether to preserve or discard whitespace between list items, valid options are 'preserve' and 'discard', defaults to 'preserve'.
28	* }
29	* @return string\|array Either the html markup of the switcher or the raw elements to build a custom language switcher.
30	*/
31	function pll_the_languages( $args = array() ) {
32	$switcher = new PLL_Switcher();
33	return $switcher->the_languages( PLL()->links, $args );
34	}
35
36	/**
37	* Returns the current language on frontend.
38	* Returns the language set in admin language filter on backend ( false if set to all languages ).
39	*
40	* @api
41	* @since 0.8.1
42	*
43	* @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'. Pass OBJECT constant to get the language object.
44	* @return string\|PLL_Language\|false The requested field for the current language.
45	*/
46	function pll_current_language( $field = 'slug' ) {
47	if ( OBJECT === $field ) {
48	return PLL()->curlang;
49	}
50	return isset( PLL()->curlang->$field ) ? PLL()->curlang->$field : false;
51	}
52
53	/**
54	* Returns the default language.
55	*
56	* @api
57	* @since 1.0
58	*
59	* @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'. Pass OBJECT constant to get the language object.
60	* @return string\|PLL_Language\|false The requested field for the default language.
61	*/
62	function pll_default_language( $field = 'slug' ) {
63	if ( isset( PLL()->options['default_lang'] ) ) {
64	$lang = PLL()->model->get_language( PLL()->options['default_lang'] );
65	if ( $lang ) {
66	if ( OBJECT === $field ) {
67	return $lang;
68	}
69	return isset( $lang->$field ) ? $lang->$field : false;
70	}
71	}
72	return false;
73	}
74
75	/**
76	* Among the post and its translations, returns the id of the post which is in the language represented by $lang.
77	*
78	* @api
79	* @since 0.5
80	*
81	* @param int $post_id Post id.
82	* @param string $lang Optional language code, defaults to the current language.
83	* @return int\|false\|null Post id of the translation if it exists, false otherwise, null if the current language is not defined yet.
84	*/
85	function pll_get_post( $post_id, $lang = '' ) {
86	return ( $lang = $lang ? $lang : pll_current_language() ) ? PLL()->model->post->get( $post_id, $lang ) : null;
87	}
88
89	/**
90	* Among the term and its translations, returns the id of the term which is in the language represented by $lang.
91	*
92	* @api
93	* @since 0.5
94	*
95	* @param int $term_id Term id.
96	* @param string $lang Optional language code, defaults to the current language.
97	* @return int\|false\|null Term id of the translation if it exists, false otherwise, null if the current language is not defined yet.
98	*/
99	function pll_get_term( $term_id, $lang = '' ) {
100	return ( $lang = $lang ? $lang : pll_current_language() ) ? PLL()->model->term->get( $term_id, $lang ) : null;
101	}
102
103	/**
104	* Returns the home url in a language.
105	*
106	* @api
107	* @since 0.8
108	*
109	* @param string $lang Optional language code, defaults to the current language.
110	* @return string
111	*/
112	function pll_home_url( $lang = '' ) {
113	if ( empty( $lang ) ) {
114	$lang = pll_current_language();
115	}
116
117	return empty( $lang ) ? home_url( '/' ) : PLL()->links->get_home_url( $lang );
118	}
119
120	/**
121	* Registers a string for translation in the "strings translation" panel.
122	*
123	* @api
124	* @since 0.6
125	*
126	* @param string $name A unique name for the string.
127	* @param string $string The string to register.
128	* @param string $context Optional, the group in which the string is registered, defaults to 'polylang'.
129	* @param bool $multiline Optional, true if the string table should display a multiline textarea,
130	* false if should display a single line input, defaults to false.
131	* @return void
132	*/
133	function pll_register_string( $name, $string, $context = 'Polylang', $multiline = false ) {
134	if ( PLL() instanceof PLL_Admin_Base ) {
135	PLL_Admin_Strings::register_string( $name, $string, $context, $multiline );
136	}
137	}
138
139	/**
140	* Translates a string ( previously registered with pll_register_string ).
141	*
142	* @api
143	* @since 0.6
144	*
145	* @param string $string The string to translate.
146	* @return string The string translated in the current language.
147	*/
148	function pll__( $string ) {
149	if ( ! is_scalar( $string ) \|\| '' === $string ) {
150	return $string;
151	}
152
153	return __( $string, 'pll_string' ); // PHPCS:ignore WordPress.WP.I18n
154	}
155
156	/**
157	* Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
158	*
159	* @api
160	* @since 2.1
161	*
162	* @param string $string The string to translate.
163	* @return string The string translated in the current language.
164	*/
165	function pll_esc_html__( $string ) {
166	return esc_html( pll__( $string ) );
167	}
168
169	/**
170	* Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
171	*
172	* @api
173	* @since 2.1
174	*
175	* @param string $string The string to translate.
176	* @return string The string translated in the current language.
177	*/
178	function pll_esc_attr__( $string ) {
179	return esc_attr( pll__( $string ) );
180	}
181
182	/**
183	* Echoes a translated string ( previously registered with pll_register_string )
184	* It is an equivalent of _e() and is not escaped.
185	*
186	* @api
187	* @since 0.6
188	*
189	* @param string $string The string to translate.
190	* @return void
191	*/
192	function pll_e( $string ) {
193	echo pll__( $string ); // phpcs:ignore
194	}
195
196	/**
197	* Echoes a translated string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output.
198	*
199	* @api
200	* @since 2.1
201	*
202	* @param string $string The string to translate.
203	* @return void
204	*/
205	function pll_esc_html_e( $string ) {
206	echo pll_esc_html__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
207	}
208
209	/**
210	* Echoes a translated a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML attributes.
211	*
212	* @api
213	* @since 2.1
214	*
215	* @param string $string The string to translate.
216	* @return void
217	*/
218	function pll_esc_attr_e( $string ) {
219	echo pll_esc_attr__( $string ); // phpcs:ignore WordPress.Security.EscapeOutput
220	}
221
222	/**
223	* Translates a string ( previously registered with pll_register_string ).
224	*
225	* @api
226	* @since 1.5.4
227	*
228	* @param string $string The string to translate.
229	* @param string $lang Language code.
230	* @return string The string translated in the requested language.
231	*/
232	function pll_translate_string( $string, $lang ) {
233	if ( PLL() instanceof PLL_Frontend && pll_current_language() == $lang ) {
234	return pll__( $string );
235	}
236
237	if ( ! is_scalar( $string ) \|\| '' === $string ) {
238	return $string;
239	}
240
241	static $cache; // Cache object to avoid loading the same translations object several times.
242
243	if ( empty( $cache ) ) {
244	$cache = new PLL_Cache();
245	}
246
247	if ( false === $mo = $cache->get( $lang ) ) {
248	$mo = new PLL_MO();
249	$mo->import_from_db( PLL()->model->get_language( $lang ) );
250	$cache->set( $lang, $mo );
251	}
252
253	return $mo->translate( $string );
254	}
255
256	/**
257	* Returns true if Polylang manages languages and translations for this post type.
258	*
259	* @api
260	* @since 1.0.1
261	*
262	* @param string $post_type Post type name.
263	* @return bool
264	*/
265	function pll_is_translated_post_type( $post_type ) {
266	return PLL()->model->is_translated_post_type( $post_type );
267	}
268
269	/**
270	* Returns true if Polylang manages languages and translations for this taxonomy.
271	*
272	* @api
273	* @since 1.0.1
274	*
275	* @param string $tax Taxonomy name.
276	* @return bool
277	*/
278	function pll_is_translated_taxonomy( $tax ) {
279	return PLL()->model->is_translated_taxonomy( $tax );
280	}
281
282	/**
283	* Returns the list of available languages.
284	*
285	* @api
286	* @since 1.5
287	*
288	* @param array $args {
289	* Optional array of arguments.
290	*
291	* @type bool $hide_empty Hides languages with no posts if set to true ( defaults to false ).
292	* @type string $fields Return only that field if set ( @see PLL_Language for a list of fields ), defaults to 'slug'.
293	* }
294	* @return string[]
295	*/
296	function pll_languages_list( $args = array() ) {
297	$args = wp_parse_args( $args, array( 'fields' => 'slug' ) );
298	return PLL()->model->get_languages_list( $args );
299	}
300
301	/**
302	* Sets the post language.
303	*
304	* @api
305	* @since 1.5
306	*
307	* @param int $id Post id.
308	* @param string $lang Language code.
309	* @return void
310	*/
311	function pll_set_post_language( $id, $lang ) {
312	PLL()->model->post->set_language( $id, $lang );
313	}
314
315	/**
316	* Sets the term language.
317	*
318	* @api
319	* @since 1.5
320	*
321	* @param int $id Term id.
322	* @param string $lang Language code.
323	* @return void
324	*/
325	function pll_set_term_language( $id, $lang ) {
326	PLL()->model->term->set_language( $id, $lang );
327	}
328
329	/**
330	* Save posts translations.
331	*
332	* @api
333	* @since 1.5
334	*
335	* @param int[] $arr An associative array of translations with language code as key and post id as value.
336	* @return void
337	*/
338	function pll_save_post_translations( $arr ) {
339	PLL()->model->post->save_translations( reset( $arr ), $arr );
340	}
341
342	/**
343	* Save terms translations
344	*
345	* @api
346	* @since 1.5
347	*
348	* @param int[] $arr An associative array of translations with language code as key and term id as value.
349	* @return void
350	*/
351	function pll_save_term_translations( $arr ) {
352	PLL()->model->term->save_translations( reset( $arr ), $arr );
353	}
354
355	/**
356	* Returns the post language.
357	*
358	* @api
359	* @since 1.5.4
360	*
361	* @param int $post_id Post id.
362	* @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'.
363	* @return string\|false The requested field for the post language, false if no language is associated to that post.
364	*/
365	function pll_get_post_language( $post_id, $field = 'slug' ) {
366	return ( $lang = PLL()->model->post->get_language( $post_id ) ) ? $lang->$field : false;
367	}
368
369	/**
370	* Returns the term language.
371	*
372	* @api
373	* @since 1.5.4
374	*
375	* @param int $term_id Term id.
376	* @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'.
377	* @return string\|false The requested field for the term language, false if no language is associated to that term.
378	*/
379	function pll_get_term_language( $term_id, $field = 'slug' ) {
380	return ( $lang = PLL()->model->term->get_language( $term_id ) ) ? $lang->$field : false;
381	}
382
383	/**
384	* Returns an array of translations of a post.
385	*
386	* @api
387	* @since 1.8
388	*
389	* @param int $post_id Post id.
390	* @return int[] An associative array of translations with language code as key and translation post id as value.
391	*/
392	function pll_get_post_translations( $post_id ) {
393	return PLL()->model->post->get_translations( $post_id );
394	}
395
396	/**
397	* Returns an array of translations of a term.
398	*
399	* @api
400	* @since 1.8
401	*
402	* @param int $term_id Term id.
403	* @return int[] An associative array of translations with language code as key and translation term id as value.
404	*/
405	function pll_get_term_translations( $term_id ) {
406	return PLL()->model->term->get_translations( $term_id );
407	}
408
409	/**
410	* Counts posts in a language.
411	*
412	* @api
413	* @since 1.5
414	*
415	* @param string $lang Language code.
416	* @param array $args {
417	* Optional arguments.
418	* Accepted keys:
419	*
420	* @type string $post_type Post type.
421	* @type int $m YearMonth ( ex: 201307 ).
422	* @type int $year 4 digit year.
423	* @type int $monthnum Month number (from 1 to 12).
424	* @type int $day Day of the month (from 1 to 31).
425	* @type int $author Author id.
426	* @type string $author_name Author nicename.
427	* @type string $post_format Post format.
428	* @type string $post_status Post status.
429	* }
430	* @return int Posts count.
431	*/
432	function pll_count_posts( $lang, $args = array() ) {
433	return PLL()->model->count_posts( PLL()->model->get_language( $lang ), $args );
434	}
435
436	/**
437	* Allows to access the Polylang instance.
438	* However, it is always preferable to use API functions
439	* as internal methods may be changed without prior notice.
440	*
441	* @since 1.8
442	*
443	* @return PLL_Frontend\|PLL_Admin\|PLL_Settings\|PLL_REST_Request
444	*/
445	function PLL() { // PHPCS:ignore WordPress.NamingConventions.ValidFunctionName
446	return $GLOBALS['polylang'];
447	}
448