Skip to content

Překlady a internacionalizace

Systém překladu je součástí šablonovacího enginu a integrován s databází překladu.

Syntaxe {S ...}

Prvek překladový řetězec (string). Zůstává zachován, jen je spouštěn až v konečné fázi parsování v metodě after(). Vše řeší core/Template/Translate.php.

{S Good Morning}
{S Testovací překladový | text}

Plurální překlady

Obohaceno o plurální překlady. Syntaxe s náhradami:

{$piv=3;$alcohol='zelenou';}
{S Vypil ## a ### piv|{$alcohol}|{$piv}}
  • ## - běžná náhrada
  • ### - plurální varianta (počet)

Příklady

{S Vypil ## a ### piv|rum|8}
{S Běhám ## a mám již ### odběhnutých stovek|utramaratony|6}

PHP funkce translate()

Překlady je možné volat i z PHP skriptů:

<?php
use function Core\I18n\translate;

translate('Download cropped image', LANG, 'admin');
translate('Vypil ## a ### piv|rum|8', LANG);
translate('Běhám ## a mám již ### odběhnutých stovek|utramaratony|6', LANG);

Sběr překladů

Překlady se sbírají staticky CLI scannerem, který prochází zdrojové soubory a hledá všechny překladové řetězce.

./console translation:scanner en admin    # admin překlady pro angličtinu
./console translation:scanner en website  # website překlady pro angličtinu
./console translation:scanner en all      # obojí najednou
./console translation:scanner en all --test  # dry-run (pouze vypíše, neuloží)

Scanner prochází:

  • admin — app/Modules/**, app/admin/**, app/Cubes/**/data.yaml, app/Cubes/**/Controller.php
  • website — app/website/**, app/Cubes/**/template.tpl, app/Cubes/**/Frontend.php

Rozdělení admin / website je dnes důležité i pro samotnou správu překladů. Staré označení backend / frontend už neodpovídá současné architektuře.

Rozpoznává {S text} v .tpl, volání translate() / translateAdmin() / translatedJson() v .php a překladové klíče (title, label, validationText, ...) v .yaml.

Co scanner nezachytí

Dynamicky sestavené stringy nelze staticky detekovat — ty je třeba přidat do DB ručně:

translate($errorMessages[$code], $lang);  // proměnná jako text → missed

Praktický workflow

Typický postup po změně textů v projektu:

  1. přidat nebo upravit texty v tpl, php nebo data.yaml
  2. spustit translation:scanner
  3. doplnit chybějící překlady v administraci
  4. vyčistit cache překladů, pokud je potřeba

Při větší změně je bezpečné nejdřív použít test mód:

./console translation:scanner en all --test

To vypíše nově nalezené texty bez zápisu do DB.

API překlady v administraci

Admin překladová vrstva není jen pasivní CRUD nad tabulkou i18n.

Používá také:

  • App\Modules\I18n\I18nService
  • App\Modules\Translation\FormFields\FormFieldsController
  • App\Modules\TranslationScanner\Service

I18nService umí:

  • CRUD nad databázovými překlady
  • kontrolu duplicit identifikátorů
  • dohledání nepřeložených položek
  • strojový překlad přes Google nebo DeepL

Sekce překladu

Překlady jsou vedené minimálně ve dvou sekcích:

  • website
  • admin

Sekce je důležitá jak pro scanner, tak pro runtime lookup. Stejný text může mít v admin a website jiný význam, a tedy i jiný překlad.

Postup pro nový jazyk

  1. Stáhnout DB z produkce
  2. Spustit ./console translation:scanner {lang} all
  3. Hromadně přeložit v administraci

Mezipaměť překladu

Do mezipaměti se dávají do jedné položky veškeré překladové texty pro daný jazyk a sekci. Klíč je tedy např. translations_frontend_cs pro frontend v češtině.

Díky mezipaměti se nemusí překlady načítat z databáze při každém požadavku.

Jazyky

Podporované jazyky jsou definovány v konfiguraci a jsou dostupné jako konstanta LANG v aplikaci.

Jazyk se určuje:

  1. Z URL (jazykový prefix)
  2. Z cookies
  3. Z defaultního jazyka (DEFAULT_LANG)