Helper API

PerfLocale provides a fluent helper API via the perflocale() function. This is the recommended way for theme and plugin developers to interact with PerfLocale.

Quick Start

// Get the helper.
$pl = perflocale();

// Current language info.
echo $pl->slug();        // "fr"
echo $pl->locale();      // "fr_FR"
echo $pl->name();        // "French"
echo $pl->native_name(); // "Français"
echo $pl->display_name(); // "French (Français)"
echo $pl->flag();        // "🇫🇷"

Method Reference

Language Information

perflocale()->slug(): string

Returns the current language slug (e.g. "fr"). Empty string if no language detected.

perflocale()->locale(): string

Returns the full locale (e.g. "fr_FR"). Falls back to get_locale().

perflocale()->name(): string

Returns the English name of the current language (e.g. "French").

perflocale()->native_name(): string

Returns the native name (e.g. "Français"). Falls back to the English name.

perflocale()->display_name(): string

Returns a combined display string: "French (Français)". If English and native names are the same, returns just the name.

perflocale()->flag(): string

Returns the flag emoji or code (e.g. "🇫🇷").

perflocale()->current_language(): ?object

Returns the full language object with all properties, or null if not detected.

Language object properties:

Language Checks

perflocale()->is_default(): bool

Returns true if the current language is the default language.

if ( ! perflocale()->is_default() ) {
	// Show "back to English" link.
}

perflocale()->is_rtl(): bool

Returns true if the current language is right-to-left (Arabic, Hebrew, etc.).

$dir = perflocale()->is_rtl() ? 'rtl' : 'ltr';
echo '<div dir="' . $dir . '">';

perflocale()->is_language( string $slug ): bool

Check if the current language matches a specific slug.

if ( perflocale()->is_language( 'fr' ) ) {
	echo 'Bienvenue!';
} elseif ( perflocale()->is_language( 'de' ) ) {
	echo 'Willkommen!';
}

Language Data

perflocale()->default_language(): ?object

Returns the default language object.

$default = perflocale()->default_language();
echo $default->name; // "English"

perflocale()->languages(): array

Returns all active languages as an array of objects.

foreach ( perflocale()->languages() as $lang ) {
	echo $lang->slug . ': ' . $lang->native_name . "\n";
}
// en: English
// fr: Français
// de: Deutsch

URLs

perflocale()->permalink( int $post_id, string $lang_slug ): string

Get the translated permalink for a post in a specific language.

$de_url = perflocale()->permalink( 42, 'de' );
// https://example.com/de/about/

perflocale()->term_link( int $term_id, string $lang_slug ): string

Get the translated term archive link.

$de_cat = perflocale()->term_link( 5, 'de' );
// https://example.com/de/category/news/

perflocale()->home_url( string $lang_slug = '', string $path = '' ): string

Get the home URL for a specific language.

perflocale()->home_url( 'de' );
// https://example.com/de/

perflocale()->home_url( 'de', '/contact/' );
// https://example.com/de/contact/

perflocale()->home_url();
// Current language home URL.

Translations

perflocale()->translations( int $post_id ): array

Get all translations of a post as a [slug => post_id] map.

$translations = perflocale()->translations( 42 );
// ['en' => 42, 'fr' => 56, 'de' => 78]

foreach ( $translations as $slug => $id ) {
	echo $slug . ': ' . get_the_title( $id ) . "\n";
}

Switcher

perflocale()->switcher( array $args = [] ): string

Returns the language switcher HTML string. Accepts the same snake_case arguments as the [perflocale_switcher] shortcode; any argument omitted falls through to the global Settings → Switcher value.

echo perflocale()->switcher();

// Inline flags + names in the footer.
echo perflocale()->switcher( [
	'display'      => 'inline',
	'template'     => 'flags_names',
	'hide_current' => true,
] );

// Compact header dropdown: "EN" pill on the button, full native names
// in the options panel, with stacked up + down chevrons.
echo perflocale()->switcher( [
	'display'        => 'dropdown',
	'name_format'    => 'native',
	'trigger_format' => 'slug',
	'arrow_style'    => 'double',
	'class'          => 'site-header__lang',
] );

See Language Switcher for the full argument list. The per-instance attribute coverage matrix shows how the same arguments are exposed on every other rendering surface (block, widget, shortcode, Customizer floating, theme addons, page-builder integrations).

