polylang / include / api.php

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

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