Muitos sites (e temas) precisam de um seletor de idioma personalizado, que combinará com o design geral da página. Este tutorial explicará como criar seletores de idioma personalizados, usando apenas modelos de HTML, sem escrever em PHP.

Introdução a modelos do Twig para seletores de idioma

O Twig é um mecanismo de modelos, que lhe permite criar com HTML e pseudocódigo.

Por exemplo, este é um modelo do Twig:




<div class="[ css_classes ] my-custom-switcher">



<ul>

   {% for code, language in languages %}



<li class="[ language.css_classes ] my-custom-switcher-item">

           <a href="[ language.url ]">

               {% if language.flag_url %}

                   <img src="[ language.flag_url ]" alt="[ language.code ]" title="[ language.flag_title ]">

               {% endif %}

               [ language.native_name ]

               ([ language.display_name ])

           </a>

       </li>



   {% endfor %}

   </ul>



</div>



O que esse modelo faz é:

  1. Abrir o contêiner DIV e as tags UL para o seletor de idioma;
  2. Iterar pelos diferentes idiomas;
  3. Gerar um item de lista (LI) para cada idioma;
  4. Dentro do item de lista, gerar um link para o idioma;
  5. Se o idioma tiver uma bandeira, apresentá-lo;
  6. Mostrar o nome do idioma;
  7. Fechar todas as tags aninhadas.

Parece simples? Vamos ver como você pode criar modelos como esse em seus próprios seletores de idioma.

Adição de um seletor de idioma ao tema

O WPML lhe permite adicionar um diretório com modelos de seletor de idioma ao tema. Se estiver criando um tema para comercializar, poderá incluir esses modelos no seu tema, para que todos usem. Se estiver personalizando um tema, deverá criar esses modelos de seletor de idioma em um tema filho, para que sua edição não seja perdida a cada atualização do tema.

O modelo de seletor de idioma precisa ser colocado na seguinte estrutura de pastas:

meu-tema/wpml/templates/language-switchers/meu-modelo

Estrutura de diretórios para seus arquivos de seletor de idioma

Estrutura de diretórios para seus arquivos de seletor de idioma

Isso quer dizer que você deve criar uma pasta com o nome “wpml” dentro da raiz do seu tema (ou tema filho). Dentro dela, crie a pasta templates, e dentro dessa última, a pasta “language-switchers”. Dentro do diretório language-switchers, você pode criar um subdiretório para cada modelo que desenvolver (em nosso exemplo, “meu-modelo”).

Dentro do diretório do modelo (“meu-modelo”), você precisa ter os seguintes arquivos, com os seguintes nomes:

  • Arquivo com o nome template.twig (obrigatório)
  • Arquivo com o nome config.json (obrigatório)
  • Arquivos CSS (opcional)
  • Arquivos JS (opcional)
  • Diretório com bandeiras (opcional)

Desenvolvimento do arquivo template.twig

O arquivo template.twig é o próprio modelo que você está criando. Ele utiliza a sintaxe Twig. No modelo, você pode usar estas variáveis:

current_language_code (cadeia)

css_classes           (cadeia)

languages             (matriz)

code          (cadeia)

url           (cadeia)

flag_url      (cadeia)

flag_title   (cadeia)

native_name   (cadeia)

display_name  (cadeia)

is_current    (bool)

css_classes   (cadeia)

Definição de opções no arquivo config.json

Todo seletor de idioma deve ter um arquivo chamado config.json, que dá informações sobre ele ao WPML.

Estes são os campos para esse arquivo:

  • name (obrigatório): O nome do modelo. Não é preciso prefixá-lo, pois o WPML fará isso com o nome do tema ou do plugin. Esse é o único campo obrigatório.
  • version (opcional): A versão do modelo. É recomendado, pois forçará a atualização das folhas de estilo e os recursos de javascript.
  • css (opcional): Por padrão, todos os arquivos CSS existentes no diretório do modelo serão examinados e enfileirados. No entanto, é possível passar uma matriz JSON de arquivos CSS dentro do diretório do modelo. Exemplo: “css”: [“style.css”, “responsive.css”] .
  • js (opcional): Por padrão, todos os arquivos JS existentes no diretório do modelo serão examinados e enfileirados. No entanto, é possível passar uma matriz JSON de arquivos JS dentro do diretório do modelo.

    Exemplo: “js”: [“script.js”, “click-script.js”] . Note que o script deve ser escrito em javascript puro, exceto se o tema ou plugin incluir alguma outra biblioteca por si mesmo.

  • flags_dir (opcional): Por padrão, um diretório de bandeiras “flags” será procurado dentro da pasta do modelo, ou algum outro especificado, caso esteja definido.
  • flag_extension (opcional): A extensão de arquivo das imagens de bandeiras (png, svg, jpg, gif).
  • for (opcional): Por padrão, o modelo ficará disponível para todos os locais do site (“menus”, “sidebars”, “footer”, “post_translations”, “shortcode_actions”). No entanto, você pode especificar um ou mais desses locais em uma matriz JSON.

    Exemplo: “for”: [“sidebars”, “post_translations”] .

  • settings (opcional): É possível substituir as configurações do usuário na UI de administrador forçando a aplicação de determinadas configurações. É só passar um objeto JSON com o valor desejado (0 ou 1) para display_flags , display_names_in_native_lang , display_names_in_current_lang , ou display_link_for_current_lang.

    Exemplo: “settings”: {“display_link_for_current_lang”: 1} .

