polylang / include / api.php

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

345 lines 9.8 KB

Raw Download Zip

1	<?php
2
3	/**
4	* Template tag: displays the language switcher
5	*
6	* List of parameters accepted in $args:
7	*
8	* dropdown => displays a dropdown if set to 1, defaults to 0
9	* echo => echoes the the switcher if set to 1 ( default )
10	* hide_if_empty => hides languages with no posts ( or pages ) if set to 1 ( default )
11	* show_flags => shows flags if set to 1, defaults to 0
12	* show_names => shows languages names if set to 1 ( default )
13	* display_names_as => whether to display the language name or code. valid options are 'slug' and 'name'
14	* force_home => forces linking to the home page is set to 1, defaults to 0
15	* hide_if_no_translation => hides the link if there is no translation if set to 1, defaults to 0
16	* hide_current => hides the current language if set to 1, defaults to 0
17	* post_id => if not null, link to translations of post defined by post_id, defaults to null
18	* raw => set this to true to build your own custom language switcher, defaults to 0
19	*
20	* @since 0.5
21	*
22	* @param array $args optional
23	* @return null\|string\|array null if displaying, array if raw is requested, string otherwise
24	*/
25	function pll_the_languages( $args = '' ) {
26	if ( PLL_ADMIN ) {
27	return '';
28	}
29
30	$switcher = new PLL_Switcher;
31	return $switcher->the_languages( PLL()->links, $args );
32	}
33
34	/**
35	* Returns the current language on frontend
36	* Returns the language set in admin language filter on backend ( false if set to all languages )
37	*
38	* @since 0.8.1
39	*
40	* @param string $field optional the language field to return 'name', 'locale', defaults to 'slug'
41	* @return string\|bool the requested field for the current language
42	*/
43	function pll_current_language( $field = 'slug' ) {
44	return isset( PLL()->curlang->$field ) ? PLL()->curlang->$field : false;
45	}
46
47	/**
48	* Returns the default language
49	*
50	* @since 1.0
51	*
52	* @param string $field optional the language field to return 'name', 'locale', defaults to 'slug'
53	* @return string the requested field for the default language
54	*/
55	function pll_default_language( $field = 'slug' ) {
56	return isset( PLL()->options['default_lang'] ) && ( $lang = PLL()->model->get_language( PLL()->options['default_lang'] ) ) && isset( $lang->$field ) ? $lang->$field : false;
57	}
58
59	/**
60	* Among the post and its translations, returns the id of the post which is in the language represented by $slug
61	*
62	* @since 0.5
63	*
64	* @param int $post_id post id
65	* @param string $slug optional language code, defaults to current language
66	* @return int\|null post id of the translation if exists, null otherwise
67	*/
68	function pll_get_post( $post_id, $slug = '' ) {
69	return ( $slug = $slug ? $slug : pll_current_language() ) ? PLL()->model->post->get( $post_id, $slug ) : null;
70	}
71
72	/**
73	* Among the term and its translations, returns the id of the term which is in the language represented by $slug
74	*
75	* @since 0.5
76	*
77	* @param int $term_id term id
78	* @param string $slug optional language code, defaults to current language
79	* @return int\|null term id of the translation if exists, null otherwise
80	*/
81	function pll_get_term( $term_id, $slug = '' ) {
82	return ( $slug = $slug ? $slug : pll_current_language() ) ? PLL()->model->term->get( $term_id, $slug ) : null;
83	}
84
85	/**
86	* Returns the home url in the current language
87	*
88	* @since 0.8
89	*
90	* @param string $lang language code ( optional on frontend )
91	* @return string
92	*/
93	function pll_home_url( $lang = '' ) {
94	if ( empty( $lang ) ) {
95	$lang = pll_current_language();
96	}
97
98	return empty( $lang ) ? home_url( '/' ) : PLL()->links->get_home_url( $lang );
99	}
100
101	/**
102	* Registers a string for translation in the "strings translation" panel
103	*
104	* @since 0.6
105	*
106	* @param string $name a unique name for the string
107	* @param string $string the string to register
108	* @param string $context optional the group in which the string is registered, defaults to 'polylang'
109	* @param bool $multiline optional wether the string table should display a multiline textarea or a single line input, defaults to single line
110	*/
111	function pll_register_string( $name, $string, $context = 'polylang', $multiline = false ) {
112	if ( PLL_ADMIN ) {
113	PLL_Admin_Strings::register_string( $name, $string, $context, $multiline );
114	}
115	}
116
117	/**
118	* Translates a string ( previously registered with pll_register_string )
119	*
120	* @since 0.6
121	*
122	* @param string $string the string to translate
123	* @return string the string translation in the current language
124	*/
125	function pll__( $string ) {
126	static $cache; // Cache object to avoid translating the same string several times
127
128	if ( ! did_action( 'pll_language_defined' ) ) { // No need for translation
129	return $string;
130	}
131
132	if ( empty( $cache ) ) {
133	$cache = new PLL_Cache();
134	}
135
136	if ( false === $str = $cache->get( $string ) ) {
137	$str = __( $string, 'pll_string' );
138	$cache->set( $string, $str );
139	}
140
141	return $str;
142	}
143
144	/**
145	* Echoes a translated string ( previously registered with pll_register_string )
146	*
147	* @since 0.6
148	*
149	* @param string $string the string to translate
150	*/
151	function pll_e( $string ) {
152	echo pll__( $string );
153	}
154
155	/**
156	* Translates a string ( previously registered with pll_register_string )
157	*
158	* @since 1.5.4
159	*
160	* @param string $string the string to translate
161	* @param string $lang language code
162	* @return string the string translation in the requested language
163	*/
164	function pll_translate_string( $string, $lang ) {
165	if ( pll_current_language() == $lang ) {
166	return pll__( $string );
167	}
168
169	static $cache; // Cache object to avoid loading the same translations object several times
170
171	if ( empty( $cache ) ) {
172	$cache = new PLL_Cache();
173	}
174
175	if ( false === $mo = $cache->get( $lang ) ) {
176	$mo = new PLL_MO();
177	$mo->import_from_db( PLL()->model->get_language( $lang ) );
178	$cache->set( $lang, $mo );
179	}
180
181	return $mo->translate( $string );
182	}
183
184	/**
185	* Returns true if Polylang manages languages and translations for this post type
186	*
187	* @since 1.0.1
188	*
189	* @param string post type name
190	* @return bool
191	*/
192	function pll_is_translated_post_type( $post_type ) {
193	return PLL()->model->is_translated_post_type( $post_type );
194	}
195
196	/**
197	* Returns true if Polylang manages languages and translations for this taxonomy
198	*
199	* @since 1.0.1
200	*
201	* @param string taxonomy name
202	* @return bool
203	*/
204	function pll_is_translated_taxonomy( $tax ) {
205	return PLL()->model->is_translated_taxonomy( $tax );
206	}
207
208	/**
209	* Returns the list of available languages
210	*
211	* List of parameters accepted in $args:
212	*
213	* hide_empty => hides languages with no posts if set to true ( defaults to false )
214	* fields => return only that field if set ( see PLL_Language for a list of fields )
215	*
216	* @since 1.5
217	*
218	* @param array $args list of parameters
219	* @return array
220	*/
221	function pll_languages_list( $args = array() ) {
222	$args = wp_parse_args( $args, array( 'fields' => 'slug' ) );
223	return PLL()->model->get_languages_list( $args );
224	}
225
226	/**
227	* Set the post language
228	*
229	* @since 1.5
230	*
231	* @param int $id post id
232	* @param string $lang language code
233	*/
234	function pll_set_post_language( $id, $lang ) {
235	PLL()->model->post->set_language( $id, $lang );
236	}
237
238	/**
239	* Set the term language
240	*
241	* @since 1.5
242	*
243	* @param int $id term id
244	* @param string $lang language code
245	*/
246	function pll_set_term_language( $id, $lang ) {
247	PLL()->model->term->set_language( $id, $lang );
248	}
249
250	/**
251	* Save posts translations
252	*
253	* @since 1.5
254	*
255	* @param array $arr an associative array of translations with language code as key and post id as value
256	*/
257	function pll_save_post_translations( $arr ) {
258	PLL()->model->post->save_translations( reset( $arr ), $arr );
259	}
260
261	/**
262	* Save terms translations
263	*
264	* @since 1.5
265	*
266	* @param array $arr an associative array of translations with language code as key and term id as value
267	*/
268	function pll_save_term_translations( $arr ) {
269	PLL()->model->term->save_translations( reset( $arr ), $arr );
270	}
271
272	/**
273	* Returns the post language
274	*
275	* @since 1.5.4
276	*
277	* @param int $post_id
278	* @param string $field optional the language field to return 'name', 'locale', defaults to 'slug'
279	* @return bool\|string the requested field for the post language, false if no language is associated to that post
280	*/
281	function pll_get_post_language( $post_id, $field = 'slug' ) {
282	return ( $lang = PLL()->model->post->get_language( $post_id ) ) ? $lang->$field : false;
283	}
284
285	/**
286	* Returns the term language
287	*
288	* @since 1.5.4
289	*
290	* @param int $term_id
291	* @param string $field optional the language field to return 'name', 'locale', defaults to 'slug'
292	* @return bool\|string the requested field for the term language, false if no language is associated to that term
293	*/
294	function pll_get_term_language( $term_id, $field = 'slug' ) {
295	return ( $lang = PLL()->model->term->get_language( $term_id ) ) ? $lang->$field : false;
296	}
297
298	/**
299	* Returns an array of translations of a post
300	*
301	* @since 1.8
302	*
303	* @param int $post_id
304	* @return array an associative array of translations with language code as key and translation post_id as value
305	*/
306	function pll_get_post_translations( $post_id ) {
307	return PLL()->model->post->get_translations( $post_id );
308	}
309
310	/**
311	* Returns an array of translations of a term
312	*
313	* @since 1.8
314	*
315	* @param int $term_id
316	* @return array an associative array of translations with language code as key and translation term_id as value
317	*/
318	function pll_get_term_translations( $term_id ) {
319	return PLL()->model->term->get_translations( $term_id );
320	}
321
322	/**
323	* Count posts in a language
324	*
325	* @since 1.5
326	*
327	* @param string $lang language code
328	* @param array $args ( accepted keys: post_type, m, year, monthnum, day, author, author_name, post_format )
329	* @return int posts count
330	*/
331	function pll_count_posts( $lang, $args = array() ) {
332	return PLL()->model->count_posts( PLL()->model->get_language( $lang ), $args );
333	}
334
335	/**
336	* Allows to access the Polylang instance
337	* It is always preferable to use API functions
338	* Internal methods may be changed without prior notice
339	*
340	* @since 1.8
341	*/
342	function PLL() {
343	return $GLOBALS['polylang'];
344	}
345