Skip to content

snippets.md

Latest commit

 

History

History
241 lines (187 loc) · 7.67 KB

snippets.md

File metadata and controls

241 lines (187 loc) · 7.67 KB
Raw

Snippets & Examples

A collection of small, focused recipes that show how to integrate the Multisite Language Switcher into a theme or another plugin. The first three mirror the canonical examples published on msls.co; the rest are short worked examples for the public API functions in docs/api.md and the hooks in docs/hooks.md.

Each snippet is intentionally minimal. Treat it as a starting point: copy it into your functions.php or a small mu-plugin, then adapt it to your theme locations, post types, and locales.

Get the current language

In most cases you should use the WordPress function get_locale() when you need the language of the current blog. MSLS exposes a near-equivalent through its blog collection — with the bonus of falling back to en_US when the value is empty — and gives you the two-letter alpha-2 code as a separate accessor.

$blog     = msls_blog_collection()->get_current_blog();
$language = $blog->get_language(); // en_US
$alpha2   = $blog->get_alpha2();   // en

Manipulate the nav menu

The Frontend\Output class is the right entry point when you want to inject the language switcher into a navigation menu. The example below renders the links as flag-only items and appends them to the primary menu only.

It's safer to gate on the existence of msls_output() than to reference the class directly — that way the theme degrades gracefully when MSLS is deactivated.

function my_custom_menu_item( $items, $args ) {
    if ( function_exists( 'msls_output' ) && 'primary' === $args->theme_location ) {
        $arr = msls_output()->get( 2 );
        if ( ! empty( $arr ) ) {
            $items .= '<li>' . implode( '</li><li>', $arr ) . '</li>';
        }
    }

    return $items;
}
add_filter( 'wp_nav_menu_items', 'my_custom_menu_item', 10, 2 );

The integer passed to get() selects the link variant:

/* Link – flag image plus text */
$arr = $obj->get( 0 );

/* TextOnly – just the language text */
$arr = $obj->get( 1 );

/* ImageOnly – just the flag image */
$arr = $obj->get( 2 );

/* TextImage – text label plus flag image */
$arr = $obj->get( 3 );

Iterate the blog collection

When you need to do something for every blog the plugin tracks — emit alternate links, build a custom menu, populate a sitemap — iterate the collection directly:

function my_print_something() {
    foreach ( msls_blog_collection()->get() as $blog ) {
        printf(
            '<link rel="alternate" hreflang="%1$s" href="http://%1$s.example.com/" />',
            $blog->get_language()
        );
    }
}
add_action( 'wp_head', 'my_print_something' );

Note that msls_blog_collection()->get() returns every blog except the current one. Use ->get_objects() instead if you need the full list.

Render the switcher in a template

The single-line drop-in for theme files. Wrap it in a function_exists() guard so the template still renders if the plugin is disabled.

if ( function_exists( 'msls_the_switcher' ) ) {
    msls_the_switcher();
}

To capture the markup as a string — for example to embed it in another component — use msls_get_switcher() and forward optional tag overrides:

$markup = msls_get_switcher(
    array(
        'before_output' => '<ul class="lang">',
        'after_output'  => '</ul>',
        'before_item'   => '<li>',
        'after_item'    => '</li>',
    )
);

Link to a single translation

Use msls_get_permalink() when you want to build your own switcher markup or a single direct link to one specific language. The optional second argument is returned when no translation is available, which makes the call safe to embed inline:

$de_url = msls_get_permalink( 'de_DE', home_url( '/' ) );
echo '<a href="' . esc_url( $de_url ) . '">Deutsche Version</a>';

Customize the hreflang value

msls_head_hreflang filters the value of the hreflang attribute generated in <head>. Use it to enforce a regional locale (for example en-GB instead of plain en) for SEO purposes:

add_filter( 'msls_head_hreflang', function ( $language ) {
    return 'en_US' === $language ? 'en-US' : $language;
} );

Restrict supported post types

By default MSLS treats every public post type as translatable. The msls_supported_post_types filter lets you opt specific post types out — for example a feedback CPT that you keep mono-lingual:

add_filter( 'msls_supported_post_types', function ( array $types ): array {
    return array_values( array_diff( $types, array( 'feedback' ) ) );
} );

The corresponding msls_supported_taxonomies filter does the same for taxonomies.

Override the per-language link markup

msls_output_get runs for every rendered language item just before it joins the output array. The example adds an aria-current="page" attribute when the item points at the current blog and otherwise leaves the markup alone:

add_filter( 'msls_output_get', function ( string $url, $link, bool $is_current_blog ): string {
    $current_attr = $is_current_blog ? ' aria-current="page"' : '';

    return sprintf( '<a href="%s" hreflang="%s"%s>%s</a>',
        esc_url( $url ),
        esc_attr( str_replace( '_', '-', (string) $link->alt ) ),
        $current_attr,
        (string) $link
    );
}, 10, 3 );

LinkInterface only declares __toString(); the values themselves live in the magic properties Link inherits from Registry\GetSet: txt is the blog description, src the flag-icon URL, and alt the locale. Casting the object to a string renders the variant the user selected — which for three of the four variants contains an <img> element, so do not run the result through esc_html().

Set the status of REST-created translations

The Quick Create REST endpoint inserts new translations as drafts by default. Hook msls_quick_create_post_data to inherit the source post's status instead:

add_filter( 'msls_quick_create_post_data', function ( array $post_data, \WP_Post $source ): array {
    $post_data['post_status'] = $source->post_status;

    return $post_data;
}, 10, 2 );

Remember that any custom callback runs alongside the built-in lloc\Msls\RestApi\RestApi::prefix_source_language() filter, which prepends the source locale to the new post's title. Remove it with remove_filter() if that behavior is unwanted in your workflow:

remove_filter(
    'msls_quick_create_post_data',
    array( \lloc\Msls\RestApi\RestApi::class, 'prefix_source_language' ),
    10
);

Widen the reference user dropdown

The "Reference user" dropdown on the settings page lists at most 100 users, in order of registration. On a blog with more accounts than that, MSLS notes the limit below the dropdown. If the account you need is not among them, raise the bound with msls_max_reference_users_count:

add_filter( 'msls_max_reference_users_count', function ( int $count ): int {
    return 500;
} );

A large blog is better served by narrowing the candidates instead of listing more of them. msls_get_users filters the arguments of the underlying get_users() call, so you can restrict the query to the roles that actually qualify as a reference account:

add_filter( 'msls_get_users', function ( array $args ): array {
    $args['role__in'] = array( 'administrator', 'editor' );

    return $args;
} );

Leave number alone in that callback: MSLS sets it to one above the display limit and uses the extra row to detect a truncated list without counting every user of the blog.

See also