Language Switcher

PerfLocale provides multiple ways to display a language switcher on your site.

Gutenberg Block

Add the Language Switcher block from the block inserter (search "Language Switcher" or find it under Widgets).

Block Settings

Setting	Options	Default
Style	Flags + Names, Flags Only, Names Only, Dropdown	Flags + Names
Layout	Horizontal, Vertical	Horizontal
Name Format	Native, English, Both - English (Native), Code	Native
Show flags	On/Off	On
Show names	On/Off	On
Hide current	On/Off	Off
Show untranslated	On/Off	Off
Font size	10–24 px	14
Flag size	14–40 px	20
Gap	0–24 px	8

The block uses server-side rendering, so you see a live preview in the editor.

Shortcode: [perflocale_switcher]

Place this shortcode in any post, page, or widget area.

Attributes

Attribute	Values	Default	Description
style	flags_names, flags_only, names_only, dropdown	From settings	Display style
layout	horizontal, vertical	horizontal	List direction
name_format	native, english, both, slug	native	How to display language names
show_flags	1 / 0	1	Show flag emoji
show_names	1 / 0	1	Show language names
hide_current	1 / 0	From settings	Hide the active language
show_untranslated	1 / 0	From settings	Show languages without a translation
class	CSS class name	(empty)	Custom CSS class

Examples

[perflocale_switcher]

[perflocale_switcher style="dropdown"]

[perflocale_switcher style="flags_only" hide_current="1"]

[perflocale_switcher style="names_only" name_format="english"]

[perflocale_switcher layout="vertical" show_flags="0"]

[perflocale_switcher style="flags_names" name_format="both" class="my-switcher"]

Widget

Go to Appearance > Widgets and add the PerfLocale Language Switcher widget. Configure the title and display style.

PHP Template Tag

In your theme templates:

<?php perflocale_language_switcher(); ?>

<?php perflocale_language_switcher( [
	'template'    => 'flags_names',
	'show_flags'  => true,
	'show_names'  => true,
	'show_native' => true,
	'hide_current' => false,
	'class'       => 'my-custom-switcher',
] ); ?>

Theme Template Override

To customize the switcher HTML, copy any template from perflocale/templates/frontend/ to your theme's perflocale/ directory:

your-theme/perflocale/switcher-list.php
your-theme/perflocale/switcher-dropdown.php
your-theme/perflocale/switcher-flags.php

Available variables in templates

Variable	Type	Description
$languages	array	Active language objects
$current_slug	string	Current language slug
$urls	array	[slug => url] map of translation URLs
$args	array	All display arguments

Language object properties

Property	Example	Description
slug	fr	2-3 letter language code
locale	fr_FR	Full WP locale
name	French	English name
native_name	Français	Native name
flag	🇫🇷	Flag emoji
text_direction	ltr	Text direction (ltr or rtl)

Filters

// Filter which languages appear in the switcher.
add_filter( 'perflocale/switcher/languages', function( $languages ) {
	// Remove a specific language.
	return array_filter( $languages, fn( $lang ) => $lang->slug !== 'de' );
} );

// Override the template path.
add_filter( 'perflocale/switcher/template', function( $path, $args ) {
	return get_stylesheet_directory() . '/my-custom-switcher.php';
}, 10, 2 );

// Modify the final HTML.
add_filter( 'perflocale/switcher/output', function( $html, $args ) {
	return '<div class="wrapper">' . $html . '</div>';
}, 10, 2 );