PHPackages seablast/i18n - 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. seablast/i18n ActiveLibrary[Localization & i18n](/categories/localization) seablast/i18n ============= A lightweight internationalization (i18n) module designed for apps using the Seablast for PHP framework v0.1.4(1w ago)01.3kMITPHPPHP >=7.2 <8.6CI passing Since Aug 3Pushed 1w agoCompare [ Source](https://github.com/WorkOfStan/seablast-i18n)[ Packagist](https://packagist.org/packages/seablast/i18n)[ RSS](/packages/seablast-i18n/feed)WikiDiscussions main Synced 2d ago READMEChangelog (5)Dependencies (11)Versions (12)Used By (0) `Seablast I18n` =============== [](#seablast-i18n) [![Total Downloads](https://camo.githubusercontent.com/42268877481815e0e49b4904ab4be5b307ea925e04d6b1339d3abb0d3a1452b8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736561626c6173742f6931386e2e737667)](https://packagist.org/packages/seablast/i18n)[![Latest Stable Version](https://camo.githubusercontent.com/95e3295ce0d68ffc85687f5a37c5cd595e6da1ca54ed8e7cf3ed87969d59165e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736561626c6173742f6931386e2e737667)](https://packagist.org/packages/seablast/i18n)[![Polish the code](https://github.com/WorkOfStan/seablast-i18n/actions/workflows/polish-the-code.yml/badge.svg)](https://github.com/WorkOfStan/seablast-i18n/actions/workflows/polish-the-code.yml) A lightweight internationalization (i18n) module for apps using the [Seablast for PHP](https://github.com/WorkOfStan/seablast) framework. It provides a Latte translation filter, a language-selection API, optional Universal Language Selector templates, and Phinx migrations for translation data. Installable via Composer, it integrates seamlessly and activates only when needed, allowing you to effortlessly provide multilingual support and manage user language preferences. Usage ----- [](#usage) ### UI [](#ui) The Latte filter `translate` uses the dictionary loaded by `Seablast\I18n\SeablastTranslate`. Seablast registers it in `Seablast\SeablastView::renderLatte()` from the `SeablastConstant::TRANSLATE_CLASS` setting defined in [app.conf.php](conf/app.conf.php). Use as: `const back = {="Zpět"|translate};` Note: In Latte, `SB:LANGUAGE` is defined lazily by the translator. For that reason, `{=''|translate}` in [views/uls.menu.latte](views/uls.menu.latte) runs before `SB:LANGUAGE` is read. ``` const back = {="Zpět"|translate}; const lang = {$configuration->getString('SB:LANGUAGE')}; ``` To display the language selector, include the three `uls.*.latte` files as follows: ``` ... {include '../vendor/seablast/i18n/views/uls.css.latte'} ... ... ... {include '../vendor/seablast/i18n/views/uls.menu.latte'} ... {block script}{/block} {include '../vendor/seablast/i18n/views/uls.js.latte'} ``` Note: The `I18n:SHOW_LANGUAGE_SELECTOR` flag controls whether the contents of all `uls.*.latte` templates are rendered. As a result, you do not need to wrap `uls.*.latte` includes in custom Latte conditions; include them, and the application decides whether they take effect. Instead of using the language selector, you can switch the language programmatically by calling: ``` window.languageSelector(string language); // language is one of the configured language codes, for example: en, cs ``` The caller is responsible for reloading or re-rendering the page so translated strings update: ``` // switch language using Seablast/I18n mechanics and jQuery $("select.language_selector").change(function () { window.languageSelector($(this).val()).then( function () { location.reload(); }, function (err) { console.error(err); }, ); }); ``` The `window.languageSelector` function is declared in `uls.js.latte`. That function returns jQuery.Promise (a promise-like object with `.then()`, `.done()`, `.fail()`, `.always()`) and in the fulfillment value, there's JSON, e.g. `{message: 'en'}`. The language switching endpoint exists independently, but the UI selector is gated by `I18n:SHOW_LANGUAGE_SELECTOR` to prevent exposing unfinished or tenant-specific i18n: ``` const flags = [ "I18n:SHOW_LANGUAGE_SELECTOR", // turned on by default also in `conf/app.conf.php` ]; ``` Note: only languages from the configuration (e.g. `->setArrayString(I18nConstant::LANGUAGE_LIST, ['en', 'cs'])`) are accepted. The first configured language is the default. ### Database structure [](#database-structure) To create the expected database table structure (for dictionary and localised items), just add the seablast/i18n migration path to your phinx.php configuration, e.g. ``` 'paths' => [ 'migrations' => [ '%%PHINX_CONFIG_DIR%%/db/migrations', '%%PHINX_CONFIG_DIR%%/../vendor/seablast/i18n/conf/db/migrations', ], 'seeds' => '%%PHINX_CONFIG_DIR%%/db/seeds' ], ``` ### Dictionary table: `translations` [](#dictionary-table-translations) ColumnTypeAttributesDescription`id`integerPrimary key, auto-increment (`identity`)Unique identifier for each translation entry.`language`string(5)Indexed, part of unique constraintConfigured language code (for example `en` or `cs`).`translation_key`string(255)Indexed, part of unique constraintThe lookup key used in the application (e.g., `"Save PDF"`, `"Back"`).`translation_value`textLocalized string corresponding to the key in the given language.Integration ----------- [](#integration) - Seablast/Seablast::v0.2.11 contains `APP_DIR . '/vendor/seablast/i18n/conf/app.conf.php', // Seablast/i18n extension configuration` so use at least this Seablast version. - `"seablast/seablast": "^0.2.7"` is in the `require-dev` section of `composer.json` because the app that uses Seablast I18n may use whatever dev version of Seablast. ### Language API [](#language-api) - API `'/api/language'` using `'model' => '\Seablast\I18n\Models\ApiLanguageModel'` returns the selected language or accepts a language to store in the cookie 'sbLanguage'. - The cookie 'sbLanguage' is created after a successful language-selection request. ### Language selector [](#language-selector) - Because typically `.htaccess` uses `RedirectMatch 404 vendor\/(?!seablast\/)` to make vendor folder off limits for web access except the seablast library, the jquery.uls is in [Seablast for PHP](https://github.com/WorkOfStan/seablast) since v0.2.11 and not in this module. - However, it's useful to know that to make the SVG icon in `.uls-trigger` adopt the `font-color` of the surrounding element, the following style was added into `uls/images/language.svg`: `fill="currentColor"`. Also `uls/css/jquery.uls.css` was changed (changed: `.uls-trigger`, added: `.uls-trigger icon` and `.uls-trigger .icon svg`). - The selector uses `I18nConstant::LANGUAGE_LIST` as both the allowed ULS language set and its `quickList`; language labels come from ULS data instead of hardcoded labels in this library. - Language is lazy-initialised in SeablastView: `$translator = new $translatorClass($this->model->getConfiguration());` instantiates SeablastTranslate, which calls `$lang = new ApiLanguageModel($this->configuration, new \Seablast\Seablast\Superglobals());`. There `$this->configuration->setString('SB:LANGUAGE', $result);` is set. - `'/api/language'` using `'model' => '\Seablast\I18n\Models\ApiLanguageModel'` is called from window.languageSelector when uls.onSelect with parameter. ### Localised data access [](#localised-data-access) Extend the class FetchLocalisedItemsModel with preset of these three properties ``` /** @var int itemTypeId set in the child class */ protected $itemTypeId; /** @var string page title beginning set in the child class */ protected $titlePrefix = ""; /** @var string page title ending set in the child class*/ protected $titleSuffix = ""; ``` in order to access the localised items filtered by their type. The full class looks like this: ```