wp_dropdown_languages()
云策文档标注
概述
wp_dropdown_languages() 函数用于生成一个语言选择器的 HTML 下拉列表，可选择显示或返回该列表。它支持自定义参数，如语言列表、翻译选项和选择状态，适用于 WordPress 多语言设置场景。
关键要点
- 函数接受可选参数数组，包括 id、name、languages、translations、selected、echo 等，用于配置选择器的输出。
- 默认情况下，函数会显示已安装语言和可用翻译，并支持选项如站点默认语言和英语（美国）。
- 通过 echo 参数控制是直接输出 HTML 还是返回字符串，便于开发者灵活集成。
- 函数内部使用 wp_parse_args() 处理参数默认值，并依赖 wp_get_available_translations() 获取翻译数据。
- 输出使用 esc_attr()、esc_html() 等函数进行安全转义，确保代码安全性。
代码示例
function wp_dropdown_languages( $args = array() ) {
$parsed_args = wp_parse_args(
$args,
array(
'id' => 'locale',
'name' => 'locale',
'languages' => array(),
'translations' => array(),
'selected' => '',
'echo' => 1,
'show_available_translations' => true,
'show_option_site_default' => false,
'show_option_en_us' => true,
'explicit_option_en_us' => false,
)
);
// 函数体省略，详见文档
}注意事项
- 确保传递有效的 id 和 name 参数，否则函数可能提前返回。
- 当 selected 参数为 'en_US' 且 explicit_option_en_us 为 false 时，值会设为空字符串。
- 函数会从 wp_get_available_translations() 获取翻译数据，如果未提供 translations 参数。
- 输出包含安全转义，但开发者仍需注意上下文使用，避免 XSS 风险。
原文内容
Displays or returns a Language selector.
Description
See also
Parameters
$argsstring|arrayoptional-
Array or string of arguments for outputting the language selector.
idstringID attribute of the select element. Default'locale'.namestringName attribute of the select element. Default'locale'.languagesstring[]List of installed languages, contain only the locales.translationsarrayList of available translations. Default result of wp_get_available_translations() .selectedstringLanguage which should be selected.echobool|intWhether to echo the generated markup. Accepts 0, 1, or their boolean equivalents. Default 1.show_available_translationsboolWhether to show available translations. Default true.show_option_site_defaultboolWhether to show an option to fall back to the site’s locale. Default false.show_option_en_usboolWhether to show an option for English (United States). Default true.explicit_option_en_usboolWhether the English (United States) option uses an explicit value of en_US instead of an empty value. Default false.
Default:
array()
Source
function wp_dropdown_languages( $args = array() ) {
$parsed_args = wp_parse_args(
$args,
array(
'id' => 'locale',
'name' => 'locale',
'languages' => array(),
'translations' => array(),
'selected' => '',
'echo' => 1,
'show_available_translations' => true,
'show_option_site_default' => false,
'show_option_en_us' => true,
'explicit_option_en_us' => false,
)
);
// Bail if no ID or no name.
if ( ! $parsed_args['id'] || ! $parsed_args['name'] ) {
return;
}
// English (United States) uses an empty string for the value attribute.
if ( 'en_US' === $parsed_args['selected'] && ! $parsed_args['explicit_option_en_us'] ) {
$parsed_args['selected'] = '';
}
$translations = $parsed_args['translations'];
if ( empty( $translations ) ) {
require_once ABSPATH . 'wp-admin/includes/translation-install.php';
$translations = wp_get_available_translations();
}
/*
* $parsed_args['languages'] should only contain the locales. Find the locale in
* $translations to get the native name. Fall back to locale.
*/
$languages = array();
foreach ( $parsed_args['languages'] as $locale ) {
if ( isset( $translations[ $locale ] ) ) {
$translation = $translations[ $locale ];
$languages[] = array(
'language' => $translation['language'],
'native_name' => $translation['native_name'],
'lang' => current( $translation['iso'] ),
);
// Remove installed language from available translations.
unset( $translations[ $locale ] );
} else {
$languages[] = array(
'language' => $locale,
'native_name' => $locale,
'lang' => '',
);
}
}
$translations_available = ( ! empty( $translations ) && $parsed_args['show_available_translations'] );
// Holds the HTML markup.
$structure = array();
// List installed languages.
if ( $translations_available ) {
$structure[] = '<optgroup label="' . esc_attr_x( 'Installed', 'translations' ) . '">';
}
// Site default.
if ( $parsed_args['show_option_site_default'] ) {
$structure[] = sprintf(
'<option value="site-default" data-installed="1"%s>%s</option>',
selected( 'site-default', $parsed_args['selected'], false ),
_x( 'Site Default', 'default site language' )
);
}
if ( $parsed_args['show_option_en_us'] ) {
$value = ( $parsed_args['explicit_option_en_us'] ) ? 'en_US' : '';
$structure[] = sprintf(
'<option value="%s" lang="en" data-installed="1"%s>English (United States)</option>',
esc_attr( $value ),
selected( '', $parsed_args['selected'], false )
);
}
// List installed languages.
foreach ( $languages as $language ) {
$structure[] = sprintf(
'<option value="%s" lang="%s"%s data-installed="1">%s</option>',
esc_attr( $language['language'] ),
esc_attr( $language['lang'] ),
selected( $language['language'], $parsed_args['selected'], false ),
esc_html( $language['native_name'] )
);
}
if ( $translations_available ) {
$structure[] = '</optgroup>';
}
// List available translations.
if ( $translations_available ) {
$structure[] = '<optgroup label="' . esc_attr_x( 'Available', 'translations' ) . '">';
foreach ( $translations as $translation ) {
$structure[] = sprintf(
'<option value="%s" lang="%s"%s>%s</option>',
esc_attr( $translation['language'] ),
esc_attr( current( $translation['iso'] ) ),
selected( $translation['language'], $parsed_args['selected'], false ),
esc_html( $translation['native_name'] )
);
}
$structure[] = '</optgroup>';
}
// Combine the output string.
$output = sprintf( '<select name="%s" id="%s">', esc_attr( $parsed_args['name'] ), esc_attr( $parsed_args['id'] ) );
$output .= implode( "n", $structure );
$output .= '</select>';
if ( $parsed_args['echo'] ) {
echo $output;
}
return $output;
}