Installation and configuration guide for the Magento 2 Language Flags module

Installation

Installation via Composer

composer require kowal/module-language-flagsbin/magento module:enable Kowal_LanguageFlagsbin/magento setup:upgradebin/magento cache:flush

Installation from the Git repository

composer config repositories.kowal-language-flags vcs https://github.com/kowalco/language-flagscomposer require kowal/module-language-flagsbin/magento module:enable Kowal_LanguageFlagsbin/magento setup:upgradebin/magento cache:flush

Additional commands for production mode

bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento cache:flush

Configuration location

Admin panel:

Stores > Configuration > Kowal > Language Flags

CMS editor widget

The module provides the following widget:

Language Flags Switcher

It can be inserted in:

• Content > Blocks
• Content > Pages

Editor path:

Edit > Insert Widget > Language Flags Switcher

The widget supports:

• dropdown or inline mode;
• showing or hiding language names;
• an additional CSS class.

Default flags

During bin/magento setup:upgrade, the module copies default SVG files from:

view/frontend/web/images/flags/

to the directory:

pub/media/language_flags/

Only missing files are copied, without overwriting existing flags.

General configuration

The General Settings section contains fields that control the module behavior.

Enable Module

Path:

language_flags/general/enabled

Meaning:

• Yes enables the module;
• No disables the module on the frontend.

Replace Native Store View Switcher

Path:

language_flags/general/native_enabled

Meaning:

• Yes replaces the native Magento switcher with a flag version;
• No leaves the native switcher unchanged.

Native Display Mode

Path:

language_flags/general/native_display_mode

Available options:

• dropdown
• inline

Meaning:

• dropdown shows the current item and a dropdown list of the remaining ones;
• inline shows all flags at once in a single line.

Show Language Names

Path:

language_flags/general/show_labels

Meaning:

• Yes shows language names next to flags;
• No hides the names in the main view, but keeps them for accessibility.

Fallback to Store View Name

Path:

language_flags/general/fallback_to_store_name

Meaning:

• Yes uses the store view name when Label is not filled in;
• No uses the store view code in uppercase.

Inline Flag Gap (px)

Path:

language_flags/general/inline_gap

Meaning:

• sets the spacing between switcher elements in inline mode;
• the value is measured in pixels;
• the default value is 8.

Icon Scale (%)

Path:

language_flags/general/icon_scale_percent

Meaning:

• 100 preserves the original image dimensions;
• a lower value reduces width and height proportionally;
• scales flags in both rendering modes.

Configuration of flag tables

The module supports three separate sets of entries:

1. Store View Flags
2. Website Flags
3. Custom URL Flags

On the frontend, the entries are combined into one set of switcher elements.

Store View Flags

Path:

language_flags/general/flag_config

Purpose:

Configuration of flags for store views handled by the native Magento mechanism.

Form columns

Store Code

Selects a store view from the Magento list.

Meaning:

• assigns a flag to a specific store view;
• uses the native Magento store view switching mechanism.

Flag File

The path to the flag file selected from the built-in file picker.

Meaning:

• defines the image displayed on the frontend;
• can be saved as pl.svg or language_flags/pl.svg;
• relative paths are resolved from the directory:

pub/media/language_flags/

Label

The full language or market name, for example:

• Polish
• English
• German

Meaning:

• is displayed next to the flag when Show Language Names is enabled;
• also serves as helper text for accessibility.

Short Label

A shortened label, for example:

• PL
• EN
• DE

Meaning:

• is used in a more compact view;
• can be used instead of the full name.

Website Flags

Path:

language_flags/general/website_flag_config

Purpose:

Configuration of flags pointing to other websites in the same Magento instance.

How it works

• clicking does not perform the native store switch post;
• the entry is rendered as a regular link to the target website base URL;
• the current website is not added as a separate option.

Form columns

Website

Selects a Magento website from the list.

Meaning:

• defines the target website for the entry;
• is used to retrieve the base URL of the target storefront.

Flag File

Works the same as in Store View Flags.

Label

The full label displayed on the frontend.

If left empty:

• the module will use the website name.

Short Label

A shortened label, for example:

• UK
• DE
• FR

If left empty:

• the module will use the website code in uppercase.

Custom URL Flags

Path:

language_flags/general/custom_url_flag_config

Purpose:

Configuration of flags pointing to any URLs, for example to another Magento instance or an external store.

Form columns

URL

The target link address.

Examples:

• https://example.de/
• https://en.example.com/
• https://shop.example.cz/

Meaning:

• the entry is rendered as a regular href link;
• it does not use the native Magento store switch mechanism.

Flag File

Works the same as in the other tables.

Label

The full label displayed on the frontend.

If left empty:

• the module will try to use the host from the URL.

Short Label

A shortened label for the compact variant.

If left empty:

• the module will build a shortcut based on the host;
• if that is not possible, it will use the URL value.

Preparing flag files

Recommended location:

pub/media/language_flags/

Recommended formats:

• svg
• png

Examples of file names:

pl.svgen.svgde.svgfr.svg

Basic configuration flow

1. Enable the module via Enable Module.
2. Decide whether you want to replace the native Magento switcher.
3. Set Native Display Mode.
4. Add flag files to pub/media/language_flags/.
5. Complete Store View Flags.
6. Add optional entries in Website Flags.
7. Add optional entries in Custom URL Flags.
8. Save the configuration and clear the cache.

Useful CLI commands

bin/magento module:status Kowal_LanguageFlagsbin/magento cache:cleanbin/magento cache:flush