perflocale()->current_url( string $lang_slug ): string

Returns the URL of the current page in another language — the same canonical URL the bundled switcher and hreflang tags use. On singular pages where the target language has no translation, returns an empty string so callers can fall through to perflocale()->home_url( $slug ) or render an “untranslated” UI as they prefer.

if ( $de_url = perflocale()->current_url( 'de' ) ) {
	echo '<a href="' . esc_url( $de_url ) . '">Deutsch</a>';
}

perflocale()->switcher_links(): array

Returns a structured array of switcher items for the current page — the same data the bundled switcher renders, exposed so themes can build their own markup without re-implementing URL conversion or translation-availability checks. Languages without a translation on the current singular page are still included with is_translated => false and an empty url; themes that want the bundled switcher’s hide-untranslated behaviour can filter on that flag.

Each entry has the following keys:

<ul class="my-lang-switcher">
<?php foreach ( perflocale()->switcher_links() as $link ) : ?>
	<li class="<?php echo $link['is_current'] ? 'is-current' : ''; ?>">
		<?php if ( $link['is_translated'] ) : ?>
			<a href="<?php echo esc_url( $link['url'] ); ?>" hreflang="<?php echo esc_attr( $link['slug'] ); ?>">
				<?php echo esc_html( $link['flag'] . ' ' . $link['native_name'] ); ?>
			</a>
		<?php else : ?>
			<span class="is-untranslated"><?php echo esc_html( $link['native_name'] ); ?></span>
		<?php endif; ?>
	</li>
<?php endforeach; ?>
</ul>

Date & Time

Each language can override the site’s date_format / time_format from PerfLocale → Languages. These helpers return the active language’s resolved format, falling back to the site default when no override is set. Filterable via perflocale/date_format and perflocale/time_format.

perflocale()->date_format(): string

Returns the PHP date-format string for the current language (e.g. "j F Y").

echo wp_date( perflocale()->date_format(), get_post_time( 'U' ) );

perflocale()->time_format(): string

Returns the PHP time-format string for the current language (e.g. "H:i").

perflocale()->datetime_format(): string

Combined date + time format — the two strings joined with a single space.

perflocale()->format_date( int|string|null $timestamp = null ): string

Render a timestamp in the active language. Accepts a Unix int, a strtotime()-parseable string, or null for “now”. Returns an empty string if the input can’t be parsed. Wraps wp_date() so month and day names are localized too.

echo perflocale()->format_date( get_post_time( 'U' ) );
// French: "13 mai 2026"
// English: "May 13, 2026"

perflocale()->format_time( int|string|null $timestamp = null ): string

Same as format_date() but applies the time format.

perflocale()->format_datetime( int|string|null $timestamp = null ): string

Combined date + time render in the active language.

Service Container Access

For advanced use cases, the PerfLocale() function (uppercase) returns the service container:

$plugin = PerfLocale();

$router     = $plugin->get( 'router' );
$settings   = $plugin->get( 'settings' );
$cache      = $plugin->get( 'cache' );
$converter  = $plugin->get( 'url_converter' );

Template Tags

These standalone functions are available for backward compatibility:

Examples

Conditional content by language

if ( perflocale()->is_language( 'fr' ) ) {
	get_template_part( 'partials/hero', 'fr' );
} else {
	get_template_part( 'partials/hero' );
}

Custom language menu

<ul class="lang-menu">
<?php foreach ( perflocale()->languages() as $lang ) : ?>
	<li class="<?php echo perflocale()->is_language( $lang->slug ) ? 'active' : ''; ?>">
		<a href="/<?php echo esc_url( perflocale()->home_url( $lang->slug ) ); ?>">
			<?php echo esc_html( $lang->native_name ); ?>
		</a>
	</li>
<?php endforeach; ?>
</ul>

Show translation links for current post

<?php
$translations = perflocale()->translations( get_the_ID() );
foreach ( $translations as $slug => $post_id ) :
	if ( $post_id === get_the_ID() ) continue;
?>
	<a href="/<?php echo esc_url( get_permalink( $post_id ) ); ?>">
		Read in <?php echo esc_html( strtoupper( $slug ) ); ?>
	</a>
<?php endforeach; ?>