PHPackages                             iridescent-dev/pico-multilanguage-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. iridescent-dev/pico-multilanguage-plugin

ActivePico-plugin[Localization & i18n](/categories/localization)

iridescent-dev/pico-multilanguage-plugin
========================================

A plugin to support content and theme in different languages.

1.0(4y ago)6391MITPHPPHP >=7.0

Since Oct 29Pushed 4y agoCompare

[ Source](https://github.com/iridescent-dev/pico-multilanguage-plugin)[ Packagist](https://packagist.org/packages/iridescent-dev/pico-multilanguage-plugin)[ Docs](https://github.com/iridescent-dev/pico-multilanguage-plugin)[ RSS](/packages/iridescent-dev-pico-multilanguage-plugin/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (3)Used By (0)

Pico MultiLanguage
===================

[](#pico-multilanguage-)

[Pico](http://picocms.org/) plugin for multi-language support.

- [Usage](#usage)
- [Getting Started](#getting-started)
    - [Install](#install)
        - [Integration with other plugins](#integration-with-other-plugins)
    - [Configuration settings](#configuration-settings)
    - [Content translation](#content-translation)
    - [Template variables defined for Twig](#template-variables-defined-for-twig)
    - [Theme translation](#theme-translation)
    - [Changing the site title automatically](#changing-the-site-title-automatically)
    - [Changing the page date formatted automatically](#changing-the-page-date-formatted-automatically)
- [Changelog](#changelog)
    - [1.0](#10)
- [License](#license)

Usage
=====

[](#usage)

A plugin to support content and theme in different languages.

You can define the languages available for your site and translate your content pages and your theme into those languages.

---

**NOTES:**

- You will need to use **the same language codes** wherever you need them.
- An **IETF language tag** like `en` is suggested.
- In all our examples we use the languages `en` and `fr`.

---

Getting Started
===============

[](#getting-started)

Install
-------

[](#install)

Add the plugin in the `plugins` directory of your Pico installation (e.g. `/var/www/html/pico/plugins/`)

- using [Composer](https://getcomposer.org/) `composer require iridescent-dev/pico-multilanguage-plugin`
- or manually by uploading the `MultiLanguage.php` file to your `plugins` directory

Pico MultiLanguage plugin requires PHP >=7.0.

### Integration with other plugins

[](#integration-with-other-plugins)

The MultiLanguage plugin filters the list of pages to keep only pages in the current language. If you are using a plugin which processes the list of pages, it may be necessary to add MultiLanguage to it as a dependency.
Take the example of [Pagination](https://github.com/rewdy/Pico-Pagination): filtering pages by language must be done before paging.

You must add or edit the following line in this plugin:

```
class Pagination extends AbstractPicoPlugin {
	protected $dependsOn = array("MultiLanguage");
  ...
```

Configuration settings
----------------------

[](#configuration-settings)

You can change the default configuration by adding values to your `config` file. Here are the options available and what they do.

- `default_language` - The default language. - *Default value: en*.
- `languages` - The list of available languages and their display names. - *Default value: 'en' => 'English'*.
- `language_dir` - The path to the language directory. - *Default value: language/* (e.g. `/var/www/html/pico/language/`).
    See [Theme translation](#theme-translation).
- `site_titles` - The list of translated titles of your website. - *Default value: (unset)*.
    See [Changing the site title automatically](#changing-the-site-title-automatically).
- `date_formats` - The list of date formats by language. - *Default value: (unset)*.
    See [Changing the page date formatted automatically](#changing-the-page-date-formatted-automatically).
- `date_locales` - The list of date locales by language. - *Default value: (unset)*.
    See [Changing the page date formatted automatically](#changing-the-page-date-formatted-automatically).

For reference, these values are set in `config/config.yml` using the following format:

```
##
# MultiLanguage support
#
default_language: en                # The default language.

languages:                          # The list of available languages and their display names.
    en: English
    fr: Français

language_dir: language/             # The path to the language directory.

site_titles:                        # The list of translated titles of your website.
    en: Website title               #   English title of your website
    fr: Titre du site web           #   French title of your website

date_formats:                       # The list of date formats by language.
                                    #     See https://php.net/manual/en/function.strftime.php for more info
    en: %B %d, %Y                   #   e.g. september 23, 2021
    fr: %d %B %Y                    #   e.g. 23 septembre 2021

date_locales:                       # The list of date locales by language.
                                    #     See https://php.net/manual/en/function.setlocale.php for more info
    en: en_US.UTF-8
    fr: fr_FR.UTF-8
```

Content translation
-------------------

[](#content-translation)

The plugin introduces `Language` and `pid` page headers. Essentially, each language version gets a separate content file with a different `Language` but the same `pid`.

- `Language` is the language of the page. A page without a language header gets assigned the `default_language`.
- `pid` identifies the same page (content-wise) across different languages, making it possible to find a different language version of a certain page. Same content, different language -> same pid.

You can organize your `content` directory with one folder per language, then you can use the `language_base_url` variable instead of `base_url`. See [Template variables defined for Twig](#template-variables-defined-for-twig).

Each language folder can contain `index.md` and `404.md` files. These files must have the corresponding `Language` header and the same `pid`. All Markdown files can be placed in the folder corresponding to their language.

The structure should be as follows:

```
content
  └───en
  │   │   index.md
  │   │   404.md
  │   └   ...
  └───fr
      │   index.md
      │   404.md
      └   ...

```

Sample of `content/en/index.md`

```
---
Title: Welcome
Description: Pico is a stupidly simple, blazing fast, flat file CMS.
Language: en
pid: home
---
```

Sample of `content/fr/index.md`

```
---
Title: Bienvenue
Description: Pico est un CMS de fichier à plat stupidement simple et ultra rapide.
Language: fr
pid: home
---
```

Below we've shown some examples of locations and their corresponding URLs:

URLPhysical Location**/**`content/index.md` if the file exists or `content/`**`[lang]`**`/index.md` **\*****/en**`content/en/index.md`**/fr**`content/fr/index.md`**/fr/sub/page**`content/fr/sub/page.md`**/badurl**`content/404.md` if the file exists or `content/`**`[lang]`**`/404.md` **\*****/en/badurl**`content/en/404.md`**\*** To replace **`[lang]`**, the plugin uses the browser language if it is one of the available `languages`, otherwise the `default_language` is used.

Template variables defined for Twig
-----------------------------------

[](#template-variables-defined-for-twig)

- `{{ languages }}`
    array of all available languages.
- `{{ page_languages }}`
    page data array of all different language versions of the current page, including the current page.
    For example, to access the page in english use `{{ page_languages['en'] }}`.
- `{{ current_language }}`
    the language of the current page.
- `{{ language_base_url }}`
    is equivalent to `{{ base_url }}/{{ current_language }}` and `{{ base_url }}?{{ current_language }}`, depending on enabled URL rewriting. See .
    In content files you can use the `%language_base_url%`.

All this can be used to build a language switcher:

```

 {% for language, display_name in languages %}
      {% if language == current_language %}
          {{ display_name }}
      {% else %}
          {% if page_languages[language] %}
              {{ display_name }}
          {% else %}
              {{ display_name }}
          {% endif %}
      {% endif %}
 {% endfor %}

```

Here, we use `{{ language|link }}` because the homepage URL for each language matches the language code (e.g. `/en` or `/fr`). See [Content translation](#content-translation).

Theme translation
-----------------

[](#theme-translation)

This Twig filter can be used in your theme templates:

- `translate` - To get a translated and formatted string (e.g. `{{ 'my_key'|translate }}`).
    See .

You must add a `language` directory in your Pico installation, with one file per language. Each file must contain all the keys used by the `translate` Twig filter in your templates.

The structure should be as follows:

```
language
  │   en.php
  │   fr.php

```

Sample of `language/en.php`

```