Lokalizace

Lokalizace jsou jedním z možných typů pluginu. Jsou to podadresáře v plugins/languages/.

Tvorba nové lokalizace

Při tvorbě nové lokazice je ideální okopírovat a upravit jednu z jich existujících lokalizací. Nezapomeňte upravit iso_code v plugin.json.

Struktura language pluginu

dictionary.php

Tento slovník obsahuje hlavní systémové překlady. Jedná se o obyčejný PHP soubor který vrací asociativní pole.

<?php

return [
    'system.poweredby' => 'Powered by',
    'global.nokit' => 'Nenalezena žádná položka',
    'global.error' => 'Chyba',
    // ....

admin_dictionary.php

Tento slovník obsahuje překlady administrace. Také se jedná o obyčejný PHP soubor který vrací asociativní pole.

Narozdíl od dictionary.php je nepovinný a pokud neexistuje, budou použity popisky administrace z náhradního slovníku (fallback_lang v systémovém config.php).

<?php

return [
    'admin.link.site' => 'Zobrazit stránky',
    'admin.link.newwin' => 'Nové okno',
    'admin.link.home' => 'zpět na hlavní stranu',
    // ....

plugin.json

Seznam klíčů, které můžou být uvedeny v plugin.json. Klíče označeny "*" jsou povinné.

Hlavní nastavení pluginu
Klíč Typ Popis
$schema string

Cesta k JSON schématu. Pomáhá editorům v napovídání klíčů a validaci plugin.json. Nepovinné. 

"$schema": "../../../system/schema/language.json"
name string Čitelný název pluginu.
description string Stručný popis pluginu.
authors object[]

Seznam autorů pluginu.
Klíče "name" a "url" je možné libovolně kombinovat. 

"authors": [
    {"name": "Author1", "url": "https://example.com/"},
    {"name": "Author2"},
    {"url": "https://example.com/"}
]
version string Verze pluginu. Např. "1.0.0".
environment object Prostředí vyžadované pluginem.
  • system - požadovaná verze systému (viz formát)
  • php - požadovaná verze PHP (viz formát)
  • php_extensions - požadované PHP rozšíření
  • debug - požadovaný debug mód
    • true - plugin aktivní pouze v debug režimu
    • false - plugin aktivní pouze mimo debug režim
    • null - plugin vždy aktivní
Příklad: 
"environment": {
    "system": "~8.0.2",
    "php": ">=7.4",
    "php_extensions": ["curl", "iconv"],
    "debug": null
}
Nastavení lokalizace
Klíč Typ Popis
iso_code string

ISO 639-1 jazykový kód. 

"iso_code": "cs"
decimal_point string

Desetinná značka. 

"decimal_point": "."
thousands_separator string

Oddělovač tisíců. 

"thousands_separator": " "
Pokročilé nastavení pluginu
Klíč Typ Popis
dependencies object

Mapa pluginů, na kterých tento plugin závisí a jejich požadovaných verzí (viz formát).

Názvy pluginů jsou ve formátu typ/název, případně pouze název - v takovém případě se předpokládá language. 

"dependencies": {
    "extend/some-plugin": "^1.0",
    "another-plugin": "*"
}
installer string

Relativní cesta ke skriptu, který vrátí instalátor pluginu.

Poznámka: Instalátor se spouští během načítání pluginů a nejsou tedy dostupné ostatní pluginy ani autoloading class samotného pluginu. 

"installer": "installer.php"

Příklad instalátoru:

<?php

use Sunlight\Plugin\PluginInstaller;
use Sunlight\Database\Database as DB;

return new class extends PluginInstaller {
    protected function verify(): bool
    {
        return empty(
            $this->checkTables([
                DB::table('example'),
            ])
        );
    }

    protected function doInstall(): void
    {
        $this->loadSqlString(<<<'SQL'
            CREATE TABLE `sunlight_example` (
                `id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
                `title` varchar(255) NOT NULL
            ) ENGINE='InnoDB';
        SQL);
    }

    protected function doUninstall(): void
    {
        $this->dropTables([
            DB::table('example'),
        ]);
    }
};
autoload object

Dodatečné nastavení autoloadingu ve stejném formátu, jako má Composer. Viz dokumentace.

  • jsou podporovaný pouze klíče "psr-0", "psr-4" a "classmap"
  • každý plugin má automaticky nastaven PSR-4 autoloading do svého class podadresáře
  • composer závislosti mohou být načteny automaticky, viz klíč inject_composer
  • namespace pluginu je řízen pomocí klíče namespace
class string

Název vlastní třídy pluginu.

  • pokud není uveden jiný namespace, je před název třídy automaticky přidán plugin namespace
  • vlastní třída musí dědit Sunlight\Plugin\LanguagePlugin
namespace string

Namespace pluginu.

Pokud není uveden žádný namespace, je vytvořen z kombinace SunlightLanguage a názvu pluginu převedeného na CamelCase. Např. pro plugin language/my-plugin bude namespace SunlightLanguage\MyPlugin

inject_composer bool

Povolit automatickou integraci Composer závislostí pluginu. Výchozí stav je true.

  • pokud je integrace povolena a v adresáři pluginu existuje composer.json, budou do autoloadingu přidány i tyto závislosti
  • s pluginem je potřeba distribuovat i vendor adresář, případně před použitím pluginu spustit composer install v jeho adresáři
  • pokud stejnou závislost poskytuje více pluginů, je preferována její nejnovější možná verze
  • systémové závislosti není možné nahradit
actions object

Vlastní akce pluginu, které je možné spouštět v administraci ve správě rozšíření. 

"actions": {
    "custom-action": "CustomActionClass"
}
  • třída akce musí dědit Sunlight\Plugin\Action\PluginAction
  • pokud není uveden jiný namespace, je před název třídy automaticky přidán plugin namespace
config_defaults object

Výchozí nastavení pluginu. 

"config_defaults": {
    "example_toggle": true,
    "example_string": "hello world!"
}
  • uvedením výchozí konfigurace se aktivuje akce Konfigurovat u daného pluginu v administraci
  • výchozí implementace akce umí editovat pouze boolean a textové hodnoty
  • implementaci akce je možné přetížit definováním vlastní akce s názvem "config" v actions
  • konfigurace se ukládá do souboru config.php v adresáři pluginu
extra object

Extra nastavení pluginu pro účely jiných pluginů.

Je možné k nim přistupovat pomocí metody getExtraOption() na instanci daného pluginu.