Abaixo há o exemplo mais básico de um arquivo config.json:


{

"name":           "My custom switcher",

}

E aqui está um exemplo mais completo, com campos adicionais (opcionais):


{

"name":           "Vertical List",

"version":         "1.0",

"css":            ["style.css"],

"js":             ["script.js"],

"flags_dir":      "super-flags",

"flag_extension": "png",

"for":            ["sidebars", "shortcode_actions"],

"settings":       {"display_link_for_current_lang": 1}

}

Exemplos de seletores de idioma

Seletor de idioma de menu

Digamos que você queira criar um seletor de idioma personalizado no menu, como este:

Seletor de Idioma personalizado com códigos ISO

Seletor de Idioma personalizado com códigos ISO

O menu conterá apenas o código ISO para cada idioma (em letras maiúsculas).

  1. Crie uma nova pasta de modelo no nosso tema: meutema/wpml/templates/language-switchers/menu-codigos-iso/
  1. Nessa pasta, adicione um arquivo config.json com o conteúdo abaixo:


{

"name" : "ISO codes for menus",

"for": ["menus"]

}

Basicamente, você define o nome do modelo (que será listado nas escolhas disponíveis) e em que contexto ele estará disponível (apenas para menus).

  1. Agora, adicione o arquivo template.twig com o conteúdo abaixo:


[ code|upper ]

Visto que é um modelo de menu, você só precisa renderizar o conteúdo do elemento do item de menu. Aqui exibimos o código de idioma após ser processado pelo filtro upper do Twig (veja a documentação aqui: http://twig.sensiolabs.org/doc/filters/upper.html).

Observação: Ainda será possível alterar as opções de exibição (bandeira, idioma nativo, etc.) no administrador do WordPress, mas isso não terá efeito algum na interface, visto que nosso modelo personalizado não prevê isso. Para evitar confundir o usuário, podemos fazer com que essas configurações sejam desabilitadas. Aqui está um arquivo config.json mais completo:


{

"name" : "ISO codes for menus",

"for": ["menus"],

"settings": {

   "display_flags": 0,

   "display_names_in_native_lang": 0,

   "display_names_in_current_lang": 0

 }

}

E na imagem abaixo, você pode ver como ficará a interface de administração para o usuário:

Seletor de idioma personalizado no back-end

Seletor de idioma personalizado no back-end

Obtenha os arquivos fonte: na nossa página do GitHub você encontra os arquivos desse exemplo.

Seletor de idioma em lista horizontal

Digamos que você queira exibir um seletor de idioma horizontal bem básico só com bandeiras e o nome do idioma como título do link. Além disso, você deseja usar sua própria coleção de bandeiras no formato SVG.

Seletor de idioma horizontal só com bandeiras

Seletor de idioma horizontal só com bandeiras

  1. Crie sua pasta de modelo personalizado em meutema/wpml/templates/language-switchers/bandeiras-personalizadas-com-titulos/
  1. Importe sua coleção de bandeiras para a pasta meutema/wpml/templates/language-switchers/bandeiras-personalizadas-com-titulos/flags/.

(fonte: https://github.com/lipis/flag-icon-css)

Observação: A coleção de bandeiras deve incluir um arquivo por código de idioma; assim: “en.svg”, “fr.svg”, “es.svg”, “pt-pt.svg”, …

  1. Crie um arquivo config.json como o abaixo:


{

"name": "Custom flags with titles",

"for": ["sidebars"],

"flag_extension": "svg",

"settings": {

  "display_flags": 1,

  "display_names_in_native_lang": 1,

  "display_names_in_current_lang": 1

 }

}

Você apenas define a extensão de arquivo para as bandeiras (“svg”), mas não há necessidade de definir a pasta das bandeiras, visto que estamos usando o nome padrão dela (“flags”).

  1. Crie um arquivo template.twig como o seguinte:




<div class="[ css_classes ] custom-flags-with-titles">



<ul>

     {% <b>for</b> code, language <b>in</b> languages %}



<li class="[ language.css_classes ] item-custom-flags-with-titles">

           <a href="[ language.url ]">

              <img src="[ language.flag_url ]" title="[ language.flag_title ]">

           </a>

        </li>



     {% <b>endfor </b>%}

  </ul>



</div>



  1. Para poder ter alguns estilos CSS, é preciso criar um arquivo style.css como o abaixo:


.custom-flags-with-titles li {

  list-style: none;

  float: left;

  margin: 0 3px;

}



.item-custom-flags-with-titles img {

  max-width: 32px;

  height: auto;

}

Obtenha os arquivos fonte: na nossa página do GitHub você encontra os arquivos desse exemplo.