Localizing the SAML2 Login Button Label in Moodle

When running a multilingual Moodle site with SAML2 single sign-on via the auth_saml2 plugin, you may need the login button label to appear in different languages based on the user’s interface language. Two approaches that look like they should work, do not:

• Putting <span class="multilang" lang="en">...</span> tags into the “IdP label override” setting has no effect. The multilang filter only runs on content rendered through Moodle’s format_text() or format_string(). The auth_saml2 plugin passes the label directly from the database to the template without a filter pass.
• Using the Language customization tool (Site administration > Language > Language customization) to override auth_saml2 language strings will not help for a custom label either. That tool only modifies strings defined in language files, not values stored as admin settings in the database.

The root cause: auth_saml2 stores the IdP label as a plain string in mdl_config_plugins and renders it via {{name}} in the login form template with no language awareness.

The correct approach: theme template override

The reliable solution is to override core/loginform.mustache in your Moodle theme and replace the dynamic {{name}} rendering with Moodle language strings defined in the theme.

Moodle’s {{#str}} Mustache helper always resolves against the current user’s interface language. By moving the label from a database-stored admin setting into theme language files, you get full multilang support through the standard Moodle mechanism.

Prerequisites

Template overrides must live inside a theme — there is no other mechanism in Moodle for overriding Mustache templates. If you are not already on a custom theme, create a minimal child theme before proceeding. Editing a third-party theme directly will get overwritten on the next theme update.

A minimal child theme only needs three files.

theme/yourtheme/config.php:

<?php
defined('MOODLE_INTERNAL') || die();

$THEME->name    = 'yourtheme';
$THEME->parents = ['parenttheme'];
$THEME->sheets  = [];

theme/yourtheme/version.php:

<?php
defined('MOODLE_INTERNAL') || die();

$plugin->component = 'theme_yourtheme';
$plugin->version   = 2024010100;
$plugin->requires  = 2022041900;
$plugin->maturity  = MATURITY_STABLE;

theme/yourtheme/lang/en/theme_yourtheme.php:

<?php
defined('MOODLE_INTERNAL') || die();

$string['pluginname'] = 'Your Theme';

Drop the theme directory into theme/ and visit the Moodle notifications page to register it. You do not need to activate it as the default theme yet — do that once the template override is in place.

Step 1: Override the login form template

Copy lib/templates/core/loginform.mustache from Moodle core into your theme at:

theme/yourtheme/templates/core/loginform.mustache

If your parent theme already overrides this template, copy from the parent theme instead of from core, so you preserve its customizations.

In the template, find the block that renders identity providers. The default Moodle core template renders the button label as:

{{#identityproviders}}
    <a href="{{{url}}}" class="btn btn-secondary">
        {{#iconurl}}
            <img src="{{iconurl}}" alt="" width="24" height="24"/>
        {{/iconurl}}
        {{name}}
    </a>
{{/identityproviders}}

Replace {{name}} with a theme language string reference:

{{#identityproviders}}
    <a href="{{{url}}}" class="btn btn-secondary">
        {{#iconurl}}
            <img src="{{iconurl}}" alt="" width="24" height="24"/>
        {{/iconurl}}
        {{#str}}saml_login_label, theme_yourtheme{{/str}}
    </a>
{{/identityproviders}}

For multi-IdP setups where each provider needs a distinct translated label, the loop approach breaks down because there is no per-provider identifier in the template context. In that case, bypass the generic loop and hard-code one button per provider, each pointing to a known URL and using a dedicated string key. This makes the template more tightly coupled to a specific IdP configuration, but gives you full label control per provider.

Step 2: Add language files

Create a language file for each language your site supports:

theme/yourtheme/lang/en/theme_yourtheme.php
theme/yourtheme/lang/nl/theme_yourtheme.php

Each file defines the same string keys with translated values.

lang/en/theme_yourtheme.php:

<?php
defined('MOODLE_INTERNAL') || die();
$string['saml_login_label'] = 'Log in with your organization account';

lang/nl/theme_yourtheme.php:

<?php
defined('MOODLE_INTERNAL') || die();
$string['saml_login_label'] = 'Inloggen met uw organisatieaccount';

Moodle will automatically use the file matching the user’s current interface language. If no file exists for the user’s language, Moodle falls back to English.

Step 3: Purge caches

After deploying your changes, purge Moodle’s theme and template caches: Site administration > Development > Purge all caches.

Caveats

This approach fully decouples the login button label from the auth_saml2 admin setting. Once you override the template, the “IdP label override” field in the plugin settings has no effect on sites using your theme. You own the label entirely from the theme side.

If you later reconfigure auth_saml2 (add a new IdP, change metadata), you will need to update the template and lang files manually to match. This is a minor maintenance trade-off for a clean, built-in multilang solution.