Instruções de instalação e configuração do módulo Magento 2 Language Flags

Instalação

Instalação via Composer

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

Instalação a partir do repositório Git

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

Comandos adicionais para production mode

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

Localização da configuração

Painel de administração:

Stores > Configuration > Kowal > Language Flags

Widget para o editor CMS

O módulo disponibiliza o widget:

Language Flags Switcher

Pode ser inserido em:

• Content > Blocks
• Content > Pages

Caminho no editor:

Edit > Insert Widget > Language Flags Switcher

O widget suporta:

• modo dropdown ou inline;
• ativar ou ocultar nomes de idiomas;
• classe CSS adicional.

Bandeiras predefinidas

Durante bin/magento setup:upgrade, o módulo copia os ficheiros SVG predefinidos de:

view/frontend/web/images/flags/

para o diretório:

pub/media/language_flags/

Apenas os ficheiros em falta são copiados, sem sobrescrever bandeiras já existentes.

Configuração geral

A secção General Settings contém os campos que controlam o funcionamento do módulo.

Enable Module

Caminho:

language_flags/general/enabled

Significado:

• Yes ativa o módulo;
• No desativa o módulo no frontend.

Replace Native Store View Switcher

Caminho:

language_flags/general/native_enabled

Significado:

• Yes substitui o switcher nativo do Magento pela versão com bandeiras;
• No mantém o switcher nativo sem alterações.

Native Display Mode

Caminho:

language_flags/general/native_display_mode

Opções disponíveis:

• dropdown
• inline

Significado:

• dropdown mostra o item atual e uma lista pendente com os restantes;
• inline mostra imediatamente todas as bandeiras numa única linha.

Show Language Names

Caminho:

language_flags/general/show_labels

Significado:

• Yes mostra os nomes dos idiomas ao lado das bandeiras;
• No oculta os nomes na vista principal, mas mantém-nos para acessibilidade.

Fallback to Store View Name

Caminho:

language_flags/general/fallback_to_store_name

Significado:

• Yes usa o nome do store view quando o Label não foi preenchido;
• No usa o código do store view em letras maiúsculas.

Inline Flag Gap (px)

Caminho:

language_flags/general/inline_gap

Significado:

• define o espaçamento entre os elementos do switcher no modo inline;
• o valor é contado em píxeis;
• o valor predefinido é 8.

Icon Scale (%)

Caminho:

language_flags/general/icon_scale_percent

Significado:

• 100 mantém as dimensões originais da imagem;
• um valor inferior reduz a largura e a altura proporcionalmente;
• dimensiona as bandeiras em ambos os modos de renderização.

Configuração das tabelas de bandeiras

O módulo suporta três conjuntos separados de entradas:

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

No frontend, as entradas são combinadas num único conjunto de elementos do switcher.

Store View Flags

Caminho:

language_flags/general/flag_config

Finalidade:

Configuração de bandeiras para store views suportados pelo mecanismo nativo do Magento.

Colunas do formulário

Store Code

Seleciona o store view a partir da lista do Magento.

Significado:

• atribui uma bandeira a um store view específico;
• utiliza o mecanismo nativo de comutação de store view do Magento.

Flag File

Caminho para o ficheiro da bandeira selecionado no seletor de ficheiros incorporado.

Significado:

• define a imagem apresentada no frontend;
• pode ser guardado como pl.svg ou language_flags/pl.svg;
• os caminhos relativos são resolvidos a partir do diretório:

pub/media/language_flags/

Label

Nome completo do idioma ou do mercado, por exemplo:

• Polski
• English
• Deutsch

Significado:

• é mostrado ao lado da bandeira quando Show Language Names está ativado;
• também serve como texto auxiliar para acessibilidade.

Short Label

Etiqueta abreviada, por exemplo:

• PL
• EN
• DE

Significado:

• é utilizada numa vista mais compacta;
• pode ser usada em vez do nome completo.

Website Flags

Caminho:

language_flags/general/website_flag_config

Finalidade:

Configuração de bandeiras que direcionam para outros websites na mesma instância do Magento.

Como funciona

• o clique não executa o store switch post nativo;
• a entrada é renderizada como um link normal para o base URL do website de destino;
• o website atual não é adicionado como opção separada.

Colunas do formulário

Website

Seleciona o website do Magento a partir da lista.

Significado:

• define o website de destino para a entrada;
• é usado para obter o endereço base do storefront de destino.

Flag File

Funciona da mesma forma que em Store View Flags.

Label

Etiqueta completa apresentada no frontend.

Se ficar vazia:

• o módulo usará o nome do website.

Short Label

Etiqueta abreviada, por exemplo:

• UK
• DE
• FR

Se ficar vazia:

• o módulo usará o código do website em letras maiúsculas.

Custom URL Flags

Caminho:

language_flags/general/custom_url_flag_config

Finalidade:

Configuração de bandeiras que direcionam para quaisquer endereços URL, por exemplo para outra instância do Magento ou para uma loja externa.

Colunas do formulário

URL

Endereço de destino do link.

Exemplos:

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

Significado:

• a entrada é renderizada como um link href normal;
• não utiliza o mecanismo nativo de store switch do Magento.

Flag File

Funciona da mesma forma que nas restantes tabelas.

Label

Etiqueta completa apresentada no frontend.

Se ficar vazia:

• o módulo tentará usar o host do URL.

Short Label

Etiqueta abreviada para a variante compacta.

Se ficar vazia:

• o módulo construirá uma abreviatura com base no host;
• se isso não for possível, usará o valor URL.

Preparação dos ficheiros de bandeiras

Localização recomendada:

pub/media/language_flags/

Formatos recomendados:

• svg
• png

Exemplos de nomes de ficheiros:

pl.svgen.svgde.svgfr.svg

Fluxo básico de configuração

1. Ative o módulo em Enable Module.
2. Decida se pretende substituir o switcher nativo do Magento.
3. Defina Native Display Mode.
4. Adicione os ficheiros de bandeiras a pub/media/language_flags/.
5. Preencha Store View Flags.
6. Adicione entradas opcionais em Website Flags.
7. Adicione entradas opcionais em Custom URL Flags.
8. Guarde a configuração e limpe a cache.

Comandos CLI úteis

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