diff --git a/latte/bg/develop.texy b/latte/bg/develop.texy index ee1700be03..1dd39d2d2f 100644 --- a/latte/bg/develop.texy +++ b/latte/bg/develop.texy @@ -166,6 +166,22 @@ try { ``` +Местоположение .[#toc-locale]{data-version:3.0.18} +================================================== + +Latte ви позволява да зададете локала, който влияе на форматирането на числата, датите и сортирането. Той се задава чрез метода `setLocale()`. Идентификаторът на локала следва стандарта за езикови маркери на IETF, който използва разширението на PHP `intl`. Той се състои от код на езика и евентуално от код на страната, например `en_US` за английски език в САЩ, `de_DE` за немски език в Германия и т.н. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Настройката на локала влияе на филтрите [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] и [bytes |filters#bytes]. + +.[note] +Изисква разширението PHP `intl`. Настройката в Latte не влияе на глобалната настройка на локала в PHP. + + Строг режим .[#toc-strict-mode]{data-version:3.0.8} =================================================== diff --git a/latte/bg/filters.texy b/latte/bg/filters.texy index 20f4bbaa82..4e32ea4f92 100644 --- a/latte/bg/filters.texy +++ b/latte/bg/filters.texy @@ -11,7 +11,7 @@ | `bytes` | [форматира размера в байтове |#bytes] | `clamp` | [ограничава стойността до определен диапазон |#clamp] | `dataStream` | [Конвертиране на протокола за данни URI |#dataStream] -| `date` | [форматиране на датата |#date] +| `date` | [форматиране на датата и часа |#date] | `explode` | [разделя низа с даден разделител |#explode] | `first` | [връща първия елемент на масив или символен низ |#first] | `group` | [групиране на данни по различни критерии |#group] @@ -20,6 +20,7 @@ | `join` | [обединяване на масив в низ |#implode] | `last` | [връща последния елемент на масив или символен низ |#last] | `length` | [връща дължината на низ или масив |#length] +| `localDate` | [форматиране на датата и часа в съответствие с местността |#localDate] | `number` | [форматира число |#number] | `padLeft` | [допълва низа вляво |#padLeft] | `padRight` | [допълва низа до зададена дължина надясно |#padRight] @@ -168,7 +169,7 @@ breakLines .[filter] bytes(int precision = 2) .[filter] ---------------------------------- -Форматира размера в байтове в удобна за четене от човека форма. +Форматира размера в байтове в удобна за четене от човека форма. Ако е зададена [локална среда |develop#locale], се използват съответните десетични и хилядни разделители. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO date(string format) .[filter] ----------------------------- -Връща дата в зададен формат, като използва опциите на функциите [php:strftime] или [php:date] на PHP. Филтърът получава датата като времеви печат на UNIX, низ или обект от тип `DateTime`. +Форматира датата и часа в съответствие с маската, използвана от функцията на PHP [php:date]. Филтърът приема датата във формат UNIX timestamp, като низ или като обект `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Вижте също [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ length .[filter] ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Форматира датата и часа в зависимост от [локала, |develop#locale] като осигурява последователно и локализирано показване на данните за времето на различни езици и региони. Филтърът приема датата като времеви печат на UNIX, низ или обект `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Ако използвате филтъра без никакви параметри, той ще изведе датата на ниво дълъг формат, както е обяснено по-нататък. + +**а) Използване на формата** + +Параметърът `format` описва кои компоненти на времето трябва да се показват. Той използва буквени кодове, при които броят на повторенията влияе на ширината на изхода: + +| Година | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Месец | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `08` / `август` +| Ден | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `нд` / `неделя` +| Час | `j` / `H` / `h` | предпочитан / 24-часов / 12-часов +| Минута | `m` / `mm` | `5` / `05` (2 цифри, когато се комбинира със секунди) +| Секунда | `s` / `ss` | `8` / `08` (2 цифри, когато се комбинират с минути) + +Редът на кодовете във формата няма значение, тъй като редът на компонентите ще бъде показан в съответствие с конвенциите на локала. Следователно форматът е независим от локала. Например, форматът `yyyyMMMMd` в локала `en_US` извежда `April 15, 2024`, докато в локала `cs_CZ` извежда `15. dubna 2024`: + +| locale: | bg-BG | en_US +|--- +| `format: 'dMy'` | 10.08.2024 г. | 8/10/2024 +| `format: 'yM'` | 08.2024 г. | 8/2024 +| `format: 'yyyyMMMM'` | август 2024 г. | August 2024 +| `format: 'MMMM'` | август | August +| `format: 'jm'` | 17:54 ч. | 5:54 PM +| `format: 'Hm'` | 17:54 ч. | 17:54 +| `format: 'hm'` | 5:54 ч. сл.об. | 5:54 PM + + +**б) Използване на предварително зададени стилове** + +Параметрите `date` и `time` определят нивото на детайлност за показване на датата и часа. Можете да избирате от няколко нива: `full`, `long`, `medium`, `short`. Можете да показвате само датата, само часа или и двете: + +| locale: | bg-BG | en_US +|--- +| `date: short` | 23.01.78 г. | 1/23/78 +| `date: medium` | 23.01.1978 г. | Jan 23, 1978 +| `date: long` | 23 януари 1978 г. | January 23, 1978 +| `date: full` | понеделник, 23 януари 1978 г. | Monday, January 23, 1978 +| `time: short` | 8:30 ч. | 8:30 AM +| `time: medium` | 8:30:59 ч. | 8:30:59 AM +| `time: long` | 8:30:59 ч. Гринуич+1 | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.78 г., 8:30 ч. | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23.01.1978 г., 8:30 ч. | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 януари 1978 г. в 8:30 ч. | January 23, 1978 at 8:30 AM + +За датата можете да използвате и префикса `relative-` (например `relative-short`), който за дати, близки до настоящата, ще покаже `yesterday`, `today` или `tomorrow`; в противен случай ще се покаже по стандартния начин. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Вижте също [дата |#date]. + + lower .[filter] --------------- Преобразува стойността в малки букви. Изисква PHP разширение `mbstring`. @@ -475,7 +539,7 @@ Unescaped: hello number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Форматира число до зададен брой знаци след десетичната запетая. Можете също така да зададете символ на десетичната запетая и разделителя за хиляди. +Форматира число до определен брой знаци след десетичната запетая. Ако е зададена [локална среда |develop#locale], се използват съответните разделители за десетични знаци и хиляди. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[fil ``` +number(string format) .[filter] +------------------------------- +Параметърът `format` ви позволява да определите външния вид на числата точно според вашите нужди. Той изисква зададена [локализация |develop#locale]. Форматът се състои от няколко специални знака, чието пълно описание можете да намерите в документацията на "DecimalFormat"::https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns + +- задължителна цифра, която винаги се показва, дори ако е нула +- `#` незадължителна цифра, показва се само ако числото има цифра на това място +- `@` значима цифра, помага за показване на числото с определен брой значими цифри +- `.` маркира мястото, където трябва да се намира десетичният разделител (запетая или точка, в зависимост от локала) +- `,` се използва за разделяне на групи от цифри, обикновено хиляди +- `%` умножава числото по 100 и добавя знака за процент + +Нека разгледаме някои примери. В първия пример двата знака след десетичната запетая са задължителни; във втория те не са задължителни. Третият пример показва попълване с нули от двете страни, а четвъртият показва само съществуващите цифри: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Значимите цифри определят колко цифри, независимо от десетичната запетая, трябва да бъдат показани, като при необходимост числото се закръгля: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Лесен начин за показване на дадено число като процент. Числото се умножава по 100 и се добавя знакът `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Можем да дефинираме различен формат за положителни и отрицателни числа, разделени със знака `;`. По този начин например положителните числа могат да се показват със знака `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Не забравяйте, че действителният вид на числата може да се различава в зависимост от настройките на локала. Например в някои страни като десетичен разделител се използва запетая вместо точка. Този филтър автоматично отчита това, така че не е необходимо да се притеснявате за него. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Попълва низ с определена дължина с друг низ отляво. @@ -615,7 +727,7 @@ slice(int start, int length = null, bool preserveKeys = false) .[filter] sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Филтърът се използва за сортиране на елементите в масив или итератор, като се запазват ключовете за асоцииране: +Филтърът сортира елементите на масив или итератор, като запазва асоциативните им ключове. Когато е зададен [локал |develop#locale], сортирането следва неговите правила, освен ако не е зададена потребителска функция за сравнение. ```latte {foreach ($names|sort) as $name} diff --git a/latte/cs/develop.texy b/latte/cs/develop.texy index 396ba77813..19e8f2d33a 100644 --- a/latte/cs/develop.texy +++ b/latte/cs/develop.texy @@ -166,6 +166,22 @@ try { ``` +Národní prostředí .{data-version:3.0.18}{toc: Locale} +===================================================== + +Latte umožňuje nastavit národní prostředí, které ovlivňuje formátování čísel, datumů a řazení. Nastavuje se pomocí metody `setLocale()`. Identifikátor prostředí se řídí standardem IETF language tag, který používá rozšíření PHP `intl`. Skládá se z kódu jazyka a případně kódu země, např. `en_US` pro angličtinu ve Spojených státech, `de_DE` pro němčinu v Německu atd. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Nastavení prostředí ovlivňuje filtry [localDate|filters#localDate], [sort|filters#sort], [number|filters#number] a [bytes|filters#bytes]. + +.[note] +Vyžaduje PHP rozšíření `intl`. Nastavení v Latte neovlivňuje globální nastavení locale v PHP. + + Striktní režim .{data-version:3.0.8} ==================================== diff --git a/latte/cs/filters.texy b/latte/cs/filters.texy index 9943d68bf2..0fa1e5a14e 100644 --- a/latte/cs/filters.texy +++ b/latte/cs/filters.texy @@ -11,7 +11,7 @@ V šablonách můžeme používat funkce, které pomáhají upravit nebo přefor | `bytes` | [formátuje velikost v bajtech |#bytes] | `clamp` | [ohraničí hodnotu do daného rozsahu |#clamp] | `dataStream` | [konverze pro Data URI protokol |#datastream] -| `date` | [formátuje datum |#date] +| `date` | [formátuje datum a čas|#date] | `explode` | [rozdělí řetězec na pole podle oddělovače |#explode] | `first` | [vrací první prvek pole nebo znak řetězce |#first] | `group` | [seskupí data podle různých kritérií |#group] @@ -20,6 +20,7 @@ V šablonách můžeme používat funkce, které pomáhají upravit nebo přefor | `join` | [spojí pole do řetězce |#implode] | `last` | [vrací poslední prvek pole nebo znak řetězce |#last] | `length` | [vrací délku řetězce ve znacích nebo pole |#length] +| `localDate` | [formátuje datum a čas podle národního prostředí|#localDate] | `number` | [formátuje číslo |#number] | `padLeft` | [doplní řetězec zleva na požadovanou délku |#padLeft] | `padRight` | [doplní řetězec zprava na požadovanou délku |#padRight] @@ -168,7 +169,7 @@ Přidává před každý znak nového řádku HTML značku `
` bytes(int precision = 2) .[filter] ---------------------------------- -Formátuje velikost v bajtech do lidsky čitelné podoby. +Formátuje velikost v bajtech do lidsky čitelné podoby. Pokud je nastavené [národní prostředí |develop#locale], použijí se odpovídající oddělovače desetinných míst a tisíců. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Vyžaduje PHP rozšíření `fileinfo`. date(string format) .[filter] ----------------------------- -Formátuje datum podle masky buď ve tvaru používaném PHP funkcí [php:strftime] nebo [php:date]. Filtr přijímá datum buď ve formátu UNIX timestamp, v podobě řetězce nebo jako objekt `DateTime`. +Formátuje datum a čas podle masky používané PHP funkcí [php:date]. Filtr přijímá datum ve formátu UNIX timestamp, jako řetězec nebo objekt typu `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Viz také [#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Vrátí délku řetězce nebo pole. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formátuje datum a čas podle [národního prostředí |develop#locale], což zajišťuje konzistentní a lokalizované zobrazení časových údajů napříč různými jazyky a regiony. Filtr přijímá datum jako UNIX timestamp, řetězec nebo objekt typu `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Pokud použijete filtr bez parametrů, vypíše se datum v úrovní `long`, viz dále. + +**a) použití formátu** + +Parametr `format` popisuje, které časové složky se mají zobrazit. Používá pro ně písmenné kódy, jejichž počet opakování ovlivňuje šířku výstupu: + +| rok | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| měsíc | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `srp` / `srpen` +| den | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `ne` / `neděle` +| hodina | `j` / `H` / `h` | preferovaný / 24hodinový / 12hodinový +| minuta | `m` / `mm` | `5` / `05` (2 číslice v kombinaci se sekundami) +| sekunda | `s` / `ss` | `8` / `08` (2 číslice v kombinaci s minutami) + +Na pořadí kódů ve formátu nezáleží, protože pořadí složek se vypíše podle zvyklostí národního prostředí. Formát je tedy na něm nezávislý. Například formát `yyyyMMMMd` v postředí `en_US` vypíše `April 15, 2024`, zatímco v prostředí `cs_CZ` vypíše `15. dubna 2024`: + +| locale: | cs_CZ | en_US +|--- +| `format: 'dMy'` | 10. 8. 2024 | 8/10/2024 +| `format: 'yM'` | 8/2024 | 8/2024 +| `format: 'yyyyMMMM'` | srpen 2024 | August 2024 +| `format: 'MMMM'` | srpen | August +| `format: 'jm'` | 17:22 | 5:22 PM +| `format: 'Hm'` | 17:22 | 17:22 +| `format: 'hm'` | 5:22 odp. | 5:22 PM + + +**b) použití přednastavených stylů** + +Parametry `date` a `time` určují, jak podrobně se má datum a čas vypsat. Můžete si vybrat z několika úrovní: `full`, `long`, `medium`, `short`. Lze nechat vypsat jen datum, jen čas, nebo obojí: + +| locale: | cs_CZ | en_US +|--- +| `date: short` | 23.01.78 | 1/23/78 +| `date: medium` | 23. 1. 1978 | Jan 23, 1978 +| `date: long` | 23. ledna 1978 | January 23, 1978 +| `date: full` | pondělí 23. ledna 1978 | Monday, January 23, 1978 +| `time: short` | 8:30 | 8:30 AM +| `time: medium` | 8:30:59 | 8:30:59 AM +| `time: long` | 8:30:59 SEČ | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.78 8:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23. 1. 1978 8:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23. ledna 1978 v 8:30 | January 23, 1978 at 8:30 AM + +U data lze navíc použít prefix `relative-` (např. `relative-short`), který pro data blízká současnosti zobrazí `včera`, `dnes` nebo `zítra`, jinak se vypíše standardním způsobem. + +```latte +{$date|localDate: date: relative-short} {* včera *} +``` + +Viz také [#date]. + + lower .[filter] --------------- Převede řetězec na malá písmena. Vyžaduje PHP rozšíření `mbstring`. @@ -475,16 +539,64 @@ Neescapovaný: hello number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formátuje číslo na určitý počet desetinných míst. Lze určit znak pro desetinnou čárku a oddělovač tisíců. +Formátuje číslo na určitý počet desetinných míst. Pokud je nastavené [národní prostředí |develop#locale], použijí se odpovídající oddělovače desetinných míst a tisíců. ```latte -{1234.20 |number} 1,234 -{1234.20 |number:1} 1,234.2 -{1234.20 |number:2} 1,234.20 -{1234.20 |number:2, ',', ' '} 1 234,20 +{1234.20|number} 1,234 +{1234.20|number:1} 1,234.2 +{1234.20|number:2} 1,234.20 +{1234.20|number:2, ',', ' '} 1 234,20 ``` +number(string format) .[filter] +------------------------------- +Parametr `format` umožňuje definovat vzhled čísel přesně podle vašich potřeb. K tomu je potřeba mít nastavené [národní prostředí |develop#locale]. Formát se skládá z několika speciálních znaků, jejichž kompletní popis najdete v dokumentaci "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- `0` povinná číslice, vždy se zobrazí, i kdyby to byla nula +- `#` volitelná číslice, zobrazí se jen tehdy, pokud na tomto místě číslo skutečně je +- `@` významná číslice, pomáhá zobrazit číslo s určitým počtem platných číslic +- `.` označuje, kde má být desetinná čárka (nebo tečka, podle země) +- `,` slouží k oddělení skupin číslic, nejčastěji tisíců +- `%` číslo vynásobí 100× a přidá znak procenta + +Pojďme se podívat na příklady. V prvním příkladu jsou dvě desetinná místa povinná, ve druhém volitelná. Třetí příklad ukazuje doplnění nulami zleva i zprava, čtvrtý zobrazuje jen existující číslice: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Významné číslice určují, kolik číslic bez ohledu na desetinou čárku má být zobrazeno, přičemž se zaokrouhluje: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Snadný způsob, jak zobrazit číslo jako procenta. Číslo se vynásobí 100× a přidá se znak `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Můžeme definovat odlišný formát pro kladná a záporná čísla, odděluje je znak `;`. Tímto způsobem lze například nastavit, že kladná čísla se mají zobrazovat se znaménkem `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Pamatujte, že skutečný vzhled čísel se může lišit podle nastavení země. Například v některých zemích se používá čárka místo tečky jako oddělovač desetinných míst. Tento filtr to automaticky zohlední a nemusíte se o nic starat. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Doplní řetězec do určité délky jiným řetězcem zleva. @@ -615,7 +727,7 @@ Ve výchozím nastavení filtr změní pořadí a resetuje celočíselného klí sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Filtr slouží k seřazení prvků v poli nebo iterátoru, přičemž zachovává asociační klíče: +Filtr seřadí prvky pole nebo iterátoru a zachová jejich asociační klíče. Při nastaveném [národním prostředí |develop#locale] se řazení řídí jeho pravidly, pokud není specifikována vlastní porovnávací funkce. ```latte {foreach ($names|sort) as $name} diff --git a/latte/de/develop.texy b/latte/de/develop.texy index a845db1fd3..62d7c01529 100644 --- a/latte/de/develop.texy +++ b/latte/de/develop.texy @@ -166,6 +166,22 @@ try { ``` +Schauplatz .[#toc-locale]{data-version:3.0.18} +============================================== + +Mit Latte können Sie das Gebietsschema festlegen, das sich auf die Formatierung von Zahlen, Daten und die Sortierung auswirkt. Sie wird mit der Methode `setLocale()` festgelegt. Der Locale-Identifikator folgt dem IETF-Standard für Sprachtags, der die PHP-Erweiterung `intl` verwendet. Er besteht aus einem Sprachcode und möglicherweise einem Ländercode, z. B. `en_US` für Englisch in den Vereinigten Staaten, `de_DE` für Deutsch in Deutschland usw. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Die Locale-Einstellung wirkt sich auf die Filter [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] und [bytes |filters#bytes] aus. + +.[note] +Erfordert die PHP-Erweiterung `intl`. Die Einstellung in Latte hat keinen Einfluss auf die globale Locale-Einstellung in PHP. + + Strenger Modus .[#toc-strict-mode]{data-version:3.0.8} ====================================================== diff --git a/latte/de/filters.texy b/latte/de/filters.texy index 1f82a5627b..8e445dd3c3 100644 --- a/latte/de/filters.texy +++ b/latte/de/filters.texy @@ -11,7 +11,7 @@ Filter sind Funktionen, die die Daten in der gewünschten Form verändern oder f | `bytes` | [formatiert Größe in Bytes |#bytes] | `clamp` | [klemmt Wert auf den Bereich |#clamp] | `dataStream` | [Konvertierung des Daten-URI-Protokolls |#datastream] -| `date` | [formatiert Datum |#date] +| `date` | [formatiert das Datum und die Uhrzeit |#date] | `explode` | [trennt eine Zeichenkette durch das angegebene Trennzeichen auf |#explode] | `first` | [gibt das erste Element eines Arrays oder ein Zeichen einer Zeichenkette zurück |#first] | `group` | [gruppiert Daten nach verschiedenen Kriterien |#group] @@ -20,6 +20,7 @@ Filter sind Funktionen, die die Daten in der gewünschten Form verändern oder f | `join` | [verbindet ein Array mit einer Zeichenkette|#implode] | `last` | [gibt das letzte Element eines Arrays oder ein Zeichen einer Zeichenkette zurück |#last] | `length` | [gibt die Länge einer Zeichenkette oder eines Arrays zurück |#length] +| `localDate` | [formatiert das Datum und die Uhrzeit entsprechend dem Gebietsschema |#localDate] | `number` | [formatiert Zahlen |#number] | `padLeft` | [vervollständigt die Zeichenkette auf die angegebene Länge von links |#padLeft] | `padRight` | [vervollständigt die Zeichenkette auf die angegebene Länge von rechts |#padRight] @@ -168,7 +169,7 @@ Fügt HTML-Zeilenumbrüche vor allen Zeilenumbrüchen ein. bytes(int precision = 2) .[filter] ---------------------------------- -Formatiert eine Größe in Bytes in eine für Menschen lesbare Form. +Formatiert die Größe in Bytes in eine für Menschen lesbare Form. Wenn das [Gebietsschema |develop#locale] festgelegt ist, werden die entsprechenden Dezimal- und Tausendertrennzeichen verwendet. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Erfordert die PHP-Erweiterung `fileinfo`. date(string format) .[filter] ----------------------------- -Liefert ein Datum im angegebenen Format unter Verwendung der Optionen der PHP-Funktionen [php:strftime] oder [php:date]. Der Filter erhält ein Datum als UNIX-Zeitstempel, als String oder als Objekt vom Typ `DateTime`. +Formatiert das Datum und die Uhrzeit entsprechend der Maske, die von der PHP-Funktion [php:date] verwendet wird. Der Filter akzeptiert das Datum im UNIX-Zeitstempelformat, als String oder als `DateTimeInterface` Objekt. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Siehe auch [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Gibt die Länge einer Zeichenkette oder eines Arrays zurück. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formatiert Datum und Uhrzeit entsprechend dem [Gebietsschema |develop#locale], um eine konsistente und lokalisierte Anzeige von Zeitdaten in verschiedenen Sprachen und Regionen zu gewährleisten. Der Filter akzeptiert das Datum als UNIX-Zeitstempel, String oder `DateTimeInterface` Objekt. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Wenn Sie den Filter ohne Parameter verwenden, gibt er das Datum in der Langformatebene aus, wie weiter unten erläutert. + +**a) Verwendung des Formats** + +Der Parameter `format` beschreibt, welche Zeitkomponenten angezeigt werden sollen. Er verwendet Buchstabencodes, wobei die Anzahl der Wiederholungen die Breite der Ausgabe beeinflusst: + +| Jahr | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Monat | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `Aug` / `August` +| Tag | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `So` / `Sonntag` +| Stunde | `j` / `H` / `h` | bevorzugt / 24 Stunden / 12 Stunden +| Minute | `m` / `mm` | `5` / `05` (2-stellig, wenn mit Sekunden kombiniert) +| Sekunde | `s` / `ss` | `8` / `08` (2 Ziffern, wenn mit Minuten kombiniert) + +Die Reihenfolge der Codes im Format spielt keine Rolle, da die Reihenfolge der Komponenten entsprechend den Konventionen des jeweiligen Gebietsschemas angezeigt wird. Daher ist das Format ortsunabhängig. Zum Beispiel gibt das Format `yyyyMMMMd` im Gebietsschema `en_US` `April 15, 2024` aus, während es im Gebietsschema `cs_CZ` `15. dubna 2024` ausgibt: + +| locale: | de-DE | en_US +|--- +| `format: 'dMy'` | 10.8.2024 | 8/10/2024 +| `format: 'yM'` | 08/2024 | 8/2024 +| `format: 'yyyyMMMM'` | August 2024 | August 2024 +| `format: 'MMMM'` | August | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 PM | 5:54 PM + + +**b) Verwendung voreingestellter Stile** + +Die Parameter `date` und `time` bestimmen den Detaillierungsgrad der Datums- und Zeitanzeige. Sie können aus mehreren Stufen wählen: `full`, `long`, `medium`, `short`. Sie können nur das Datum, nur die Uhrzeit oder beides anzeigen lassen: + +| locale: | de-DE | en_US +|--- +| `date: short` | 23.01.78 | 1/23/78 +| `date: medium` | 23.01.1978 | Jan 23, 1978 +| `date: long` | 23. Januar 1978 | January 23, 1978 +| `date: full` | Montag, 23. Januar 1978 | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 MEZ | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.78, 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23.01.1978, 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23. Januar 1978 um 08:30 | January 23, 1978 at 8:30 AM + +Für das Datum können Sie auch das Präfix `relative-` verwenden (z. B. `relative-short`), das für Daten, die kurz vor der Gegenwart liegen, `yesterday`, `today` oder `tomorrow` anzeigt; andernfalls erfolgt die Anzeige auf die übliche Weise. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Siehe auch [Datum |#date]. + + lower .[filter] --------------- Konvertiert einen Wert in Kleinbuchstaben. Erfordert die PHP-Erweiterung `mbstring`. @@ -475,7 +539,7 @@ Die missbräuchliche Verwendung des `noescape` Filters kann zu einer XSS-Schwach number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formatiert eine Zahl auf eine bestimmte Anzahl von Dezimalstellen. Sie können auch ein Zeichen für den Dezimalpunkt und das Tausendertrennzeichen angeben. +Formatiert eine Zahl mit einer bestimmten Anzahl von Dezimalstellen. Wenn das [Gebietsschema |develop#locale] festgelegt ist, werden die entsprechenden Dezimal- und Tausendertrennzeichen verwendet. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Formatiert eine Zahl auf eine bestimmte Anzahl von Dezimalstellen. Sie können a ``` +number(string format) .[filter] +------------------------------- +Mit dem Parameter `format` können Sie das Aussehen von Zahlen genau nach Ihren Bedürfnissen festlegen. Er erfordert ein festgelegtes [Gebietsschema |develop#locale]. Das Format besteht aus mehreren Sonderzeichen, deren vollständige Beschreibung in der Dokumentation "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns zu finden ist: + +- obligatorische Ziffer, wird immer angezeigt, auch wenn sie Null ist +- `#` optionale Ziffer, wird nur angezeigt, wenn die Zahl eine Ziffer an dieser Stelle hat +- `@` signifikante Ziffer, hilft bei der Anzeige der Zahl mit einer bestimmten Anzahl signifikanter Ziffern +- `.` markiert die Stelle, an der das Dezimaltrennzeichen stehen soll (Komma oder Punkt, je nach Gebietsschema) +- `,` wird verwendet, um Gruppen von Ziffern zu trennen, normalerweise Tausender +- `%` multipliziert die Zahl mit 100 und fügt das Prozentzeichen hinzu + +Schauen wir uns einige Beispiele an. Im ersten Beispiel sind zwei Dezimalstellen obligatorisch, im zweiten sind sie optional. Das dritte Beispiel zeigt Auffüllungen mit Nullen auf beiden Seiten, und das vierte Beispiel zeigt nur die vorhandenen Ziffern an: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Signifikante Ziffern legen fest, wie viele Ziffern, unabhängig vom Dezimalpunkt, angezeigt werden sollen, wobei die Zahl gegebenenfalls gerundet wird: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Eine einfache Möglichkeit, eine Zahl als Prozentsatz anzuzeigen. Die Zahl wird mit 100 multipliziert und das Zeichen `%` wird hinzugefügt: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Wir können ein unterschiedliches Format für positive und negative Zahlen definieren, die durch ein `;` Zeichen getrennt sind. Auf diese Weise können z. B. positive Zahlen mit einem `+` -Zeichen angezeigt werden: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Denken Sie daran, dass das tatsächliche Aussehen von Zahlen je nach den Einstellungen des Gebietsschemas variieren kann. In einigen Ländern wird zum Beispiel ein Komma anstelle eines Punktes als Dezimaltrennzeichen verwendet. Dieser Filter berücksichtigt dies automatisch, so dass Sie sich darüber keine Gedanken machen müssen. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Füllt eine Zeichenkette bis zu einer bestimmten Länge mit einer anderen Zeichenkette von links auf. @@ -615,7 +727,7 @@ Filter ordnet die Schlüssel des Integer-Arrays standardmäßig neu an und setzt sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Der Filter wird verwendet, um die Elemente in einem Array oder Iterator zu sortieren, wobei die Zuordnungsschlüssel erhalten bleiben: +Der Filter sortiert Elemente eines Arrays oder Iterators unter Beibehaltung ihrer assoziativen Schlüssel. Wenn ein [Gebietsschema |develop#locale] festgelegt ist, folgt die Sortierung dessen Regeln, es sei denn, eine benutzerdefinierte Vergleichsfunktion ist angegeben. ```latte {foreach ($names|sort) as $name} diff --git a/latte/el/develop.texy b/latte/el/develop.texy index 76342e9f87..c0e671a9be 100644 --- a/latte/el/develop.texy +++ b/latte/el/develop.texy @@ -166,6 +166,22 @@ try { ``` +Τοπική τοποθεσία .[#toc-locale]{data-version:3.0.18} +==================================================== + +Το Latte σας επιτρέπει να ορίσετε την τοπική γλώσσα, η οποία επηρεάζει τη μορφοποίηση των αριθμών, των ημερομηνιών και την ταξινόμηση. Ορίζεται χρησιμοποιώντας τη μέθοδο `setLocale()`. Το αναγνωριστικό locale ακολουθεί το πρότυπο ετικέτας γλώσσας IETF, το οποίο χρησιμοποιεί την επέκταση PHP `intl`. Αποτελείται από έναν κωδικό γλώσσας και ενδεχομένως έναν κωδικό χώρας, για παράδειγμα, `en_US` για τα αγγλικά στις Ηνωμένες Πολιτείες, `de_DE` για τα γερμανικά στη Γερμανία, κ.λπ. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Η ρύθμιση locale επηρεάζει τα φίλτρα [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] και [bytes |filters#bytes]. + +.[note] +Απαιτεί την επέκταση PHP `intl`. Η ρύθμιση στο Latte δεν επηρεάζει την παγκόσμια ρύθμιση τοπικής γλώσσας στην PHP. + + Αυστηρή λειτουργία .[#toc-strict-mode]{data-version:3.0.8} ========================================================== diff --git a/latte/el/filters.texy b/latte/el/filters.texy index 40b7a6a564..b35b9e0a1e 100644 --- a/latte/el/filters.texy +++ b/latte/el/filters.texy @@ -11,7 +11,7 @@ | `bytes` | [μορφοποιεί το μέγεθος σε bytes |#bytes] | `clamp` | [συγκρατεί την τιμή στο εύρος |#clamp] | `dataStream` | [Μετατροπή πρωτοκόλλου URI δεδομένων |#datastream] -| `date` | [μορφοποίηση ημερομηνίας |#date] +| `date` | [μορφοποιεί την ημερομηνία και την ώρα |#date] | `explode` | [Διαχωρίζει μια συμβολοσειρά με το δεδομένο διαχωριστικό |#explode] | `first` | [επιστρέφει το πρώτο στοιχείο του πίνακα ή τον χαρακτήρα της συμβολοσειράς |#first] | `group` | [ομαδοποιεί δεδομένα σύμφωνα με διάφορα κριτήρια |#group] @@ -20,6 +20,7 @@ | `join` | [ενώνει έναν πίνακα σε μια συμβολοσειρά |#implode] | `last` | [επιστρέφει το τελευταίο στοιχείο του πίνακα ή τον χαρακτήρα της συμβολοσειράς |#last] | `length` | [επιστρέφει το μήκος μιας συμβολοσειράς ή ενός πίνακα |#length] +| `localDate` | [μορφοποιεί την ημερομηνία και την ώρα σύμφωνα με την τοπική γλώσσα |#localDate] | `number` | [μορφοποίηση αριθμού |#number] | `padLeft` | [συμπληρώνει τη συμβολοσειρά στο συγκεκριμένο μήκος από αριστερά |#padLeft] | `padRight` | [συμπληρώνει τη συμβολοσειρά στο δεδομένο μήκος από τα δεξιά |#padRight] @@ -168,7 +169,7 @@ breakLines .[filter] bytes(int precision = 2) .[filter] ---------------------------------- -Διαμορφώνει ένα μέγεθος σε bytes σε μορφή αναγνώσιμη από τον άνθρωπο. +Διαμορφώνει το μέγεθος σε bytes σε μορφή αναγνώσιμη από τον άνθρωπο. Εάν έχει οριστεί η [τοπική γλώσσα |develop#locale], χρησιμοποιούνται τα αντίστοιχα διαχωριστικά δεκαδικών και χιλιάδων. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO date(string format) .[filter] ----------------------------- -Επιστρέφει μια ημερομηνία στη δεδομένη μορφή χρησιμοποιώντας τις επιλογές των συναρτήσεων PHP [php:strftime] ή [php:date]. Το φίλτρο λαμβάνει μια ημερομηνία ως χρονοσφραγίδα UNIX, συμβολοσειρά ή αντικείμενο τύπου `DateTime`. +Διαμορφώνει την ημερομηνία και την ώρα σύμφωνα με τη μάσκα που χρησιμοποιείται από τη συνάρτηση της PHP [php:date]. Το φίλτρο δέχεται την ημερομηνία σε μορφή χρονοσφραγίδας UNIX, ως συμβολοσειρά ή ως αντικείμενο `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Βλέπε επίσης [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ length .[filter] ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Διαμορφώνει την ημερομηνία και την ώρα σύμφωνα με την [τοπική γλώσσα |develop#locale], εξασφαλίζοντας συνεπή και εντοπισμένη εμφάνιση των δεδομένων ώρας σε διάφορες γλώσσες και περιοχές. Το φίλτρο δέχεται την ημερομηνία ως χρονοσφραγίδα UNIX, συμβολοσειρά ή αντικείμενο `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Αν χρησιμοποιήσετε το φίλτρο χωρίς παραμέτρους, θα εξάγει την ημερομηνία σε επίπεδο μακράς μορφής, όπως εξηγείται παρακάτω. + +**α) Χρήση της μορφής** + +Η παράμετρος `format` περιγράφει ποια στοιχεία της ώρας θα πρέπει να εμφανίζονται. Χρησιμοποιεί κώδικες γραμμάτων, όπου ο αριθμός των επαναλήψεων επηρεάζει το πλάτος της εξόδου: + +| Έτος | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Μήνας | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `Αυγ` / `Αυγούστου` +| Ημέρα | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `Κυρ` / `Κυριακή` +| Ώρα | `j` / `H` / `h` | προτιμώμενη / 24ωρη / 12ωρη +| Minute | `m` / `mm` | `5` / `05` (2 ψηφία όταν συνδυάζεται με δευτερόλεπτα) +| Second | `s` / `ss` | `8` / `08` (2 ψηφία όταν συνδυάζονται με λεπτά) + +Η σειρά των κωδικών στη μορφή δεν έχει σημασία, καθώς η σειρά των στοιχείων θα εμφανίζεται σύμφωνα με τις συμβάσεις της τοπικής γλώσσας. Επομένως, η μορφή είναι ανεξάρτητη από την τοπική γλώσσα. Για παράδειγμα, η μορφή `yyyyMMMMd` στην τοπική γλώσσα `en_US` δίνει την ένδειξη `April 15, 2024`, ενώ στην τοπική γλώσσα `cs_CZ` δίνει την ένδειξη `15. dubna 2024`: + +| locale: | el-GR | en_US +|--- +| `format: 'dMy'` | 10/8/2024 | 8/10/2024 +| `format: 'yM'` | 8/2024 | 8/2024 +| `format: 'yyyyMMMM'` | Αύγουστος 2024 | August 2024 +| `format: 'MMMM'` | Αυγούστου | August +| `format: 'jm'` | 5:54 μ.μ. | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 μ.μ. | 5:54 PM + + +**β) Χρήση προκαθορισμένων στυλ** + +Οι παράμετροι `date` και `time` καθορίζουν το επίπεδο λεπτομέρειας για την εμφάνιση της ημερομηνίας και της ώρας. Μπορείτε να επιλέξετε ανάμεσα σε διάφορα επίπεδα: `full`, `long`, `medium`, `short`. Μπορείτε να εμφανίσετε μόνο την ημερομηνία, μόνο την ώρα ή και τα δύο: + +| locale: | el-GR | en_US +|--- +| `date: short` | 23/1/78 | 1/23/78 +| `date: medium` | 23 Ιαν 1978 | Jan 23, 1978 +| `date: long` | 23 Ιανουαρίου 1978 | January 23, 1978 +| `date: full` | Δευτέρα 23 Ιανουαρίου 1978 | Monday, January 23, 1978 +| `time: short` | 8:30 π.μ. | 8:30 AM +| `time: medium` | 8:30:59 π.μ. | 8:30:59 AM +| `time: long` | 8:30:59 π.μ. CET | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23/1/78, 8:30 π.μ. | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 Ιαν 1978, 8:30 π.μ. | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 Ιανουαρίου 1978 στις 8:30 π.μ. | January 23, 1978 at 8:30 AM + +Για την ημερομηνία, μπορείτε επίσης να χρησιμοποιήσετε το πρόθεμα `relative-` (π.χ. `relative-short`), το οποίο για ημερομηνίες κοντά στο παρόν θα εμφανίσει `yesterday`, `today` ή `tomorrow`, διαφορετικά, θα εμφανίσει με τον τυπικό τρόπο. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Βλέπε επίσης [ημερομηνία |#date]. + + lower .[filter] --------------- Μετατρέπει μια τιμή σε πεζά γράμματα. Απαιτεί την επέκταση PHP `mbstring`. @@ -475,7 +539,7 @@ Unescaped: hello number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Διαμορφώνει έναν αριθμό σε δεδομένο αριθμό δεκαδικών ψηφίων. Μπορείτε επίσης να καθορίσετε έναν χαρακτήρα του δεκαδικού σημείου και του διαχωριστικού χιλιάδων. +Διαμορφώνει έναν αριθμό σε έναν καθορισμένο αριθμό δεκαδικών ψηφίων. Εάν έχει οριστεί η [τοπική γλώσσα |develop#locale], χρησιμοποιούνται τα αντίστοιχα διαχωριστικά δεκαδικών και χιλιάδων. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[fil ``` +number(string format) .[filter] +------------------------------- +Η παράμετρος `format` σας επιτρέπει να καθορίσετε την εμφάνιση των αριθμών ακριβώς σύμφωνα με τις ανάγκες σας. Απαιτεί μια καθορισμένη [τοπική γλώσσα |develop#locale]. Η μορφή αποτελείται από διάφορους ειδικούς χαρακτήρες, την πλήρη περιγραφή των οποίων μπορείτε να βρείτε στην τεκμηρίωση "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- υποχρεωτικό ψηφίο, εμφανίζεται πάντα, ακόμη και αν είναι μηδέν +- `#` προαιρετικό ψηφίο, εμφανίζεται μόνο αν ο αριθμός έχει ψηφίο στη συγκεκριμένη θέση +- `@` σημαντικό ψηφίο, βοηθά στην εμφάνιση του αριθμού με συγκεκριμένο αριθμό σημαντικών ψηφίων +- `.` σηματοδοτεί τη θέση του δεκαδικού διαχωριστικού (κόμμα ή τελεία, ανάλογα με την τοπική γλώσσα) +- `,` χρησιμοποιείται για το διαχωρισμό ομάδων ψηφίων, συνήθως χιλιάδων +- `%` πολλαπλασιάζει τον αριθμό με το 100 και προσθέτει το σύμβολο του ποσοστού + +Ας δούμε μερικά παραδείγματα. Στο πρώτο παράδειγμα, τα δύο δεκαδικά ψηφία είναι υποχρεωτικά- στο δεύτερο, είναι προαιρετικά. Στο τρίτο παράδειγμα εμφανίζεται συμπλήρωση με μηδενικά και στις δύο πλευρές, ενώ στο τέταρτο εμφανίζονται μόνο τα υπάρχοντα ψηφία: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Τα σημαντικά ψηφία καθορίζουν πόσα ψηφία, ανεξάρτητα από το δεκαδικό σημείο, θα πρέπει να εμφανίζονται, στρογγυλοποιώντας τον αριθμό εάν είναι απαραίτητο: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Ένας εύκολος τρόπος για να εμφανίσετε έναν αριθμό ως ποσοστό. Ο αριθμός πολλαπλασιάζεται με το 100 και προστίθεται το σύμβολο `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Μπορούμε να ορίσουμε μια διαφορετική μορφή για θετικούς και αρνητικούς αριθμούς, οι οποίοι χωρίζονται με έναν χαρακτήρα `;`. Με αυτόν τον τρόπο, για παράδειγμα, οι θετικοί αριθμοί μπορούν να εμφανίζονται με το σύμβολο `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Να θυμάστε ότι η πραγματική εμφάνιση των αριθμών μπορεί να διαφέρει ανάλογα με τις ρυθμίσεις της τοπικής γλώσσας. Για παράδειγμα, σε ορισμένες χώρες χρησιμοποιείται κόμμα αντί για τελεία ως διαχωριστικό δεκαδικού ψηφίου. Αυτό το φίλτρο το λαμβάνει αυτόματα υπόψη, οπότε δεν χρειάζεται να ανησυχείτε γι' αυτό. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Συμπληρώνει μια συμβολοσειρά σε συγκεκριμένο μήκος με μια άλλη συμβολοσειρά από αριστερά. @@ -615,7 +727,7 @@ slice(int start, int length = null, bool preserveKeys = false) .[filter] sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Το φίλτρο χρησιμοποιείται για την ταξινόμηση των στοιχείων ενός πίνακα ή ενός επαναλήπτη, διατηρώντας παράλληλα τα κλειδιά συσχέτισης: +Το φίλτρο ταξινομεί τα στοιχεία ενός πίνακα ή ενός επαναλήπτη διατηρώντας τα συσχετιστικά κλειδιά τους. Όταν έχει οριστεί μια [τοπική γλώσσα |develop#locale], η ταξινόμηση ακολουθεί τους κανόνες της, εκτός αν έχει καθοριστεί μια προσαρμοσμένη συνάρτηση σύγκρισης. ```latte {foreach ($names|sort) as $name} diff --git a/latte/en/develop.texy b/latte/en/develop.texy index d3b27885de..9a9a5ad437 100644 --- a/latte/en/develop.texy +++ b/latte/en/develop.texy @@ -166,6 +166,22 @@ try { ``` +Locale .{data-version:3.0.18} +============================= + +Latte allows you to set the locale, which affects the formatting of numbers, dates, and sorting. It is set using the `setLocale()` method. The locale identifier follows the IETF language tag standard, which uses the PHP `intl` extension. It consists of a language code and possibly a country code, for example, `en_US` for English in the United States, `de_DE` for German in Germany, etc. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +The locale setting affects the filters [localDate|filters#localDate], [sort|filters#sort], [number|filters#number], and [bytes|filters#bytes]. + +.[note] +Requires the PHP `intl` extension. The setting in Latte does not affect the global locale setting in PHP. + + Strict Mode .{data-version:3.0.8} ================================= diff --git a/latte/en/filters.texy b/latte/en/filters.texy index 8b54e1fa13..047d2cdd4e 100644 --- a/latte/en/filters.texy +++ b/latte/en/filters.texy @@ -11,7 +11,7 @@ Filters are functions that change or format the data to a form we want. This is | `bytes` | [formats size in bytes |#bytes] | `clamp` | [clamps value to the range |#clamp] | `dataStream` | [Data URI protocol conversion |#datastream] -| `date` | [formats date |#date] +| `date` | [formats the date and time|#date] | `explode` | [splits a string by the given delimiter |#explode] | `first` | [returns first element of array or character of string |#first] | `group` | [groups data according to various criteria |#group] @@ -20,6 +20,7 @@ Filters are functions that change or format the data to a form we want. This is | `join` | [joins an array to a string |#implode] | `last` | [returns last element of array or character of string |#last] | `length` | [returns length of a string or array |#length] +| `localDate` | [formats the date and time according to the locale|#localDate] | `number` | [formats number |#number] | `padLeft` | [completes the string to given length from left |#padLeft] | `padRight` | [completes the string to given length from right |#padRight] @@ -168,7 +169,7 @@ Inserts HTML line breaks before all newlines. bytes(int precision = 2) .[filter] ---------------------------------- -Formats a size in bytes to human-readable form. +Formats the size in bytes into a human-readable form. If the [locale |develop#locale] is set, the corresponding decimal and thousand separators are used. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Requires PHP extension `fileinfo`. date(string format) .[filter] ----------------------------- -Returns a date in the given format using options of [php:strftime] or [php:date] PHP functions. Filter gets a date as a UNIX timestamp, a string or an object of `DateTime` type. +Formats the date and time according to the mask used by the PHP function [php:date]. The filter accepts the date in UNIX timestamp format, as a string, or as a `DateTimeInterface` object. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +See also [#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Returns length of a string or array. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formats date and time according to the [locale |develop#locale], ensuring consistent and localized display of time data across different languages and regions. The filter accepts the date as a UNIX timestamp, string, or `DateTimeInterface` object. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +If you use the filter without any parameters, it will output the date in the long format level, as explained further. + +**a) Using the format** + +The `format` parameter describes which time components should be displayed. It uses letter codes, where the number of repetitions affects the width of the output: + +| Year | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Month | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `Aug` / `August` +| Day | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `Sun` / `Sunday` +| Hour | `j` / `H` / `h` | preferred / 24-hour / 12-hour +| Minute | `m` / `mm` | `5` / `05` (2 digits when combined with seconds) +| Second | `s` / `ss` | `8` / `08` (2 digits when combined with minutes) + +The order of the codes in the format doesn’t matter, as the order of components will be displayed according to the locale's conventions. Therefore, the format is locale-independent. For example, the format `yyyyMMMMd` in the `en_US` locale outputs `April 15, 2024`, while in the `cs_CZ` locale it outputs `15. dubna 2024`: + +| locale: | cs_CZ | en_US +|--- +| `format: 'dMy'` | 10. 8. 2024 | 8/10/2024 +| `format: 'yM'` | 8/2024 | 8/2024 +| `format: 'yyyyMMMM'` | srpen 2024 | August 2024 +| `format: 'MMMM'` | srpen | August +| `format: 'jm'` | 17:22 | 5:22 PM +| `format: 'Hm'` | 17:22 | 17:22 +| `format: 'hm'` | 5:22 odp. | 5:22 PM + + +**b) Using preset styles** + +The `date` and `time` parameters determine the level of detail for the date and time display. You can choose from several levels: `full`, `long`, `medium`, `short`. You can display just the date, just the time, or both: + +| locale: | cs_CZ | en_US +|--- +| `date: short` | 23.01.78 | 1/23/78 +| `date: medium` | 23. 1. 1978 | Jan 23, 1978 +| `date: long` | 23. ledna 1978 | January 23, 1978 +| `date: full` | pondělí 23. ledna 1978 | Monday, January 23, 1978 +| `time: short` | 8:30 | 8:30 AM +| `time: medium` | 8:30:59 | 8:30:59 AM +| `time: long` | 8:30:59 SEČ | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.78 8:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23. 1. 1978 8:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23. ledna 1978 v 8:30 | January 23, 1978 at 8:30 AM + +For the date, you can also use the prefix `relative-` (e.g., `relative-short`), which for dates close to the present will display `yesterday`, `today`, or `tomorrow`; otherwise, it will display in the standard way. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +See also [#date]. + + lower .[filter] --------------- Converts a value to lowercase. Requires PHP extension `mbstring`. @@ -475,16 +539,64 @@ Misuse of the `noescape` filter can lead to an XSS vulnerability! Never use it u number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formats a number to given number of decimal places. You can also specify a character of the decimal point and thousands separator. +Formats a number to a specified number of decimal places. If the [locale |develop#locale] is set, the corresponding decimal and thousand separators are used. ```latte -{1234.20 |number} 1,234 -{1234.20 |number:1} 1,234.2 -{1234.20 |number:2} 1,234.20 -{1234.20 |number:2, ',', ' '} 1 234,20 +{1234.20|number} 1,234 +{1234.20|number:1} 1,234.2 +{1234.20|number:2} 1,234.20 +{1234.20|number:2, ',', ' '} 1 234,20 ``` +number(string format) .[filter] +------------------------------- +The `format` parameter allows you to define the appearance of numbers exactly according to your needs. It requires a set [locale |develop#locale]. The format consists of several special characters, the complete description of which can be found in the "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns documentation: + +- `0` mandatory digit, always displayed even if it's zero +- `#` optional digit, displayed only if the number has a digit in that place +- `@` significant digit, helps to display the number with a certain number of significant digits +- `.` marks where the decimal separator should be (comma or dot, depending on the locale) +- `,` used to separate groups of digits, usually thousands +- `%` multiplies the number by 100 and adds the percent sign + +Let's look at some examples. In the first example, two decimal places are mandatory; in the second, they are optional. The third example shows padding with zeros on both sides, and the fourth displays only the existing digits: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Significant digits determine how many digits, regardless of the decimal point, should be displayed, rounding the number if necessary: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +An easy way to display a number as a percentage. The number is multiplied by 100 and the `%` sign is added: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +We can define a different format for positive and negative numbers, separated by a `;` character. This way, for example, positive numbers can be displayed with a `+` sign: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Remember that the actual appearance of numbers may vary depending on the locale settings. For example, in some countries, a comma is used instead of a dot as a decimal separator. This filter automatically accounts for this, so you don't need to worry about it. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Pads a string to a certain length with another string from left. @@ -615,7 +727,7 @@ Filter will reorder and reset the integer array keys by default. This behaviour sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -The filter is used to sort the elements in an array or iterator while preserving the association keys: +The filter sorts elements of an array or iterator while preserving their associative keys. When a [locale |develop#locale] is set, the sorting follows its rules unless a custom comparison function is specified. ```latte {foreach ($names|sort) as $name} diff --git a/latte/es/develop.texy b/latte/es/develop.texy index e925b76524..01b100ae14 100644 --- a/latte/es/develop.texy +++ b/latte/es/develop.texy @@ -166,6 +166,22 @@ try { ``` +Localidad .[#toc-locale]{data-version:3.0.18} +============================================= + +Latte le permite establecer la configuración regional, que afecta al formato de los números, las fechas y la ordenación. Se establece usando el método `setLocale()`. El identificador de configuración regional sigue el estándar de etiquetas de idioma IETF, que utiliza la extensión PHP `intl`. Consiste en un código de idioma y posiblemente un código de país, por ejemplo, `en_US` para inglés en los Estados Unidos, `de_DE` para alemán en Alemania, etc. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +La configuración regional afecta a los filtros [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] y [bytes |filters#bytes]. + +.[note] +Requiere la extensión PHP `intl`. La configuración de Latte no afecta a la configuración regional global de PHP. + + Modo estricto .[#toc-strict-mode]{data-version:3.0.8} ===================================================== diff --git a/latte/es/filters.texy b/latte/es/filters.texy index 309ff9a45e..bd61a2f102 100644 --- a/latte/es/filters.texy +++ b/latte/es/filters.texy @@ -11,7 +11,7 @@ Los filtros son funciones que cambian o formatean los datos de la forma que quer | `bytes` | [formatea el tamaño en bytes |#bytes] | `clamp` | [sujeta el valor al rango|#clamp] | `dataStream` | [Conversión de protocolo URI de datos|#datastream] -| `date` | [Formatea la fecha |#date] +| `date` | [formatea la fecha y la hora |#date] | `explode` | [divide una cadena por el delimitador dado |#explode] | `first` | [devuelve el primer elemento de una matriz o carácter de una cadena |#first] | `group` | [agrupa los datos según varios criterios |#group] @@ -20,6 +20,7 @@ Los filtros son funciones que cambian o formatean los datos de la forma que quer | `join` | [une una matriz con una cadena|#implode] | `last` | [devuelve el último elemento de la matriz o carácter de la cadena |#last] | `length` | [devuelve la longitud de una cadena o matriz |#length] +| `localDate` | [formatea la fecha y la hora según la configuración regional |#localDate] | `number` | [Formatea un número |#number] | `padLeft` | [completa la cadena a la longitud dada desde la izquierda |#padLeft] | `padRight` | [completa la cadena a la longitud dada desde la derecha|#padRight] @@ -168,7 +169,7 @@ Inserta saltos de línea HTML antes de todas las nuevas líneas. bytes(int precision = 2) .[filter] ---------------------------------- -Formatea un tamaño en bytes a formato legible por humanos. +Formatea el tamaño en bytes de forma legible. Si se establece la [configuración regional |develop#locale], se utilizan los separadores decimales y de miles correspondientes. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Requiere extensión PHP `fileinfo`. date(string format) .[filter] ----------------------------- -Devuelve una fecha en el formato dado usando las opciones de las funciones PHP [php:strftime] o [php:date]. Filter obtiene una fecha como una marca de tiempo UNIX, una cadena o un objeto de tipo `DateTime`. +Formatea la fecha y la hora según la máscara utilizada por la función de PHP [php:date]. El filtro acepta la fecha en formato UNIX timestamp, como cadena o como objeto `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Véase también [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Devuelve la longitud de una cadena o matriz. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formatea la fecha y la hora de acuerdo con la [configuración regional |develop#locale], lo que garantiza una visualización coherente y localizada de los datos de la hora en diferentes idiomas y regiones. El filtro acepta la fecha como marca de tiempo UNIX, cadena u objeto `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Si utiliza el filtro sin ningún parámetro, mostrará la fecha en el nivel de formato largo, como se explica más adelante. + +**a) Utilización del formato** + +El parámetro `format` describe qué componentes horarios deben mostrarse. Utiliza códigos de letras, en los que el número de repeticiones afecta a la anchura de la salida: + +| Año | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Mes | `M` / `MM` / `MMM`, `MMMM` | `8` / `08` / `ago` / `agosto` +| Día | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `dom` / `domingo` +| Hora | `j` / `H` / `h` | preferido / 24 horas / 12 horas +| Minuto | `m` / `mm` | `5` / `05` (2 dígitos cuando se combinan con segundos) +| Segundo | `s` / `ss` | `8` / `08` (2 dígitos cuando se combinan con minutos) + +El orden de los códigos en el formato no importa, ya que el orden de los componentes se mostrará según las convenciones de la configuración regional. Por lo tanto, el formato es independiente de la configuración regional. Por ejemplo, el formato `yyyyMMMMd` en la localización `en_US` produce `April 15, 2024`, mientras que en la localización `cs_CZ` produce `15. dubna 2024`: + +| locale: | es-ES | en_US +|--- +| `format: 'dMy'` | 10/8/2024 | 8/10/2024 +| `format: 'yM'` | 8/2024 | 8/2024 +| `format: 'yyyyMMMM'` | agosto de 2024 | August 2024 +| `format: 'MMMM'` | agosto | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 p. m. | 5:54 PM + + +**b) Utilización de estilos predefinidos** + +Los parámetros `date` y `time` determinan el nivel de detalle de la visualización de la fecha y la hora. Puede elegir entre varios niveles: `full`, `long`, `medium`, `short`. Puede mostrar sólo la fecha, sólo la hora o ambas: + +| locale: | es-ES | en_US +|--- +| `date: short` | 23/1/78 | 1/23/78 +| `date: medium` | 23 ene 1978 | Jan 23, 1978 +| `date: long` | 23 de enero de 1978 | January 23, 1978 +| `date: full` | lunes, 23 de enero de 1978 | Monday, January 23, 1978 +| `time: short` | 8:30 | 8:30 AM +| `time: medium` | 8:30:59 | 8:30:59 AM +| `time: long` | 8:30:59 CET | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23/1/78, 8:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 ene 1978, 8:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 de enero de 1978, 8:30 | January 23, 1978 at 8:30 AM + +Para la fecha, también puede utilizar el prefijo `relative-` (por ejemplo, `relative-short`), que para fechas cercanas al presente mostrará `yesterday`, `today`, o `tomorrow`; de lo contrario, se mostrará de la forma estándar. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Véase también [fecha |#date]. + + lower .[filter] --------------- Convierte un valor a minúsculas. Requiere la extensión PHP `mbstring`. @@ -475,7 +539,7 @@ Unescaped: hello number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formatea un número con un número dado de decimales. También puede especificar un carácter del punto decimal y del separador de miles. +Formatea un número con el número de decimales especificado. Si se establece la [configuración regional |develop#locale], se utilizan los separadores decimales y de miles correspondientes. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Formatea un número con un número dado de decimales. También puede especificar ``` +number(string format) .[filter] +------------------------------- +El parámetro `format` le permite definir la apariencia de los números exactamente según sus necesidades. Requiere una [configuración regional |develop#locale] establecida. El formato consta de varios caracteres especiales, cuya descripción completa puede encontrarse en la documentación "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- dígito obligatorio, se muestra siempre aunque sea cero +- `#` dígito opcional, se muestra sólo si el número tiene un dígito en ese lugar +- `@` dígito significativo, ayuda a mostrar el número con un cierto número de dígitos significativos +- `.` marca dónde debe estar el separador decimal (coma o punto, según la configuración regional) +- `,` se utiliza para separar grupos de dígitos, normalmente miles +- `%` multiplica el número por 100 y añade el signo de porcentaje + +Veamos algunos ejemplos. En el primer ejemplo, los dos decimales son obligatorios; en el segundo, son opcionales. El tercer ejemplo muestra relleno con ceros a ambos lados, y el cuarto muestra sólo los dígitos existentes: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Los dígitos significativos determinan cuántos dígitos, independientemente del punto decimal, deben mostrarse, redondeando el número si es necesario: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Una forma sencilla de mostrar un número como porcentaje. El número se multiplica por 100 y se añade el signo `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Podemos definir un formato diferente para los números positivos y negativos, separados por un carácter `;`. Así, por ejemplo, los números positivos pueden mostrarse con el signo `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Recuerde que el aspecto real de los números puede variar en función de la configuración regional. Por ejemplo, en algunos países se utiliza una coma en lugar de un punto como separador decimal. Este filtro lo tiene en cuenta automáticamente, así que no tienes que preocuparte por ello. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Rellena una cadena de una longitud determinada con otra cadena de la izquierda. @@ -615,7 +727,7 @@ Filter reordenará y restablecerá las claves de la matriz de enteros por defect sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -El filtro se utiliza para ordenar los elementos de un array o iterador conservando las claves de asociación: +El filtro ordena los elementos de un array o iterador conservando sus claves asociativas. Cuando se establece una [configuración regional |develop#locale], la ordenación sigue sus reglas a menos que se especifique una función de comparación personalizada. ```latte {foreach ($names|sort) as $name} diff --git a/latte/fr/develop.texy b/latte/fr/develop.texy index e444e942ed..7e13825f75 100644 --- a/latte/fr/develop.texy +++ b/latte/fr/develop.texy @@ -166,6 +166,22 @@ try { ``` +Locale .[#toc-locale]{data-version:3.0.18} +========================================== + +Latte vous permet de définir la locale, qui affecte le formatage des nombres, des dates et des tris. Elle est définie à l'aide de la méthode `setLocale()`. L'identifiant de la locale suit la norme de balise de langue de l'IETF, qui utilise l'extension PHP `intl`. Il se compose d'un code de langue et éventuellement d'un code de pays, par exemple, `en_US` pour l'anglais aux États-Unis, `de_DE` pour l'allemand en Allemagne, etc. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Les paramètres linguistiques affectent les filtres [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] et [bytes |filters#bytes]. + +.[note] +Nécessite l'extension PHP `intl`. Les paramètres de Latte n'affectent pas les paramètres linguistiques globaux de PHP. + + Mode strict .[#toc-strict-mode]{data-version:3.0.8} =================================================== diff --git a/latte/fr/filters.texy b/latte/fr/filters.texy index 4149816502..3ed03d5d75 100644 --- a/latte/fr/filters.texy +++ b/latte/fr/filters.texy @@ -11,7 +11,7 @@ Les filtres sont des fonctions qui modifient ou formatent les données selon nos | `bytes` | [Formate la taille en octets |#bytes] | `clamp` | [Fixe la valeur à l'intervalle |#clamp] | `dataStream` | [Conversion du protocole URI des données |#datastream] -| `date` | [Formate la date |#date] +| `date` | [Formatage de la date et de l'heure |#date] | `explode` | [divise une chaîne de caractères par le délimiteur donné |#explode] | `first` | [renvoie le premier élément d'un tableau ou le premier caractère d'une chaîne de caractères |#first] | `group` | [regroupe les données en fonction de différents critères |#group] @@ -20,6 +20,7 @@ Les filtres sont des fonctions qui modifient ou formatent les données selon nos | `join` | [joint un tableau à une chaîne de caractères |#implode] | `last` | [renvoie le dernier élément d'un tableau ou le dernier caractère d'une chaîne de caractères |#last] | `length` | [retourne la longueur d'une chaîne ou d'un tableau |#length] +| `localDate` | [Formate la date et l'heure en fonction des paramètres locaux |#localDate] | `number` | [Formate un nombre |#number] | `padLeft` | [Complète une chaîne de caractères à une longueur donnée en partant de la gauche |#padLeft] | `padRight` | [Complète la chaîne à la longueur donnée à partir de la droite |#padRight] @@ -168,7 +169,7 @@ Insère des sauts de ligne HTML avant tous les retours à la ligne. bytes(int precision = 2) .[filter] ---------------------------------- -Formate une taille en octets sous une forme lisible par l'homme. +Formate la taille en octets sous une forme lisible par l'homme. Si la [langue locale |develop#locale] est définie, les séparateurs décimaux et de milliers correspondants sont utilisés. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Nécessite l'extension PHP `fileinfo`. date(string format) .[filter] ----------------------------- -Renvoie une date au format donné en utilisant les options des fonctions PHP [php:strftime] ou [php:date]. Le filtre permet d'obtenir une date sous la forme d'un timestamp UNIX, d'une chaîne de caractères ou d'un objet de type `DateTime`. +Formate la date et l'heure selon le masque utilisé par la fonction PHP [php:date]. Le filtre accepte la date au format timestamp UNIX, sous forme de chaîne de caractères ou d'objet `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Voir aussi [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Renvoie la longueur d'une chaîne ou d'un tableau. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formate la date et l'heure en fonction de la [locale |develop#locale], ce qui garantit un affichage cohérent et localisé des données temporelles dans différentes langues et régions. Le filtre accepte la date sous forme d'horodatage UNIX, de chaîne de caractères ou d'objet `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Si vous utilisez le filtre sans aucun paramètre, il affichera la date au niveau du format long, comme expliqué plus loin. + +**a) Utilisation du format** + +Le paramètre `format` décrit les composantes de l'heure qui doivent être affichées. Il utilise des codes de lettres, dont le nombre de répétitions affecte la largeur de la sortie : + +| Année | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Mois | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `août` / `août` +| Jour : `d` / `dd` / `E` / `EEEE` | `1` / `01` / `dim.` / `dimanche` +| Heure | `j` / `H` / `h` | préférée / 24 heures / 12 heures +| Minute | `m` / `mm` | `5` / `05` (2 chiffres lorsqu'ils sont combinés avec les secondes) +| Heure | `s` / `ss` | `8` / `08` (2 chiffres lorsqu'ils sont combinés avec les secondes) + +L'ordre des codes dans le format n'a pas d'importance, car l'ordre des composants sera affiché selon les conventions locales. Le format est donc indépendant de la locale. Par exemple, le format `yyyyMMMMd` dans la locale `en_US` produit `April 15, 2024`, alors que dans la locale `cs_CZ` il produit `15. dubna 2024`: + +| locale: | fr-FR | en_US +|--- +| `format: 'dMy'` | 10/08/2024 | 8/10/2024 +| `format: 'yM'` | 08/2024 | 8/2024 +| `format: 'yyyyMMMM'` | août 2024 | August 2024 +| `format: 'MMMM'` | août | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 PM | 5:54 PM + + +**b) Utilisation de styles prédéfinis** + +Les paramètres `date` et `time` déterminent le niveau de détail de l'affichage de la date et de l'heure. Vous avez le choix entre plusieurs niveaux : `full`, `long`, `medium`, `short`. Vous pouvez afficher uniquement la date, uniquement l'heure ou les deux : + +| locale: | fr-FR | en_US +|--- +| `date: short` | 23/01/1978 | 1/23/78 +| `date: medium` | 23 janv. 1978 | Jan 23, 1978 +| `date: long` | 23 janvier 1978 | January 23, 1978 +| `date: full` | lundi 23 janvier 1978 | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 UTC+1 | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23/01/1978 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 janv. 1978, 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 janvier 1978 à 08:30 | January 23, 1978 at 8:30 AM + +Pour la date, vous pouvez également utiliser le préfixe `relative-` (par exemple, `relative-short`), qui affichera `yesterday`, `today` ou `tomorrow` pour les dates proches de la date actuelle ; sinon, l'affichage se fera de manière standard. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Voir aussi [date |#date]. + + lower .[filter] --------------- Convertit une valeur en minuscule. Nécessite l'extension PHP `mbstring`. @@ -475,7 +539,7 @@ Une mauvaise utilisation du filtre `noescape` peut conduire à une vulnérabilit number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formate un nombre avec un nombre donné de décimales. Vous pouvez également spécifier un caractère du point décimal et du séparateur de milliers. +Formate un nombre avec le nombre de décimales spécifié. Si la [locale |develop#locale] est définie, les séparateurs de décimales et de milliers correspondants sont utilisés. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Formate un nombre avec un nombre donné de décimales. Vous pouvez également sp ``` +number(string format) .[filter] +------------------------------- +Le paramètre `format` vous permet de définir l'apparence des chiffres exactement selon vos besoins. Il nécessite une [locale |develop#locale] définie. Le format se compose de plusieurs caractères spéciaux, dont la description complète se trouve dans la documentation "DecimalFormat" ::https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns + +- chiffre obligatoire, toujours affiché même s'il est nul +- `#` chiffre optionnel, affiché seulement si le nombre a un chiffre à cette place +- `@` chiffre significatif, permet d'afficher le nombre avec un certain nombre de chiffres significatifs +- `.` marque l'emplacement du séparateur décimal (virgule ou point, selon la langue) +- `,` utilisé pour séparer des groupes de chiffres, généralement des milliers +- `%` multiplie le nombre par 100 et ajoute le signe de pourcentage + +Voyons quelques exemples. Dans le premier exemple, deux décimales sont obligatoires ; dans le deuxième, elles sont facultatives. Le troisième exemple montre un remplissage avec des zéros des deux côtés, et le quatrième n'affiche que les chiffres existants : + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Les chiffres significatifs déterminent le nombre de chiffres à afficher, indépendamment de la virgule, en arrondissant le nombre si nécessaire : + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Une façon simple d'afficher un nombre en pourcentage. Le nombre est multiplié par 100 et le signe `%` est ajouté : + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Nous pouvons définir un format différent pour les nombres positifs et négatifs, séparés par le caractère `;`. Ainsi, par exemple, les nombres positifs peuvent être affichés avec le signe `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +N'oubliez pas que l'apparence réelle des nombres peut varier en fonction des paramètres locaux. Par exemple, dans certains pays, une virgule est utilisée à la place d'un point comme séparateur décimal. Ce filtre en tient compte automatiquement, vous n'avez donc pas à vous en préoccuper. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Remplit une chaîne de caractères d'une certaine longueur avec une autre chaîne de caractères à partir de la gauche. @@ -615,7 +727,7 @@ Filter réordonnera et réinitialisera les clés du tableau d'entiers par défau sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Le filtre est utilisé pour trier les éléments d'un tableau ou d'un itérateur tout en préservant les clés d'association : +Le filtre trie les éléments d'un tableau ou d'un itérateur tout en préservant leurs clés associatives. Lorsqu'une [locale |develop#locale] est définie, le tri suit ses règles à moins qu'une fonction de comparaison personnalisée ne soit spécifiée. ```latte {foreach ($names|sort) as $name} diff --git a/latte/hu/develop.texy b/latte/hu/develop.texy index 80a77b993c..78d5e737db 100644 --- a/latte/hu/develop.texy +++ b/latte/hu/develop.texy @@ -166,6 +166,22 @@ try { ``` +Helyszín .[#toc-locale]{data-version:3.0.18} +============================================ + +A Latte lehetővé teszi a helyi nyelv beállítását, amely befolyásolja a számok, dátumok és a rendezés formázását. A beállítás a `setLocale()` módszerrel történik. A locale azonosító követi az IETF nyelvi tag szabványát, amely a PHP `intl` kiterjesztését használja. Ez egy nyelvkódból és esetleg egy országkódból áll, például `en_US` az Egyesült Államokban az angol nyelvhez, `de_DE` a német nyelvhez Németországban, stb. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +A nyelvi beállítás befolyásolja a [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] és [bytes |filters#bytes] szűrőket. + +.[note] +A PHP `intl` bővítményt igényli. A Latte beállítása nem befolyásolja a PHP globális nyelvi beállítását. + + Szigorú üzemmód .[#toc-strict-mode]{data-version:3.0.8} ======================================================= diff --git a/latte/hu/filters.texy b/latte/hu/filters.texy index 3692d74e5f..07144f677d 100644 --- a/latte/hu/filters.texy +++ b/latte/hu/filters.texy @@ -11,7 +11,7 @@ A szűrők olyan függvények, amelyek megváltoztatják vagy formázzák az ada | `bytes` | [méretformázás bájtban |#bytes] | `clamp` | [az értéket a tartományba szorítja |#clamp] | `dataStream` | [Adat URI protokoll átalakítás |#datastream] -| `date` | [dátumformázás |#date] +| `date` | [dátum és idő formázása |#date] | `explode` | [a karakterláncot a megadott elválasztóval osztja fel |#explode] | `first` | [visszaadja a tömb első elemét vagy a karakterlánc első karakterét |#first] | `group` | [adatok csoportosítása különböző kritériumok |#group] szerint @@ -20,6 +20,7 @@ A szűrők olyan függvények, amelyek megváltoztatják vagy formázzák az ada | `join` | [egy tömböt egy karakterlánchoz kapcsol |#implode] | `last` | [visszaadja a tömb utolsó elemét vagy a karakterlánc utolsó karakterét |#last] | `length` | [egy karakterlánc vagy tömb hosszát adja vissza |#length] +| `localDate` | [A dátum és az idő formázása a helyi beállításoknak megfelelően |#localDate] | `number` | [formázza a számot |#number] | `padLeft` | [balról balra kiegészíti a karakterláncot a megadott hosszúságúra |#padLeft] | `padRight` | [a stringet jobbról a megadott hosszúságra egészíti ki |#padRight] @@ -168,7 +169,7 @@ HTML-sorszünetet illeszt be minden újsor előtt. bytes(int precision = 2) .[filter] ---------------------------------- -Bájtban megadott méretet formázza ember által olvashatóvá. +A bájtokban megadott méretet ember által olvasható formába formázza. Ha a [nyelvi tartomány |develop#locale] be van állítva, akkor a megfelelő tizedes és ezres elválasztójeleket használja. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ PHP-bővítményt igényel: `fileinfo`. date(string format) .[filter] ----------------------------- -Visszaad egy dátumot a megadott formátumban a [php:strftime] vagy [php:date] PHP függvények opcióinak használatával. A szűrő a dátumot UNIX időbélyegként, stringként vagy a `DateTime` típusú objektumként kapja meg. +A dátumot és az időt a [php:date] PHP-funkció által használt maszknak megfelelően formázza. A szűrő elfogadja a dátumot UNIX időbélyeg formátumban, sztringként vagy `DateTimeInterface` objektumként. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Lásd még [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Egy karakterlánc vagy tömb hosszát adja vissza. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +A dátum és az idő formázása a [nyelvterületnek |develop#locale] megfelelően, így biztosítva az időadatok konzisztens és lokalizált megjelenítését a különböző nyelveken és régiókban. A szűrő a dátumot UNIX időbélyegként, stringként vagy `DateTimeInterface` objektumként fogadja el. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Ha a szűrőt paraméterek nélkül használja, akkor a dátumot hosszú formátumban adja ki, ahogyan azt a továbbiakban kifejtjük. + +**a) A formátum használata** + +A `format` paraméter leírja, hogy mely időösszetevőket kell megjeleníteni. Betűkódokat használ, ahol az ismétlések száma befolyásolja a kimenet szélességét: + +| Év | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Hónap | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `aug.` / `augusztus` +| Nap | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `V` / `vasárnap` +| Hour | `j` / `H` / `h` | preferred / 24-hour / 12-hour +| Perc | `m` / `mm` | `5` / `05` (2 számjegy, ha másodpercekkel kombinálják) +| Másodperc | `s` / `ss` | `8` / `08` (2 számjegy, ha percekkel kombinálva) + +A kódok sorrendje a formátumban nem számít, mivel az összetevők sorrendje a helyi konvencióknak megfelelően jelenik meg. Ezért a formátum helytől független. Például a `yyyyMMMMd` formátum a `en_US` nyelvjárásban a `April 15, 2024`, míg a `cs_CZ` nyelvjárásban a `15. dubna 2024` formátumot adja ki: + +| locale: | hu-HU | en_US +|--- +| `format: 'dMy'` | 2024. 08. 10. | 8/10/2024 +| `format: 'yM'` | 2024. 8. | 8/2024 +| `format: 'yyyyMMMM'` | 2024. augusztus | August 2024 +| `format: 'MMMM'` | augusztus | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | du. 5:54 | 5:54 PM + + +**b) Előre beállított stílusok használata** + +A `date` és a `time` paraméterek határozzák meg a dátum és az idő megjelenítésének részletességét. Több szint közül választhat: `full`, `long`, `medium`, `short`. Megjelenítheti csak a dátumot, csak az időt vagy mindkettőt: + +| locale: | hu-HU | en_US +|--- +| `date: short` | 1978. 01. 23. | 1/23/78 +| `date: medium` | 1978. jan. 23. | Jan 23, 1978 +| `date: long` | 1978. január 23. | January 23, 1978 +| `date: full` | 1978. január 23., hétfő | Monday, January 23, 1978 +| `time: short` | 8:30 | 8:30 AM +| `time: medium` | 8:30:59 | 8:30:59 AM +| `time: long` | 8:30:59 CET | 8:30:59 AM GMT+1 +| `date: short, time: short` | 1978. 01. 23. 8:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 1978. jan. 23. 8:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 1978. január 23. 8:30 | January 23, 1978 at 8:30 AM + +A dátumhoz használhatja a `relative-` előtagot is (pl. `relative-short`), amely a jelenhez közeli dátumok esetében a `yesterday`, `today` vagy `tomorrow`, egyébként a szokásos módon jelenik meg. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Lásd még [dátum |#date]. + + lower .[filter] --------------- Egy értéket kisbetűvé alakít. PHP-bővítményt igényel `mbstring`. @@ -475,7 +539,7 @@ A `noescape` szűrő visszaélése XSS sebezhetőséghez vezethet! Soha ne haszn number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Egy számot adott számú tizedesjegyig formáz. Megadhatja a tizedesvessző és az ezres elválasztó karakterét is. +Egy számot a megadott számú tizedesjegyig formáz. Ha a [nyelvi terület |develop#locale] be van állítva, akkor a megfelelő tizedes és ezres elválasztójeleket használja. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Egy számot adott számú tizedesjegyig formáz. Megadhatja a tizedesvessző és ``` +number(string format) .[filter] +------------------------------- +A `format` paraméter lehetővé teszi, hogy a számok megjelenését pontosan az Ön igényei szerint határozza meg. Beállított [nyelvterületet |develop#locale] igényel. A formátum több speciális karakterből áll, amelyek teljes leírása a "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns dokumentációban található: + +- kötelező számjegy, mindig megjelenik, még akkor is, ha nulla. +- `#` opcionális számjegy, csak akkor jelenik meg, ha a számnak van számjegye az adott helyen. +- `@` szignifikáns számjegy, segít a számot bizonyos számú szignifikáns számjeggyel megjeleníteni. +- `.` a tizedesvessző helyét jelöli (vessző vagy pont, a területi adattól függően). +- `,` számjegycsoportok, általában ezrek elválasztására szolgál. +- `%` megszorozza a számot 100-zal, és hozzáadja a százalékjelet. + +Nézzünk néhány példát. Az első példában a két tizedesjegy kötelező, a másodikban opcionális. A harmadik példa mindkét oldalon nullákkal való kitöltést mutat, a negyedik példa pedig csak a meglévő számjegyeket jeleníti meg: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +A szignifikáns számjegyek határozzák meg, hogy a tizedesvesszőtől függetlenül hány számjegyet kell megjeleníteni, szükség esetén kerekítve a számot: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Egy szám százalékban történő megjelenítésének egyszerű módja. A számot megszorozzuk 100-zal, és hozzáadjuk a `%` jelet: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +A pozitív és negatív számok számára eltérő formátumot határozhatunk meg, amelyet egy `;` karakterrel választunk el. Így például a pozitív számok a `+` jellel jeleníthetők meg: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Ne feledje, hogy a számok tényleges megjelenése a helyi beállításoktól függően változhat. Egyes országokban például pont helyett vesszőt használnak tizedesválasztóként. Ez a szűrő automatikusan figyelembe veszi ezt, így nem kell aggódnia emiatt. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Egy adott hosszúságú karakterláncot balról egy másik karakterlánccal kitölti. @@ -615,7 +727,7 @@ A Filter alapértelmezés szerint átrendezi és visszaállítja az integer töm sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -A szűrő egy tömb vagy iterátor elemeinek rendezésére szolgál, miközben megőrzi az asszociációs kulcsokat: +A szűrő egy tömb vagy iterátor elemeit rendezi, miközben megőrzi az asszociatív kulcsokat. Ha egy [területi |develop#locale] beállítás van megadva, a rendezés annak szabályait követi, kivéve, ha egyéni összehasonlító függvény van megadva. ```latte {foreach ($names|sort) as $name} diff --git a/latte/it/develop.texy b/latte/it/develop.texy index 39e2d89dab..4ef1b775b2 100644 --- a/latte/it/develop.texy +++ b/latte/it/develop.texy @@ -166,6 +166,22 @@ try { ``` +Locale .[#toc-locale]{data-version:3.0.18} +========================================== + +Latte consente di impostare il locale, che influisce sulla formattazione di numeri, date e ordinamenti. Viene impostato con il metodo `setLocale()`. L'identificatore di locale segue lo standard IETF per i tag di lingua, che utilizza l'estensione PHP `intl`. È composto da un codice di lingua ed eventualmente da un codice di paese, ad esempio `en_US` per l'inglese negli Stati Uniti, `de_DE` per il tedesco in Germania, ecc. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +L'impostazione del locale influisce sui filtri [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] e [bytes |filters#bytes]. + +.[note] +Richiede l'estensione PHP `intl`. L'impostazione di Latte non influisce sull'impostazione globale del locale in PHP. + + Modalità rigorosa .[#toc-strict-mode]{data-version:3.0.8} ========================================================= diff --git a/latte/it/filters.texy b/latte/it/filters.texy index 67b0beca50..8b10d13d53 100644 --- a/latte/it/filters.texy +++ b/latte/it/filters.texy @@ -11,7 +11,7 @@ I filtri sono funzioni che modificano o formattano i dati nella forma desiderata | `bytes` | [Formatta la dimensione in byte |#bytes] | `clamp` | [blocca il valore all'intervallo |#clamp] | `dataStream` | [Conversione del protocollo URI dei dati |#datastream] -| `date` | [formatta la data |#date] +| `date` | [formatta la data e l'ora |#date] | `explode` | [divide una stringa in base al delimitatore dato |#explode] | `first` | [restituisce il primo elemento di un array o un carattere di una stringa |#first] | `group` | [raggruppa i dati secondo vari criteri |#group] @@ -20,6 +20,7 @@ I filtri sono funzioni che modificano o formattano i dati nella forma desiderata | `join` | [unisce un array a una stringa |#implode] | `last` | [restituisce l'ultimo elemento di un array o un carattere di una stringa |#last] | `length` | [restituisce la lunghezza di una stringa o di un array |#length] +| `localDate` | [formatta la data e l'ora in base al locale |#localDate] | `number` | [formatta un numero |#number] | `padLeft` | [completa la stringa alla lunghezza data da sinistra |#padLeft] | `padRight` | [completa la stringa alla lunghezza data da destra |#padRight] @@ -168,7 +169,7 @@ Inserisce le interruzioni di riga HTML prima di tutti i newline. bytes(int precision = 2) .[filter] ---------------------------------- -Formatta una dimensione in byte in forma leggibile. +Formatta la dimensione in byte in una forma leggibile. Se il [locale |develop#locale] è impostato, vengono utilizzati i corrispondenti separatori decimali e delle migliaia. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Richiede l'estensione PHP `fileinfo`. date(string format) .[filter] ----------------------------- -Restituisce una data nel formato indicato, utilizzando le opzioni delle funzioni PHP [php:strftime] o [php:date]. Il filtro ottiene una data come timestamp UNIX, una stringa o un oggetto di tipo `DateTime`. +Formatta la data e l'ora secondo la maschera utilizzata dalla funzione PHP [php:date]. Il filtro accetta la data in formato UNIX timestamp, come stringa o come oggetto `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Vedere anche [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Restituisce la lunghezza di una stringa o di un array. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formatta la data e l'ora in base al [locale |develop#locale], garantendo una visualizzazione coerente e localizzata dei dati temporali in diverse lingue e regioni. Il filtro accetta la data come timestamp UNIX, stringa o oggetto `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Se si utilizza il filtro senza alcun parametro, verrà emessa la data nel livello di formato lungo, come spiegato più avanti. + +**a) Utilizzo del formato** + +Il parametro `format` descrive quali componenti dell'ora devono essere visualizzati. Utilizza codici di lettere, il cui numero di ripetizioni influisce sull'ampiezza dell'output: + +| Anno | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Mese | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `ago` / `agosto` +| Giorno | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `dom` / `domenica` +| Ora | `j` / `H` / `h` | preferito / 24 ore / 12 ore +| Minuto | `m` / `mm` | `5` / `05` (2 cifre se combinato con i secondi) +| Secondo | `s` / `ss` | `8` / `08` (2 cifre se combinato con i minuti) + +L'ordine dei codici nel formato non ha importanza, poiché l'ordine dei componenti sarà visualizzato in base alle convenzioni del locale. Pertanto, il formato è indipendente dal locale. Ad esempio, il formato `yyyyMMMMd` nel locale `en_US` produce `April 15, 2024`, mentre nel locale `cs_CZ` produce `15. dubna 2024`: + +| locale: | it-IT | en_US +|--- +| `format: 'dMy'` | 10/8/2024 | 8/10/2024 +| `format: 'yM'` | 8/2024 | 8/2024 +| `format: 'yyyyMMMM'` | agosto 2024 | August 2024 +| `format: 'MMMM'` | agosto | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 PM | 5:54 PM + + +**b) Utilizzo di stili preimpostati** + +I parametri `date` e `time` determinano il livello di dettaglio della visualizzazione di data e ora. È possibile scegliere tra diversi livelli: `full`, `long`, `medium`, `short`. È possibile visualizzare solo la data, solo l'ora o entrambe: + +| locale: | it-IT | en_US +|--- +| `date: short` | 23/01/78 | 1/23/78 +| `date: medium` | 23 gen 1978 | Jan 23, 1978 +| `date: long` | 23 gennaio 1978 | January 23, 1978 +| `date: full` | lunedì 23 gennaio 1978 | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 CET | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23/01/78, 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 gen 1978, 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 gennaio 1978 alle ore 08:30 | January 23, 1978 at 8:30 AM + +Per la data si può anche usare il prefisso `relative-` (ad esempio, `relative-short`), che per le date vicine al presente visualizzerà `yesterday`, `today`, o `tomorrow`; altrimenti, verrà visualizzato nel modo standard. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Vedere anche [data |#date]. + + lower .[filter] --------------- Converte un valore in minuscolo. Richiede l'estensione PHP `mbstring`. @@ -475,7 +539,7 @@ L'uso improprio del filtro `noescape` può portare a una vulnerabilità XSS! Non number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formatta un numero con un determinato numero di cifre decimali. È anche possibile specificare un carattere del punto decimale e del separatore delle migliaia. +Formatta un numero con un numero specificato di cifre decimali. Se il [locale |develop#locale] è impostato, vengono utilizzati i corrispondenti separatori decimali e delle migliaia. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Formatta un numero con un determinato numero di cifre decimali. È anche possibi ``` +number(string format) .[filter] +------------------------------- +Il parametro `format` consente di definire l'aspetto dei numeri esattamente secondo le proprie esigenze. Richiede un [locale |develop#locale] impostato. Il formato consiste in diversi caratteri speciali, la cui descrizione completa si trova nella documentazione "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- cifra obbligatoria, sempre visualizzata anche se è zero +- `#` cifra opzionale, visualizzata solo se il numero ha una cifra in quel posto +- `@` cifra significativa, aiuta a visualizzare il numero con un certo numero di cifre significative +- `.` segna la posizione del separatore decimale (virgola o punto, a seconda del locale) +- `,` si usa per separare gruppi di cifre, di solito le migliaia +- `%` moltiplica il numero per 100 e aggiunge il segno di percentuale + +Vediamo alcuni esempi. Nel primo esempio, le due cifre decimali sono obbligatorie; nel secondo, sono facoltative. Il terzo esempio mostra un'imbottitura con zeri su entrambi i lati, mentre il quarto visualizza solo le cifre esistenti: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Le cifre significative determinano il numero di cifre da visualizzare, indipendentemente dal punto decimale, arrotondando il numero se necessario: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Un modo semplice per visualizzare un numero come percentuale. Il numero viene moltiplicato per 100 e viene aggiunto il segno `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Possiamo definire un formato diverso per i numeri positivi e negativi, separati da un carattere `;`. In questo modo, ad esempio, i numeri positivi possono essere visualizzati con il segno `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Ricordate che l'aspetto effettivo dei numeri può variare a seconda delle impostazioni locali. Ad esempio, in alcuni Paesi si usa una virgola al posto del punto come separatore decimale. Questo filtro ne tiene conto automaticamente, quindi non è necessario preoccuparsene. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Imbottisce una stringa di una certa lunghezza con un'altra stringa a partire da sinistra. @@ -615,7 +727,7 @@ Per impostazione predefinita, Filter riordina e reimposta le chiavi dell'array d sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Il filtro viene utilizzato per ordinare gli elementi di un array o di un iteratore, preservando le chiavi di associazione: +Il filtro ordina gli elementi di un array o di un iteratore preservandone le chiavi associative. Quando viene impostato un [locale |develop#locale], l'ordinamento segue le sue regole, a meno che non venga specificata una funzione di confronto personalizzata. ```latte {foreach ($names|sort) as $name} diff --git a/latte/ja/develop.texy b/latte/ja/develop.texy index 3a63e03253..4bcca138fe 100644 --- a/latte/ja/develop.texy +++ b/latte/ja/develop.texy @@ -166,6 +166,22 @@ try { }``` +ロケール .[#toc-locale]{data-version:3.0.18} +======================================== + +Latteではロケールを設定することができます。ロケールは数値、日付、ソートのフォーマットに影響します。ロケールは`setLocale()` 。ロケール識別子は IETF の言語タグ標準に従い、PHP の`intl` 拡張モジュールを使用します。これは、言語コードと場合によっては国コードで構成されます。 たとえば、`en_US` は米国の英語、`de_DE` はドイツのドイツ語といった具合です。 + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +ロケールの設定は、フィルタ[localDate |filters#localDate]、[sort |filters#sort]、[number |filters#number] および[bytes |filters#bytes] に影響します。 + +.[note] +PHP の`intl` 拡張モジュールが必要です。Latte での設定は、PHP のグローバルロケール設定には影響しません。 + + ストリクトモード .[#toc-strict-mode]{data-version:3.0.8} ================================================ diff --git a/latte/ja/filters.texy b/latte/ja/filters.texy index 73f987a0c5..5b79b19ecf 100644 --- a/latte/ja/filters.texy +++ b/latte/ja/filters.texy @@ -11,7 +11,7 @@ |`bytes` | [サイズをバイト単位でフォーマットする|#bytes] |`clamp` | [値を範囲にクランプする|#clamp] |`dataStream` | [データ URI プロトコル変換 |#datastream] -|`date` | [日付の書式設定|#date] +|`date` | [日付と時刻をフォーマットする |#date] |`explode` | [与えられたデリミターで文字列を分割する|#explode] |`first` | [配列の最初の要素または文字列の文字を返します |#first] |`group` | [様々な基準に従ってデータをグループ 化する|#group] @@ -20,6 +20,7 @@ |`join` | [配列と 文字列を結合します|#implode] |`last` | 配列の[最後の要素または文字列の文字を返します|#last] |`length` | [文字列または配列の長さを返す|#length] +|`localDate` | [日付と時刻をロケールにしたがってフォーマットする。 |#localDate] |`number` | [数値をフォーマットする|#number] |`padLeft` | [左から指定された長さまで文字列を伸ばします|#padLeft] |`padRight` | 右[から指定 された長さまで文字列を補完する|#padRight] @@ -168,7 +169,7 @@ breakLines .[filter] bytes(int precision = 2) .[filter] ---------------------------------- -バイト単位のサイズを人間が読みやすい形に整形する。 +バイト単位のサイズを人間が読める形に整形する。[ロケールが |develop#locale]設定されている場合は、対応する10進数と1000のセパレータが使用される。 ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ PHP 拡張機能が必要です`fileinfo`. date(string format) .[filter] ----------------------------- -[php:strftime] あるいは[php:date] の PHP 関数のオプションを使用して、指定した書式で日付を返します。フィルタは、UNIXタイムスタンプ、文字列、あるいは`DateTime` 型のオブジェクトとして日付を取得します。 +PHP の関数[php:date] で使われるマスクに従って、日付と時刻をフォーマットします。このフィルタは、UNIX タイムスタンプ形式、文字列、あるいは`DateTimeInterface` オブジェクトとして日付を受け取ります。 ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +[localDateも |#localDate]参照のこと。 + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ length .[filter] ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +[ロケールにしたがって |develop#locale]日付と時刻をフォーマットし、異なる言語や地域間で時刻データの一貫したローカライズされた表示を保証します。このフィルタは、UNIXタイムスタンプ、文字列、`DateTimeInterface` オブジェクトとして日付を受け付けます。 + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +このフィルターをパラメーターなしで使用すると、後で説明するように、長い書式レベルの日付が出力される。 + +**a) フォーマットの使用** + +`format` パラメーターはどの時間要素を表示するかを指定します。これは文字コードを使用し、繰り返しの数が出力の幅に影響します： + +| 年|`y` /`yy` /`yyyy` |`2024` / `24` / `2024` +| 月|`M` /`MM` /`MMM` /`MMMM` | `8` / `08` / `8月` / `8月` +| 日| `d` /`dd` /`E` /`EEEE` |`1` /`01` /`Sun` / `Sunday` +| 時間|`j` /`H` /`h` |希望｜24時間｜12時間 +| 分|`m` /`mm` |`5` /`05` (秒と組み合わせる場合は2桁) +| 秒 |`s` /`ss` |`8` /`08` (分と組み合わせた場合は2桁) + +構成要素の順序はロケールの規約に従って表示されるため、フォーマット内のコードの順序は問題ではない。したがって、書式はロケールに依存しない。たとえば、`en_US` ロケールでは`yyyyMMMMd` という書式は`April 15, 2024` を出力しますが、`cs_CZ` ロケールでは`15. dubna 2024` を出力します： + +| locale: | ja-JP | en_US +|--- +| `format: 'dMy'` | 2024/8/10 | 8/10/2024 +| `format: 'yM'` | 2024/8 | 8/2024 +| `format: 'yyyyMMMM'` | 2024年8月 | August 2024 +| `format: 'MMMM'` | 8月 | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 午後5:54 | 5:54 PM + + +**b) プリセットスタイルの使用** + +`date` と`time` パラメータは、日付と時刻表示の詳細レベルを決定します。いくつかのレベルから選択できます：`full` `long`,`medium`,`short` 。日付のみ、時刻のみ、または両方を表示することができます： + +| locale: | ja-JP | en_US +|--- +| `date: short` | 1978/01/23 | 1/23/78 +| `date: medium` | 1978/01/23 | Jan 23, 1978 +| `date: long` | 1978年1月23日 | January 23, 1978 +| `date: full` | 1978年1月23日月曜日 | Monday, January 23, 1978 +| `time: short` | 8:30 | 8:30 AM +| `time: medium` | 8:30:59 | 8:30:59 AM +| `time: long` | 8:30:59 GMT+1 | 8:30:59 AM GMT+1 +| `date: short, time: short` | 1978/01/23 8:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 1978/01/23 8:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 1978年1月23日 8:30 | January 23, 1978 at 8:30 AM + +日付には接頭辞`relative-` （例：`relative-short` ）を使うこともでき、現在に近い日付の場合は`yesterday` 、`today` 、`tomorrow` と表示される。それ以外の場合は標準的な方法で表示される。 + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +[日付も |#date]参照。 + + lower .[filter] --------------- 値を小文字に変換します。PHP 拡張モジュール`mbstring` が必要です。 @@ -475,7 +539,7 @@ Unescaped: hello number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -数値を小数点以下の桁数で表示します。また、小数点、桁区切りの文字も指定できます。 +指定した小数点以下の桁数で数値をフォーマットする。[ロケールが |develop#locale]設定されている場合は、対応する小数点以下の桁区切り文字が使用される。 ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[fil ``` +number(string format) .[filter] +------------------------------- +`format` パラメータを使用すると、ニーズに合わせて数字の外観を正確に定義することができる。これには[ロケールが |develop#locale]必要である。この書式はいくつかの特殊文字で構成されており、その完全な説明は"DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patternsドキュメントにあります： + +- 必須桁。ゼロであっても常に表示される。 +-`#` オプションの桁。数字がその位置に数字を持つ場合のみ表示される。 +-`@` 有意桁。有効桁数を指定して数値を表示するのに役立ちます。 +-`.` 小数点の区切り位置を示すマーク（ロケールによってカンマまたはドット）。 +-`,` 数桁のグループ（通常は数千）を区切るために使用します。 +-`%` 数値に100を掛け、パーセント記号を加える。 + +いくつかの例を見てみよう。最初の例では小数点以下2桁は必須であり、2番目の例では任意である。3つ目の例では両脇にゼロを含むパディングが表示され、4つ目の例では既存の桁のみが表示されます： + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +有効数字は、小数点以下の桁数に関係なく、何桁表示するかを決定し、必要であれば四捨五入する： + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +数値をパーセント表示する簡単な方法。数値を100倍し、`%` の記号を加える： + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +正の数と負の数について、`;` 文字で区切った異なる書式を定義することができる。こうすることで、例えば正の数を`+` 記号で表示することができる： + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +数字の実際の見た目は、ロケールの設定によって異なる可能性があることを覚えておいてください。例えば、ある国では小数点以下の区切り文字としてドットの代わりにカンマが使われます。このフィルターは自動的にこれを考慮しますので、心配する必要はありません。 + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- 指定された長さの文字列を、左から別の文字列で埋め尽くします。 @@ -615,7 +727,7 @@ Filter は、デフォルトで整数配列のキーを並べ替え、リセッ sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -フィルタは、配列やイテレータの要素を、関連キーを保持したままソートするために使用します： +フィルタは、配列やイテレータの要素を連想キーを保持したままソートします。[ロケールが |develop#locale]設定されている場合は、独自の比較関数が指定されていない限り その規則に従います。 ```latte {foreach ($names|sort) as $name} diff --git a/latte/pl/develop.texy b/latte/pl/develop.texy index 99c9975f81..353a90b36e 100644 --- a/latte/pl/develop.texy +++ b/latte/pl/develop.texy @@ -166,6 +166,22 @@ try { ``` +Lokalizacja .[#toc-locale]{data-version:3.0.18} +=============================================== + +Latte pozwala ustawić ustawienia regionalne, które wpływają na formatowanie liczb, dat i sortowanie. Jest on ustawiany przy użyciu metody `setLocale()`. Identyfikator ustawień regionalnych jest zgodny ze standardem znaczników językowych IETF, który wykorzystuje rozszerzenie PHP `intl`. Składa się z kodu języka i ewentualnie kodu kraju, na przykład `en_US` dla języka angielskiego w Stanach Zjednoczonych, `de_DE` dla języka niemieckiego w Niemczech itp. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Ustawienie locale wpływa na filtry [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] i [bytes |filters#bytes]. + +.[note] +Wymaga rozszerzenia PHP `intl`. Ustawienie w Latte nie wpływa na globalne ustawienie locale w PHP. + + Tryb ścisły .[#toc-strict-mode]{data-version:3.0.8} =================================================== diff --git a/latte/pl/filters.texy b/latte/pl/filters.texy index 6f454ab7cd..378e117c94 100644 --- a/latte/pl/filters.texy +++ b/latte/pl/filters.texy @@ -11,7 +11,7 @@ Możemy używać funkcji w szablonach, aby pomóc w edycji lub przeformatowaniu | `bytes` | [rozmiar formatu w bajtach |#bytes] | `clamp` | [ogranicza wartość do podanego zakresu |#clamp] | `dataStream` | [konwersja dla protokołu Data URI |#dataStream] -| `date` | [formatuje datę |#date] +| `date` | [formatuje datę i godzinę |#date] | `explode` | [dzieli łańcuch na pola zgodnie z delimiterem |#explode] | `first` | [zwraca pierwszy element tablicy lub znak łańcucha|#first] | `group` | [grupuje dane według różnych kryteriów |#group] @@ -20,6 +20,7 @@ Możemy używać funkcji w szablonach, aby pomóc w edycji lub przeformatowaniu | `join` | [konkatenuje tablicę w ciąg znaków|#implode] | `last` | [zwraca ostatni element tablicy lub znak łańcucha|#last] | `length` | [zwraca długość łańcucha w znakach lub tablicy |#length] +| `localDate` | [formatuje datę i godzinę zgodnie z ustawieniami regionalnymi |#localDate] | `number` | [formatuje liczbę |#number] | `padLeft` | [uzupełnia ciąg od lewej do pożądanej długości |#padLeft] | `padRight` | [uzupełnia ciąg od prawej do pożądanej długości |#padRight] @@ -168,7 +169,7 @@ Wstawia podziały linii HTML przed wszystkimi liniami nowymi. bytes(int precision = 2) .[filter] ---------------------------------- -Formatuje rozmiar w bajtach do postaci czytelnej dla człowieka. +Formatuje rozmiar w bajtach do postaci czytelnej dla człowieka. Jeśli ustawione są [ustawienia regionalne |develop#locale], używane są odpowiednie separatory dziesiętne i tysięczne. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Wymaga rozszerzenia PHP `fileinfo`. date(string format) .[filter] ----------------------------- -Zwraca datę w podanym formacie przy użyciu opcji funkcji PHP [php:strftime] lub [php:date]. Filtr pobiera datę jako timestamp UNIX, łańcuch znaków lub obiekt typu `DateTime`. +Formatuje datę i godzinę zgodnie z maską używaną przez funkcję PHP [php:date]. Filtr akceptuje datę w formacie znacznika czasu UNIX, jako ciąg znaków lub jako obiekt `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Zobacz także [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Zwraca długość łańcucha lub tablicy. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formatuje datę i godzinę zgodnie z [ustawieniami regionalnymi |develop#locale], zapewniając spójne i zlokalizowane wyświetlanie danych czasu w różnych językach i regionach. Filtr akceptuje datę jako znacznik czasu UNIX, ciąg znaków lub obiekt `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Jeśli użyjesz filtra bez żadnych parametrów, wyświetli on datę w długim formacie, jak wyjaśniono dalej. + +**a) Użycie formatu** + +Parametr `format` opisuje, które składniki czasu powinny być wyświetlane. Używa kodów literowych, gdzie liczba powtórzeń wpływa na szerokość wyjścia: + +| Rok | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Miesiąc | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `sie` / `sierpień` +| Dzień | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `niedz.` / `niedziela` +| Godzina | `j` / `H` / `h` | preferowana / 24-godzinna / 12-godzinna +| Minuta | `m` / `mm` | `5` / `05` (2 cyfry w połączeniu z sekundami) +| Sekunda | `s` / `ss` | `8` / `08` (2 cyfry w połączeniu z minutami) + +Kolejność kodów w formacie nie ma znaczenia, ponieważ kolejność komponentów będzie wyświetlana zgodnie z konwencjami regionalnymi. Dlatego format jest niezależny od ustawień regionalnych. Na przykład, format `yyyyMMMMd` w locale `en_US` wyświetla `April 15, 2024`, podczas gdy w locale `cs_CZ` wyświetla `15. dubna 2024`: + +| locale: | pl-PL | en_US +|--- +| `format: 'dMy'` | 10.08.2024 | 8/10/2024 +| `format: 'yM'` | 08.2024 | 8/2024 +| `format: 'yyyyMMMM'` | sierpień 2024 | August 2024 +| `format: 'MMMM'` | sierpień | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 PM | 5:54 PM + + +**b) Korzystanie z gotowych stylów** + +Parametry `date` i `time` określają poziom szczegółowości wyświetlania daty i godziny. Można wybrać jeden z kilku poziomów: `full`, `long`, `medium`, `short`. Można wyświetlać tylko datę, tylko godzinę lub obie te wartości: + +| locale: | pl-PL | en_US +|--- +| `date: short` | 23.01.1978 | 1/23/78 +| `date: medium` | 23 sty 1978 | Jan 23, 1978 +| `date: long` | 23 stycznia 1978 | January 23, 1978 +| `date: full` | poniedziałek, 23 stycznia 1978 | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 CET | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.1978, 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 sty 1978, 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 stycznia 1978 08:30 | January 23, 1978 at 8:30 AM + +W przypadku daty można również użyć prefiksu `relative-` (np. `relative-short`), co w przypadku dat bliskich teraźniejszości spowoduje wyświetlenie `yesterday`, `today` lub `tomorrow`; w przeciwnym razie zostanie wyświetlony w standardowy sposób. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Zobacz też [data |#date]. + + lower .[filter] --------------- Konwertuje wartość na małe litery. Wymaga rozszerzenia PHP `mbstring`. @@ -475,7 +539,7 @@ Niewłaściwe użycie filtra `noescape` może prowadzić do luki XSS! Nigdy nie number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formatuje liczbę do podanej liczby miejsc dziesiętnych. Można również określić znak kropki dziesiętnej i separatora tysięcy. +Formatuje liczbę do określonej liczby miejsc dziesiętnych. Jeśli ustawione są [ustawienia regionalne |develop#locale], używane są odpowiednie separatory dziesiętne i tysięczne. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Formatuje liczbę do podanej liczby miejsc dziesiętnych. Można również okre ``` +number(string format) .[filter] +------------------------------- +Parametr `format` pozwala zdefiniować wygląd liczb dokładnie według własnych potrzeb. Wymaga ustawionych [ustawień regionalnych |develop#locale]. Format składa się z kilku znaków specjalnych, których pełny opis można znaleźć w dokumentacji "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- cyfra obowiązkowa, wyświetlana zawsze, nawet jeśli jest zerem +- `#` cyfra opcjonalna, wyświetlana tylko wtedy, gdy liczba ma cyfrę w tym miejscu +- `@` cyfra znacząca, pomaga wyświetlić liczbę z określoną liczbą cyfr znaczących +- `.` oznacza miejsce, w którym powinien znajdować się separator dziesiętny (przecinek lub kropka, w zależności od ustawień regionalnych) +- `,` używany do oddzielania grup cyfr, zwykle tysięcy +- `%` mnoży liczbę przez 100 i dodaje znak procentu + +Przyjrzyjmy się kilku przykładom. W pierwszym przykładzie dwa miejsca po przecinku są obowiązkowe; w drugim są opcjonalne. Trzeci przykład pokazuje wypełnianie zerami po obu stronach, a czwarty wyświetla tylko istniejące cyfry: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Znaczące cyfry określają, ile cyfr, niezależnie od przecinka dziesiętnego, powinno być wyświetlanych, zaokrąglając liczbę w razie potrzeby: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Prosty sposób wyświetlania liczby jako procentu. Liczba jest mnożona przez 100 i dodawany jest znak `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Możemy zdefiniować inny format dla liczb dodatnich i ujemnych, oddzielonych znakiem `;`. W ten sposób, na przykład, liczby dodatnie mogą być wyświetlane ze znakiem `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Należy pamiętać, że rzeczywisty wygląd liczb może się różnić w zależności od ustawień regionalnych. Na przykład w niektórych krajach przecinek jest używany zamiast kropki jako separator dziesiętny. Ten filtr automatycznie to uwzględnia, więc nie musisz się tym martwić. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Przekłada łańcuch o określonej długości z innym łańcuchem od lewej. @@ -615,7 +727,7 @@ Filtr domyślnie zmieni kolejność i wyzeruje klucze tablicy liczb całkowitych sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Filtr służy do sortowania elementów w tablicy lub iteratorze przy jednoczesnym zachowaniu kluczy asocjacyjnych: +Filtr sortuje elementy tablicy lub iteratora, zachowując ich klucze asocjacyjne. Gdy ustawione są [ustawienia regionalne |develop#locale], sortowanie odbywa się zgodnie z ich regułami, chyba że określono niestandardową funkcję porównania. ```latte {foreach ($names|sort) as $name} diff --git a/latte/pt/develop.texy b/latte/pt/develop.texy index 85ed5ef920..e2ba521258 100644 --- a/latte/pt/develop.texy +++ b/latte/pt/develop.texy @@ -166,6 +166,22 @@ try { ``` +Local .[#toc-locale]{data-version:3.0.18} +========================================= + +O Latte permite que você defina a localidade, o que afeta a formatação de números, datas e classificação. Ele é definido usando o método `setLocale()`. O identificador de localidade segue o padrão de tag de idioma da IETF, que usa a extensão PHP `intl`. Ele consiste em um código de idioma e possivelmente um código de país, por exemplo, `en_US` para inglês nos Estados Unidos, `de_DE` para alemão na Alemanha, etc. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +A configuração de localidade afeta os filtros [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] e [bytes |filters#bytes]. + +.[note] +Requer a extensão PHP `intl`. A configuração no Latte não afeta a configuração global de localidade no PHP. + + Modo estrito .[#toc-strict-mode]{data-version:3.0.8} ==================================================== diff --git a/latte/pt/filters.texy b/latte/pt/filters.texy index 219f397c21..49e6f334c2 100644 --- a/latte/pt/filters.texy +++ b/latte/pt/filters.texy @@ -11,7 +11,7 @@ Os filtros são funções que mudam ou formatam os dados para um formulário que | `bytes` | [formatos em bytes |#bytes] | `clamp` | [valor dos grampos para a faixa |#clamp] | `dataStream` | [Conversão do protocolo Data URI |#datastream] -| `date` | [formatos data |#date] +| `date` | [formata a data e a hora |#date] | `explode` | [divide um fio pelo delimitador dado |#explode] | `first` | [devolve o primeiro elemento de matriz ou caráter de cadeia |#first] | `group` | [agrupa dados de acordo com vários critérios |#group] @@ -20,6 +20,7 @@ Os filtros são funções que mudam ou formatam os dados para um formulário que | `join` | [junta um conjunto a um cordão |#implode] | `last` | [retorna o último elemento de matriz ou caráter de cadeia |#last] | `length` | [devolve o comprimento de um fio ou matriz |#length] +| `localDate` | [formata a data e a hora de acordo com a localidade |#localDate] | `number` | [número de formatos |#number] | `padLeft` | [completa o cordel a dado comprimento a partir da esquerda |#padLeft] | `padRight` | [completa o cordel a dado comprimento a partir da direita |#padRight] @@ -168,7 +169,7 @@ Insere quebras de linha HTML antes de todas as novas linhas. bytes(int precision = 2) .[filter] ---------------------------------- -Formata um tamanho em bytes de forma legível para o ser humano. +Formata o tamanho em bytes em um formato legível por humanos. Se a [localidade |develop#locale] estiver definida, serão usados os separadores decimais e de milhar correspondentes. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Requer extensão PHP `fileinfo`. date(string format) .[filter] ----------------------------- -Retorna uma data no formato dado usando as opções de [php:strftime] ou [php:date] funções PHP. O filtro recebe uma data como um carimbo de tempo UNIX, uma string ou um objeto do tipo `DateTime`. +Formata a data e a hora de acordo com a máscara usada pela função PHP [php:date]. O filtro aceita a data no formato de carimbo de data/hora do UNIX, como uma cadeia de caracteres ou como um objeto `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Consulte também [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Retorna o comprimento de um fio ou matriz. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formata a data e a hora de acordo com a [localidade |develop#locale], garantindo a exibição consistente e localizada dos dados de hora em diferentes idiomas e regiões. O filtro aceita a data como um carimbo de data/hora UNIX, uma cadeia de caracteres ou um objeto `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Se você usar o filtro sem nenhum parâmetro, ele emitirá a data no nível de formato longo, conforme explicado mais adiante. + +**a) Usando o formato** + +O parâmetro `format` descreve quais componentes de tempo devem ser exibidos. Ele usa códigos de letras, em que o número de repetições afeta a largura da saída: + +| Year | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Mês | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `ago.` / `agosto` +| Dia | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `domingo` / `domingo` +| Hora | `j` / `H` / `h` | preferencial / 24 horas / 12 horas +| Minuto | `m` / `mm` | `5` / `05` (2 dígitos quando combinado com segundos) +| Segundo | `s` / `ss` | `8` / `08` (2 dígitos quando combinados com os minutos) + +A ordem dos códigos no formato não importa, pois a ordem dos componentes será exibida de acordo com as convenções da localidade. Portanto, o formato é independente da localidade. Por exemplo, o formato `yyyyMMMMd` na localidade `en_US` gera `April 15, 2024`, enquanto na localidade `cs_CZ` gera `15. dubna 2024`: + +| locale: | pt-PT | en_US +|--- +| `format: 'dMy'` | 10/08/2024 | 8/10/2024 +| `format: 'yM'` | 08/2024 | 8/2024 +| `format: 'yyyyMMMM'` | agosto de 2024 | August 2024 +| `format: 'MMMM'` | agosto | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 da tarde | 5:54 PM + + +**b) Uso de estilos predefinidos** + +Os parâmetros `date` e `time` determinam o nível de detalhe da exibição de data e hora. Você pode escolher entre vários níveis: `full`, `long`, `medium`, `short`. Você pode exibir apenas a data, apenas a hora ou ambas: + +| locale: | pt-PT | en_US +|--- +| `date: short` | 23/01/78 | 1/23/78 +| `date: medium` | 23/01/1978 | Jan 23, 1978 +| `date: long` | 23 de janeiro de 1978 | January 23, 1978 +| `date: full` | segunda-feira, 23 de janeiro de 1978 | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 CET | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23/01/78, 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23/01/1978, 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 de janeiro de 1978 às 08:30 | January 23, 1978 at 8:30 AM + +Para a data, você também pode usar o prefixo `relative-` (por exemplo, `relative-short`), que para datas próximas ao presente exibirá `yesterday`, `today`, ou `tomorrow`; caso contrário, será exibido da maneira padrão. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Consulte também [date |#date]. + + lower .[filter] --------------- Converte um valor para minúsculas. Requer extensão PHP `mbstring`. @@ -475,7 +539,7 @@ O mau uso do filtro `noescape` pode levar a uma vulnerabilidade XSS! Nunca o use number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formata um número para um determinado número de casas decimais. Você também pode especificar um caractere do separador de casas decimais e de milhares. +Formata um número com um número especificado de casas decimais. Se a [localidade |develop#locale] estiver definida, serão usados os separadores decimais e de milhar correspondentes. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Formata um número para um determinado número de casas decimais. Você também ``` +number(string format) .[filter] +------------------------------- +O parâmetro `format` permite que você defina a aparência dos números exatamente de acordo com suas necessidades. Ele requer uma [localidade |develop#locale] definida. O formato consiste em vários caracteres especiais, cuja descrição completa pode ser encontrada na documentação "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- dígito obrigatório, sempre exibido, mesmo que seja zero +- `#` dígito opcional, exibido somente se o número tiver um dígito naquele local +- `@` dígito significativo, ajuda a exibir o número com um determinado número de dígitos significativos +- `.` marca onde o separador decimal deve estar (vírgula ou ponto, dependendo da localidade) +- `,` usado para separar grupos de dígitos, geralmente milhares +- `%` multiplica o número por 100 e adiciona o sinal de porcentagem + +Vamos dar uma olhada em alguns exemplos. No primeiro exemplo, duas casas decimais são obrigatórias; no segundo, são opcionais. O terceiro exemplo mostra o preenchimento com zeros em ambos os lados, e o quarto exibe apenas os dígitos existentes: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Os dígitos significativos determinam quantos dígitos, independentemente do ponto decimal, devem ser exibidos, arredondando o número, se necessário: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Uma maneira fácil de exibir um número como porcentagem. O número é multiplicado por 100 e o sinal `%` é adicionado: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Podemos definir um formato diferente para números positivos e negativos, separados por um caractere `;`. Dessa forma, por exemplo, os números positivos podem ser exibidos com um sinal `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Lembre-se de que a aparência real dos números pode variar de acordo com as configurações de localidade. Por exemplo, em alguns países, uma vírgula é usada em vez de um ponto como separador decimal. Esse filtro considera isso automaticamente, portanto, você não precisa se preocupar com isso. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Coloca um cordel a um certo comprimento com outro cordel da esquerda. @@ -615,7 +727,7 @@ O filtro reordenará e redefinirá as chaves da matriz inteira por padrão. Este sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -O filtro é usado para classificar os elementos em uma matriz ou iterador, preservando as chaves de associação: +O filtro classifica os elementos de uma matriz ou iterador, preservando suas chaves associativas. Quando uma [localidade |develop#locale] é definida, a classificação segue suas regras, a menos que uma função de comparação personalizada seja especificada. ```latte {foreach ($names|sort) as $name} diff --git a/latte/ro/develop.texy b/latte/ro/develop.texy index 9f63037d6a..2be2225225 100644 --- a/latte/ro/develop.texy +++ b/latte/ro/develop.texy @@ -166,6 +166,22 @@ try { ``` +Local .[#toc-locale]{data-version:3.0.18} +========================================= + +Latte vă permite să setați localele, care afectează formatarea numerelor, a datelor și sortarea. Aceasta este setată utilizând metoda `setLocale()`. Identificatorul locale urmează standardul IETF language tag, care utilizează extensia PHP `intl`. Acesta constă dintr-un cod de limbă și, eventual, un cod de țară, de exemplu, `en_US` pentru limba engleză în Statele Unite, `de_DE` pentru limba germană în Germania etc. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Setarea locale afectează filtrele [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] și [bytes |filters#bytes]. + +.[note] +Necesită extensia PHP `intl`. Setarea din Latte nu afectează setarea locală globală din PHP. + + Modul strict .[#toc-strict-mode]{data-version:3.0.8} ==================================================== diff --git a/latte/ro/filters.texy b/latte/ro/filters.texy index 2a4b1df87b..5a0ca9987b 100644 --- a/latte/ro/filters.texy +++ b/latte/ro/filters.texy @@ -11,7 +11,7 @@ Filtrele sunt funcții care modifică sau formatează datele în forma dorită. | `bytes` | [formatează dimensiunea în bytes |#bytes] | `clamp` | [fixează valoarea în intervalul |#clamp] | `dataStream` | [Conversia protocolului URI de date |#datastream] -| `date` | [formatează data |#date] +| `date` | [formatează data și ora |#date] | `explode` | [separă un șir de caractere prin delimitatorul dat |#explode] | `first` | [returnează primul element al unui array sau caracterul unui șir de caractere |#first] | `group` | [grupează datele în funcție de diverse criterii |#group] @@ -20,6 +20,7 @@ Filtrele sunt funcții care modifică sau formatează datele în forma dorită. | `join` | [unește un array cu un șir de caractere|#implode] | `last` | [returnează ultimul element al unui array sau caracter al unui șir de caractere|#last] | `length` | [returnează lungimea unui șir sau a unui array |#length] +| `localDate` | [formatează data și ora în funcție de locale |#localDate] | `number` | [formatează numere |#number] | `padLeft` | [completează șirul de caractere la o lungime dată din stânga |#padLeft] | `padRight` | [completează șirul la lungimea dată dinspre dreapta |#padRight] @@ -168,7 +169,7 @@ Inserează întreruperi de linie HTML înainte de toate liniile noi. bytes(int precision = 2) .[filter] ---------------------------------- -Formatează o dimensiune în bytes în formă lizibilă pentru oameni. +Formatează dimensiunea în octeți într-o formă lizibilă de către om. Dacă este setată [localitatea |develop#locale], sunt utilizate separatoarele corespunzătoare de zecimale și de mii. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Necesită extensia PHP `fileinfo`. date(string format) .[filter] ----------------------------- -Returnează o dată în formatul dat folosind opțiunile funcțiilor PHP [php:strftime] sau [php:date]. Filtrul obține o dată sub forma unui timestamp UNIX, a unui șir de caractere sau a unui obiect de tip `DateTime`. +Formatează data și ora în conformitate cu masca utilizată de funcția PHP [php:date]. Filtrul acceptă data în format UNIX timestamp, ca șir de caractere sau ca obiect `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +A se vedea și [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Returnează lungimea unui șir de caractere sau a unei matrice. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Formatează data și ora în funcție de [locale |develop#locale], asigurând afișarea consecventă și localizată a datelor de timp în diferite limbi și regiuni. Filtrul acceptă data ca timestamp UNIX, șir sau obiect `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Dacă utilizați filtrul fără niciun parametru, acesta va afișa data în format lung, după cum se explică în continuare. + +**a) Utilizarea formatului** + +Parametrul `format` descrie componentele de timp care ar trebui afișate. Acesta utilizează coduri de litere, unde numărul de repetiții afectează lățimea ieșirii: + +| An | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Luna | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `aug.` / `august` +| Zi | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `dum.` / `duminică` +| Ora | `j` / `H` / `h` | preferat / 24 de ore / 12 ore +| Minute | `m` / `mm` | `5` / `05` (2 cifre atunci când sunt combinate cu secundele) +| Second | `s` / `ss` | `8` / `08` (2 cifre atunci când sunt combinate cu minutele) + +Ordinea codurilor în format nu contează, deoarece ordinea componentelor va fi afișată în conformitate cu convențiile locale. Prin urmare, formatul este independent de locale. De exemplu, formatul `yyyyMMMMd` în localul `en_US` afișează `April 15, 2024`, în timp ce în localul `cs_CZ` afișează `15. dubna 2024`: + +| locale: | ro-RO | en_US +|--- +| `format: 'dMy'` | 10.08.2024 | 8/10/2024 +| `format: 'yM'` | 08.2024 | 8/2024 +| `format: 'yyyyMMMM'` | august 2024 | August 2024 +| `format: 'MMMM'` | august | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 p.m. | 5:54 PM + + +**b) Utilizarea stilurilor prestabilite** + +Parametrii `date` și `time` determină nivelul de detaliu pentru afișarea datei și orei. Puteți alege din mai multe niveluri: `full`, `long`, `medium`, `short`. Puteți afișa doar data, doar ora sau ambele: + +| locale: | ro-RO | en_US +|--- +| `date: short` | 23.01.1978 | 1/23/78 +| `date: medium` | 23 ian. 1978 | Jan 23, 1978 +| `date: long` | 23 ianuarie 1978 | January 23, 1978 +| `date: full` | luni, 23 ianuarie 1978 | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 CET | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.1978, 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 ian. 1978, 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 ianuarie 1978 la 08:30 | January 23, 1978 at 8:30 AM + +Pentru dată, puteți utiliza, de asemenea, prefixul `relative-` (de exemplu, `relative-short`), care pentru datele apropiate de prezent va afișa `yesterday`, `today` sau `tomorrow`; în caz contrar, se va afișa în mod standard. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +A se vedea și [data |#date]. + + lower .[filter] --------------- Convertește o valoare în minuscule. Necesită extensia PHP `mbstring`. @@ -475,7 +539,7 @@ Folosirea abuzivă a filtrului `noescape` poate duce la o vulnerabilitate XSS! N number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Formatează un număr cu un anumit număr de zecimale. De asemenea, puteți specifica un caracter al punctului zecimal și al separatorului de mii. +Formatează un număr la un număr specificat de zecimale. Dacă este setată [localitatea |develop#locale], se utilizează separatoarele de zecimale și de mii corespunzătoare. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Formatează un număr cu un anumit număr de zecimale. De asemenea, puteți spec ``` +number(string format) .[filter] +------------------------------- +Parametrul `format` vă permite să definiți aspectul numerelor exact în funcție de nevoile dumneavoastră. Acesta necesită o [localitate |develop#locale] stabilită. Formatul constă din mai multe caractere speciale, a căror descriere completă poate fi găsită în documentația "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- cifră obligatorie, afișată întotdeauna chiar dacă este zero +- `#` cifră opțională, afișată numai dacă numărul are o cifră în acel loc +- `@` cifră semnificativă, ajută la afișarea numărului cu un anumit număr de cifre semnificative +- `.` marchează locul unde ar trebui să fie separatorul zecimal (virgulă sau punct, în funcție de localitate) +- `,` utilizat pentru a separa grupuri de cifre, de obicei mii +- `%` înmulțește numărul cu 100 și adaugă semnul procentului + +Să ne uităm la câteva exemple. În primul exemplu, două zecimale sunt obligatorii; în al doilea, ele sunt opționale. Al treilea exemplu prezintă o umplere cu zerouri pe ambele părți, iar al patrulea afișează doar cifrele existente: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Cifrele semnificative determină câte cifre, indiferent de punctul zecimal, ar trebui afișate, rotunjind numărul dacă este necesar: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +O modalitate ușoară de a afișa un număr ca procent. Numărul este înmulțit cu 100 și se adaugă semnul `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Putem defini un format diferit pentru numerele pozitive și negative, separate de un caracter `;`. În acest fel, de exemplu, numerele pozitive pot fi afișate cu un semn `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Rețineți că aspectul real al numerelor poate varia în funcție de setările locale. De exemplu, în unele țări, se utilizează o virgulă în loc de un punct ca separator zecimal. Acest filtru ține cont automat de acest lucru, deci nu trebuie să vă faceți griji. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Pads un șir de caractere la o anumită lungime cu un alt șir de caractere din stânga. @@ -615,7 +727,7 @@ Filter reordonează și resetează implicit cheile tabloului de numere întregi. sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Filtrul este utilizat pentru a sorta elementele dintr-un array sau iterator, păstrând în același timp cheile de asociere: +Filtrul sortează elementele unui array sau iterator păstrând cheile lor asociative. Atunci când este setată o [localitate |develop#locale], sortarea urmează regulile acesteia, cu excepția cazului în care este specificată o funcție de comparație personalizată. ```latte {foreach ($names|sort) as $name} diff --git a/latte/ru/develop.texy b/latte/ru/develop.texy index bba7e01173..09b576545b 100644 --- a/latte/ru/develop.texy +++ b/latte/ru/develop.texy @@ -166,6 +166,22 @@ try { ``` +Местность .[#toc-locale]{data-version:3.0.18} +============================================= + +Latte позволяет установить локаль, которая влияет на форматирование чисел, дат и сортировку. Она задается с помощью метода `setLocale()`. Идентификатор локали соответствует стандарту языковых тегов IETF, который использует расширение PHP `intl`. Он состоит из кода языка и, возможно, кода страны, например, `en_US` для английского языка в США, `de_DE` для немецкого языка в Германии и т.д. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Настройка локали влияет на фильтры [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] и [bytes |filters#bytes]. + +.[note] +Требуется расширение PHP `intl`. Настройка в Latte не влияет на глобальную настройку локали в PHP. + + Строгий режим .[#toc-strict-mode]{data-version:3.0.8} ===================================================== diff --git a/latte/ru/filters.texy b/latte/ru/filters.texy index 8cfbe5d4e8..a2fe0b2ddf 100644 --- a/latte/ru/filters.texy +++ b/latte/ru/filters.texy @@ -11,7 +11,7 @@ | `bytes` | [форматирует размер в байтах |#bytes] | `clamp` | [ограничивает значение диапазоном |#clamp] | `dataStream` | [преобразование протокола URI данных |#dataStream] -| `date` | [форматирует дату |#date] +| `date` | [Форматирование даты и времени |#date] | `explode` | [разделяет строку по заданному разделителю |#explode] | `first` | [возвращает первый элемент массива или символ строки |#first] | `group` | [группирует данные по различным критериям |#group]. @@ -20,6 +20,7 @@ | `join` | [присоединяет массив к строке |#implode] | `last` | [возвращает последний элемент массива или символ строки |#last] | `length` | [возвращает длину строки или массива |#length] +| `localDate` | [Форматирование даты и времени в соответствии с локалью |#localDate] | `number` | [форматирует число |#number] | `padLeft` | [завершает строку до заданной длины слева |#padLeft] | `padRight` | [завершает строку до заданной длины справа |#padRight] @@ -168,7 +169,7 @@ breakLines .[filter] bytes(int precision = 2) .[filter] ---------------------------------- -Форматирует размер в байтах в человекочитаемую форму. +Форматирует размер в байтах в удобочитаемую форму. Если установлена [локаль |develop#locale], используются соответствующие десятичные и тысячные разделители. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO date(string format) .[filter] ----------------------------- -Возвращает дату в заданном формате, используя опции PHP-функций [php:strftime] или [php:date]. Фильтр получает дату в виде временной метки UNIX, строки или объекта типа `DateTime`. +Форматирует дату и время в соответствии с маской, используемой PHP-функцией [php:date]. Фильтр принимает дату в формате временной метки UNIX, как строку или как объект `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +См. также [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ length .[filter] ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Форматирует дату и время в соответствии с [локалью |develop#locale], обеспечивая последовательное и локализованное отображение данных о времени на разных языках и в разных регионах. Фильтр принимает дату в виде временной метки UNIX, строки или объекта `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Если вы используете фильтр без параметров, он выведет дату в длинном формате, как объясняется далее. + +**а) Использование формата** + +Параметр `format` описывает, какие компоненты времени должны быть отображены. Он использует буквенные коды, причем количество повторений влияет на ширину вывода: + +| Год | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Месяц | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `авг.` / `август` +| День | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `вс` / `воскресенье` +| Час | `j` / `H` / `h` | предпочтительный / 24-часовой / 12-часовой +| Минута | `m` / `mm` | `5` / `05` (2 цифры в сочетании с секундами) +| Second | `s` / `ss` | `8` / `08` (2 цифры в сочетании с минутами) + +Порядок кодов в формате не имеет значения, так как порядок компонентов будет отображаться в соответствии с соглашениями локали. Таким образом, формат не зависит от локали. Например, формат `yyyyMMMMd` в локали `en_US` выводит `April 15, 2024`, а в локали `cs_CZ` - `15. dubna 2024`: + +| locale: | ru-RU | en_US +|--- +| `format: 'dMy'` | 10.08.2024 | 8/10/2024 +| `format: 'yM'` | 08.2024 | 8/2024 +| `format: 'yyyyMMMM'` | август 2024 г. | August 2024 +| `format: 'MMMM'` | август | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 PM | 5:54 PM + + +**б) Использование предустановленных стилей** + +Параметры `date` и `time` определяют уровень детализации отображения даты и времени. Вы можете выбрать один из нескольких уровней: `full`, `long`, `medium`, `short`. Вы можете отображать только дату, только время или и то, и другое: + +| locale: | ru-RU | en_US +|--- +| `date: short` | 23.01.1978 | 1/23/78 +| `date: medium` | 23 янв. 1978 г. | Jan 23, 1978 +| `date: long` | 23 января 1978 г. | January 23, 1978 +| `date: full` | понедельник, 23 января 1978 г. | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 GMT+1 | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.1978, 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 янв. 1978 г., 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 января 1978 г. в 08:30 | January 23, 1978 at 8:30 AM + +Для даты можно также использовать префикс `relative-` (например, `relative-short`), который для дат, близких к текущей, отобразит `yesterday`, `today` или `tomorrow`; в противном случае отображение будет стандартным. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +См. также [дата |#date]. + + lower .[filter] --------------- Преобразует значение в нижний регистр. Требуется расширение PHP `mbstring`. @@ -475,16 +539,64 @@ Unescaped: hello number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Форматирует число до заданного количества знаков после запятой. Можно также указать символ десятичной точки и разделителя тысяч. +Форматирует число с указанным количеством знаков после запятой. Если задана [локаль |develop#locale], используются соответствующие десятичные и тысячные разделители. ```latte -{1234.20 |number} 1,234 -{1234.20 |number:1} 1,234.2 -{1234.20 |number:2} 1,234.20 +{1234.20|number} 1,234 +{1234.20|number:1} 1,234.2 +{1234.20|number:2} 1,234.20 {1234.20 |number:2, ',', ' '} 1 234,20 ``` +number(string format) .[filter] +------------------------------- +Параметр `format` позволяет определить внешний вид чисел в точном соответствии с вашими потребностями. Для его использования требуется установленная [локаль |develop#locale]. Формат состоит из нескольких специальных символов, полное описание которых можно найти в документации "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- обязательная цифра, отображается всегда, даже если она равна нулю +- `#` необязательная цифра, отображается только в том случае, если число имеет цифру на этом месте +- `@` значащая цифра, помогает отобразить число с определенным количеством значащих цифр +- `.` обозначает место, где должен находиться десятичный разделитель (запятая или точка, в зависимости от локали) +- `,` используется для разделения групп цифр, обычно тысяч +- `%` умножает число на 100 и добавляет знак процента + +Давайте рассмотрим несколько примеров. В первом примере два знака после запятой обязательны, во втором - необязательны. В третьем примере показаны прокладки с нулями с обеих сторон, а в четвертом - только существующие цифры: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Значимые цифры определяют, сколько цифр, независимо от десятичной точки, должно быть отображено, при необходимости округляя число: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Простой способ отобразить число в процентах. Число умножается на 100 и добавляется знак `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Мы можем задать разный формат для положительных и отрицательных чисел, разделенных знаком `;`. Таким образом, например, положительные числа могут отображаться со знаком `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Помните, что фактический вид чисел может меняться в зависимости от настроек локали. Например, в некоторых странах вместо точки в качестве десятичного разделителя используется запятая. Данный фильтр автоматически учитывает это, поэтому вам не нужно беспокоиться об этом. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Складывает строку определенной длины с другой строкой слева. @@ -615,7 +727,7 @@ Filter по умолчанию переупорядочивает и сбрас sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Фильтр используется для сортировки элементов в массиве или итераторе с сохранением ключей объединения: +Фильтр сортирует элементы массива или итератора с сохранением их ассоциативных ключей. Если задана [локаль |develop#locale], сортировка выполняется по ее правилам, если не указана пользовательская функция сравнения. ```latte {foreach ($names|sort) as $name} diff --git a/latte/sl/develop.texy b/latte/sl/develop.texy index 7df0221c10..e4dd654ce2 100644 --- a/latte/sl/develop.texy +++ b/latte/sl/develop.texy @@ -166,6 +166,22 @@ try { ``` +Lokacija .[#toc-locale]{data-version:3.0.18} +============================================ + +Latte omogoča nastavitev lokalnega okolja, ki vpliva na oblikovanje številk, datumov in razvrščanje. Nastavlja se z metodo `setLocale()`. Identifikator locale sledi standardu jezikovnih oznak IETF, ki uporablja razširitev PHP `intl`. Sestavljen je iz kode jezika in po možnosti kode države, na primer `en_US` za angleščino v ZDA, `de_DE` za nemščino v Nemčiji itd. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Nastavitev locale vpliva na filtre [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] in [bytes |filters#bytes]. + +.[note] +Zahteva razširitev PHP `intl`. Nastavitev v Latte ne vpliva na globalno nastavitev locale v PHP. + + Strogi način .[#toc-strict-mode]{data-version:3.0.8} ==================================================== diff --git a/latte/sl/filters.texy b/latte/sl/filters.texy index ebb5a86626..ffc1b68e4b 100644 --- a/latte/sl/filters.texy +++ b/latte/sl/filters.texy @@ -11,7 +11,7 @@ Filtri so funkcije, ki spremenijo ali oblikujejo podatke v želeno obliko. To je | `bytes` | [oblikuje velikost v bajtih |#bytes] | `clamp` | [vpne vrednost v območje |#clamp] | `dataStream` | [Pretvorba protokola URI podatkov |#datastream] -| `date` | [oblikuje datum |#date] +| `date` | [oblikovanje datuma in časa |#date] | `explode` | [razdeli niz z danim ločilom |#explode] | `first` | [vrne prvi element polja ali znak niza |#first] | `group` | [združevanje podatkov po različnih merilih |#group] @@ -20,6 +20,7 @@ Filtri so funkcije, ki spremenijo ali oblikujejo podatke v želeno obliko. To je | `join` | [združi polje z nizom |#implode] | `last` | [vrne zadnji element polja ali znak niza |#last] | `length` | [vrne dolžino niza ali polja |#length] +| `localDate` | [oblikovanje datuma in časa v skladu z lokalnim jezikom |#localDate] | `number` | [oblikovanje števila |#number] | `padLeft` | [dopolni niz do dane dolžine z leve |#padLeft] | `padRight` | [dopolni niz do dane dolžine od desne |#padRight] @@ -168,7 +169,7 @@ Pred vse nove vrstice vstavi prelome vrstic HTML. bytes(int precision = 2) .[filter] ---------------------------------- -Oblikuje velikost v bajtih v človeku berljivo obliko. +Oblikuje velikost v bajtih v človeku razumljivo obliko. Če je nastavljen [lokalni jezik, |develop#locale] se uporabijo ustrezna decimalna ločila in ločila v tisočih. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ Zahteva razširitev PHP `fileinfo`. date(string format) .[filter] ----------------------------- -Vrne datum v danem formatu z uporabo možnosti funkcij PHP [php:strftime] ali [php:date]. Filter dobi datum kot časovni žig UNIX, niz ali objekt tipa `DateTime`. +Oblikuje datum in čas v skladu z masko, ki jo uporablja funkcija PHP [php:date]. Filter sprejme datum v obliki časovnega žiga UNIX, kot niz ali kot objekt `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Glej tudi [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Vrne dolžino niza ali polja. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Oblikuje datum in čas glede na [lokalno okolje, |develop#locale] kar zagotavlja dosleden in lokaliziran prikaz časovnih podatkov v različnih jezikih in regijah. Filter sprejme datum kot časovni žig UNIX, niz ali objekt `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Če filter uporabite brez parametrov, bo izpisal datum v dolgem formatu, kot je pojasnjeno v nadaljevanju. + +**a) Uporaba oblike** + +Parameter `format` opisuje, katere časovne komponente je treba prikazati. Uporablja črkovne kode, pri čemer število ponovitev vpliva na širino izpisa: + +| Leto | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Mesec | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `avg.` / `avgust` +| Dan | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `ned.` / `nedelja` +| Ura | `j` / `H` / `h` | prednostno / 24-urno / 12-urno +| Minuta | `m` / `mm` | `5` / `05` (2 števki v kombinaciji s sekundami) +| Sekunda | `s` / `ss` | `8` / `08` (2 števki v kombinaciji z minutami) + +Vrstni red kod v formatu ni pomemben, saj bo vrstni red komponent prikazan v skladu s konvencijami lokalnega okolja. Zato je oblika neodvisna od krajevnega okolja. Na primer, format `yyyyMMMMd` v lokalnem okolju `en_US` prikaže `April 15, 2024`, medtem ko v lokalnem okolju `cs_CZ` prikaže `15. dubna 2024`: + +| locale: | sl-SI | en_US +|--- +| `format: 'dMy'` | 10. 8. 2024 | 8/10/2024 +| `format: 'yM'` | 8/2024 | 8/2024 +| `format: 'yyyyMMMM'` | avgust 2024 | August 2024 +| `format: 'MMMM'` | avgust | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 pop. | 5:54 PM + + +**b) Uporaba prednastavljenih slogov** + +Parametra `date` in `time` določata stopnjo podrobnosti prikaza datuma in časa. Izbirate lahko med več ravnmi: `full`, `long`, `medium`, `short`. Prikažete lahko samo datum, samo čas ali oboje: + +| locale: | sl-SI | en_US +|--- +| `date: short` | 23. 01. 78 | 1/23/78 +| `date: medium` | 23. jan. 1978 | Jan 23, 1978 +| `date: long` | 23. januar 1978 | January 23, 1978 +| `date: full` | ponedeljek, 23. januar 1978 | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 GMT+1 | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23. 01. 78, 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23. jan. 1978, 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23. januar 1978 ob 08:30 | January 23, 1978 at 8:30 AM + +Za datum lahko uporabite tudi predpono `relative-` (npr. `relative-short`), ki za datume blizu sedanjosti prikaže `yesterday`, `today` ali `tomorrow`; sicer se prikaže na standardni način. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Glejte tudi [datum |#date]. + + lower .[filter] --------------- Pretvori vrednost v male črke. Zahteva razširitev PHP `mbstring`. @@ -475,7 +539,7 @@ Zloraba filtra `noescape` lahko privede do ranljivosti XSS! Nikoli ga ne uporabl number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Oblikuje število na določeno število decimalnih mest. Določite lahko tudi znak za decimalno vejico in ločilo tisočic. +Oblikuje število na določeno število decimalnih mest. Če je nastavljen [lokalni jezik, |develop#locale] se uporabijo ustrezna ločila za decimalke in tisočinke. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Oblikuje število na določeno število decimalnih mest. Določite lahko tudi zn ``` +number(string format) .[filter] +------------------------------- +S parametrom `format` lahko videz številk določite točno po svojih potrebah. Zahteva nastavljeno [lokalno okolje |develop#locale]. Oblika je sestavljena iz več posebnih znakov, katerih popoln opis je na voljo v dokumentaciji "DecimalFormat"::https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns + +- obvezna številka, ki je vedno prikazana, tudi če je enaka nič +- `#` neobvezna števka, prikazana samo, če ima število na tem mestu števko +- `@` pomembna števka, pomaga prikazati število z določenim številom pomembnih števk +- `.` označuje, kje mora biti decimalno ločilo (vejica ali pika, odvisno od lokalnega okolja) +- `,` se uporablja za ločevanje skupin številk, običajno tisočic +- `%` pomnoži število s 100 in doda znak odstotka + +Oglejmo si nekaj primerov. V prvem primeru sta dve decimalki obvezni, v drugem pa neobvezni. Tretji primer prikazuje polnilo z ničlami na obeh straneh, četrti pa prikazuje samo obstoječe števke: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Pomembne števke določajo, koliko števk, ne glede na decimalno vejico, naj se prikaže, pri čemer se število po potrebi zaokroži: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Enostaven način za prikaz števila v odstotkih. Število pomnožimo s 100 in dodamo znak `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Za pozitivna in negativna števila, ločena z znakom `;`, lahko določimo drugačno obliko. Tako lahko na primer pozitivna števila prikažemo z znakom `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Ne pozabite, da se dejanski videz številk lahko razlikuje glede na nastavitve lokalnega okolja. V nekaterih državah se na primer namesto pike kot decimalno ločilo uporablja vejica. Ta filter to samodejno upošteva, zato vam ni treba skrbeti za to. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Podaljša niz do določene dolžine z drugim nizom z leve. @@ -615,7 +727,7 @@ Filter bo privzeto spremenil vrstni red in ponastavil ključe celoštevilskega p sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Filter se uporablja za razvrščanje elementov v polju ali iteratorju, pri čemer se ohranijo ključi asociacij: +Filter razvrsti elemente polja ali iteratorja, pri čemer ohrani njihove asociativne ključe. Ko je nastavljen [lokalni jezik, |develop#locale] razvrščanje sledi njegovim pravilom, razen če je določena primerjalna funkcija po meri. ```latte {foreach ($names|sort) as $name} diff --git a/latte/tr/develop.texy b/latte/tr/develop.texy index 89515279b0..6def79178d 100644 --- a/latte/tr/develop.texy +++ b/latte/tr/develop.texy @@ -166,6 +166,22 @@ try { ``` +Yerel .[#toc-locale]{data-version:3.0.18} +========================================= + +Latte, sayıların, tarihlerin ve sıralamanın biçimlendirilmesini etkileyen yerel ayarı ayarlamanıza olanak tanır. `setLocale()` yöntemi kullanılarak ayarlanır. Yerel ayar tanımlayıcısı, PHP `intl` uzantısını kullanan IETF dil etiketi standardını izler. Bir dil kodu ve muhtemelen bir ülke kodundan oluşur, örneğin, ABD'deki İngilizce için `en_US`, Almanya'daki Almanca için `de_DE` vb. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + + [Yerel |filters#localDate] ayar, [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] ve [bytes |filters#bytes] filtrelerini etkiler. + +.[note] +PHP `intl` eklentisini gerektirir. Latte'deki ayar PHP'deki global yerel ayarını etkilemez. + + Sıkı Mod .[#toc-strict-mode]{data-version:3.0.8} ================================================ diff --git a/latte/tr/filters.texy b/latte/tr/filters.texy index efee026bc4..b43086a874 100644 --- a/latte/tr/filters.texy +++ b/latte/tr/filters.texy @@ -11,7 +11,7 @@ Filtreler, verileri istediğimiz biçimde değiştiren veya biçimlendiren işle | `bytes` | [bayt cinsinden biçim boyutu |#bytes] | `clamp` | [değeri aralığa sıkıştırır |#clamp] | `dataStream` | [Veri URI protokol dönüşümü |#datastream] -| `date` | [tarihi biçimlendirir |#date] +| `date` | [tarih ve saati biçimlendirir |#date] | `explode` | [bir dizeyi verilen sınırlayıcıya göre böler |#explode] | `first` | [dizinin ilk elemanını veya karakter dizisini döndürür |#first] | `group` | [verileri çeşitli kriterlere göre gruplar |#group] @@ -20,6 +20,7 @@ Filtreler, verileri istediğimiz biçimde değiştiren veya biçimlendiren işle | `join` | [bir diziyi bir dizeye birleştirir|#implode] | `last` | [dizinin son elemanını veya karakter dizisini döndürür |#last] | `length` | [bir dize veya dizinin uzunluğunu döndürür |#length] +| `localDate` | [tarih ve saati yerel ayara göre biçimlendirir |#localDate] | `number` | [format numarası |#number] | `padLeft` | [dizeyi soldan verilen uzunluğa tamamlar |#padLeft] | `padRight` | [dizeyi sağdan verilen uzunluğa tamamlar |#padRight] @@ -168,7 +169,7 @@ Tüm yeni satırlardan önce HTML satır sonlarını ekler. bytes(int precision = 2) .[filter] ---------------------------------- -Bayt cinsinden bir boyutu insan tarafından okunabilir biçimde biçimlendirir. +Bayt cinsinden boyutu insan tarafından okunabilir bir biçimde biçimlendirir. [Yerel |develop#locale] ayar belirlenmişse, ilgili ondalık ve binlik ayırıcılar kullanılır. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ PHP uzantısı gerektirir `fileinfo`. date(string format) .[filter] ----------------------------- -[php:strftime] veya [php:date] PHP işlevlerinin seçeneklerini kullanarak verilen biçimde bir tarih döndürür. Süzgeç bir tarihi UNIX zaman damgası, bir dizge veya `DateTime` türünde bir nesne olarak alır. +Tarih ve saati [php:date] PHP işlevi tarafından kullanılan maskeye göre biçimlendirir. Süzgeç, tarihi UNIX zaman damgası biçiminde, dize olarak veya `DateTimeInterface` nesnesi olarak kabul eder. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Ayrıca bkz. [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ Bir dize veya dizinin uzunluğunu döndürür. ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Tarih ve saati yerel [ayara |develop#locale] göre biçimlendirerek, zaman verilerinin farklı diller ve bölgeler arasında tutarlı ve yerelleştirilmiş bir şekilde görüntülenmesini sağlar. Filtre, tarihi UNIX zaman damgası, dize veya `DateTimeInterface` nesnesi olarak kabul eder. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Filtreyi herhangi bir parametre olmadan kullanırsanız, daha sonra açıklanacağı gibi tarihi uzun biçim düzeyinde verir. + +**a) Formatı kullanma** + + `format` parametresi hangi zaman bileşenlerinin görüntülenmesi gerektiğini açıklar. Tekrar sayısının çıktının genişliğini etkilediği harf kodlarını kullanır: + +| Yıl | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Ay | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `Ağu` / `Ağustos` +| Gün | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `Paz` / `Pazar` +| Saat | `j` / `H` / `h` | tercih edilen / 24 saat / 12 saat +| Dakika | `m` / `mm` | `5` / `05` (saniye ile birleştirildiğinde 2 hane) +| Saniye | `s` / `ss` | `8` / `08` (dakika ile birleştirildiğinde 2 hane) + +Biçimdeki kodların sırası önemli değildir, çünkü bileşenlerin sırası yerel ayarların kurallarına göre görüntülenecektir. Bu nedenle, biçim yerelden bağımsızdır. Örneğin, `en_US` yerel ayarında `yyyyMMMMd` biçimi `April 15, 2024` çıktısını verirken, `cs_CZ` yerel ayarında `15. dubna 2024` çıktısını verir: + +| locale: | tr-TR | en_US +|--- +| `format: 'dMy'` | 10.08.2024 | 8/10/2024 +| `format: 'yM'` | 08/2024 | 8/2024 +| `format: 'yyyyMMMM'` | Ağustos 2024 | August 2024 +| `format: 'MMMM'` | Ağustos | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | ÖS 5:54 | 5:54 PM + + +**b) Önceden ayarlanmış stilleri kullanma** + + `date` ve `time` parametreleri tarih ve saat gösterimi için ayrıntı düzeyini belirler. Birkaç seviye arasından seçim yapabilirsiniz: `full`, `long`, `medium`, `short`. Sadece tarihi, sadece saati ya da her ikisini birden görüntüleyebilirsiniz: + +| locale: | tr-TR | en_US +|--- +| `date: short` | 23.01.1978 | 1/23/78 +| `date: medium` | 23 Oca 1978 | Jan 23, 1978 +| `date: long` | 23 Ocak 1978 | January 23, 1978 +| `date: full` | 23 Ocak 1978 Pazartesi | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 GMT+1 | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.1978 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 Oca 1978 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 Ocak 1978 08:30 | January 23, 1978 at 8:30 AM + +Tarih için `relative-` önekini de kullanabilirsiniz (örneğin, `relative-short`), bu da günümüze yakın tarihler için `yesterday`, `today` veya `tomorrow` olarak görüntülenir; aksi takdirde standart şekilde görüntülenir. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Ayrıca bkz. [tarih |#date]. + + lower .[filter] --------------- Bir değeri küçük harfe dönüştürür. PHP eklentisi gerektirir `mbstring`. @@ -475,7 +539,7 @@ Unescaped: hello number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Bir sayıyı verilen ondalık basamak sayısına göre biçimlendirir. Ayrıca ondalık nokta ve binlik ayırıcının bir karakterini de belirtebilirsiniz. +Bir sayıyı belirtilen sayıda ondalık basamağa göre biçimlendirir. [Yerel |develop#locale] ayar belirlenmişse, ilgili ondalık ve binlik ayırıcılar kullanılır. ```latte {1234.20 |number} 1,234 @@ -485,6 +549,54 @@ Bir sayıyı verilen ondalık basamak sayısına göre biçimlendirir. Ayrıca o ``` +number(string format) .[filter] +------------------------------- + `format` parametresi, sayıların görünümünü tam olarak ihtiyaçlarınıza göre tanımlamanıza olanak tanır. Ayarlanmış bir [yerel |develop#locale] ayar gerektirir. Biçim, tam açıklamasını "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns belgesinde bulabileceğiniz birkaç özel karakterden oluşur: + +- zorunlu rakam, sıfır olsa bile her zaman görüntülenir +- `#` isteğe bağlı rakam, yalnızca sayının o yerde bir rakamı varsa görüntülenir +- `@` anlamlı hane, sayının belirli sayıda anlamlı hane ile görüntülenmesine yardımcı olur +- `.` ondalık ayırıcının olması gereken yeri işaretler (yerel ayara bağlı olarak virgül veya nokta) +- `,` genellikle binlik rakam gruplarını ayırmak için kullanılır +- `%` sayıyı 100 ile çarpar ve yüzde işaretini ekler + +Şimdi bazı örneklere bakalım. İlk örnekte, iki ondalık basamak zorunludur; ikincisinde ise isteğe bağlıdır. Üçüncü örnekte her iki tarafta da sıfırlarla doldurma gösterilirken, dördüncü örnekte yalnızca mevcut rakamlar görüntülenir: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Önemli basamaklar, ondalık noktadan bağımsız olarak kaç basamağın görüntülenmesi gerektiğini belirler ve gerekirse sayıyı yuvarlar: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Bir sayıyı yüzde olarak görüntülemenin kolay bir yolu. Sayı 100 ile çarpılır ve `%` işareti eklenir: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Pozitif ve negatif sayılar için `;` karakteriyle ayrılmış farklı bir format tanımlayabiliriz. Bu şekilde, örneğin pozitif sayılar bir `+` işaretiyle gösterilebilir: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Sayıların gerçek görünümünün yerel ayarlara bağlı olarak değişebileceğini unutmayın. Örneğin, bazı ülkelerde ondalık ayırıcı olarak nokta yerine virgül kullanılır. Bu filtre bunu otomatik olarak hesaba katar, bu nedenle endişelenmenize gerek yoktur. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Bir dizeyi soldan başka bir dizeyle belirli bir uzunluğa kadar doldurur. @@ -615,7 +727,7 @@ Filtre, varsayılan olarak tamsayı dizi anahtarlarını yeniden sıralar ve sı sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Filtre, ilişkilendirme anahtarlarını koruyarak bir dizi veya yineleyicideki öğeleri sıralamak için kullanılır: +Filtre, bir dizinin veya yineleyicinin öğelerini, ilişkisel anahtarlarını koruyarak sıralar. Bir [yerel |develop#locale] ayarlandığında, özel bir karşılaştırma işlevi belirtilmediği sürece sıralama [yerel |develop#locale] ayarın kurallarını izler. ```latte {foreach ($names|sort) as $name} diff --git a/latte/uk/develop.texy b/latte/uk/develop.texy index a41c7a5d0b..a539136910 100644 --- a/latte/uk/develop.texy +++ b/latte/uk/develop.texy @@ -166,6 +166,22 @@ try { ``` +Локація .[#toc-locale]{data-version:3.0.18} +=========================================== + +Latte дозволяє встановити локаль, яка впливає на форматування чисел, дат і сортування. Вона встановлюється за допомогою методу `setLocale()`. Ідентифікатор локалі відповідає стандарту мовних тегів IETF, який використовує розширення PHP `intl`. Він складається з коду мови і, можливо, коду країни, наприклад, `en_US` для англійської мови в США, `de_DE` для німецької мови в Німеччині тощо. + +```php +$latte = new Latte\Engine; +$latte->setLocale('cs'); +``` + +Параметр локалі впливає на фільтри [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] і [bytes |filters#bytes]. + +.[note] +Потрібне розширення PHP `intl`. Налаштування у Latte не впливає на глобальне налаштування локалі у PHP. + + Суворий режим .[#toc-strict-mode]{data-version:3.0.8} ===================================================== diff --git a/latte/uk/filters.texy b/latte/uk/filters.texy index d3f91111f4..e5146ecc6d 100644 --- a/latte/uk/filters.texy +++ b/latte/uk/filters.texy @@ -11,7 +11,7 @@ | `bytes` | [форматує розмір у байтах |#bytes] | `clamp` | [обмежує значення діапазоном |#clamp] | `dataStream` | [перетворення протоколу URI даних |#dataStream] -| `date` | [форматує дату |#date] +| `date` | [форматує дату та час |#date] | `explode` | [розділяє рядок за заданим роздільником |#explode] | `first` | [повертає перший елемент масиву або символ рядка |#first] | `group` | [групує дані за різними критеріями |#group] @@ -20,6 +20,7 @@ | `join` | [приєднує масив до ряд ка|#implode] | `last` | [повертає останній елемент масиву або символ рядка|#last] | `length` | [повертає довжину рядка або масиву |#length] +| `localDate` | [форматує дату і час відповідно до місцевості |#localDate] | `number` | [форматує число |#number] | `padLeft` | [завершує рядок до заданої довжини зліва |#padLeft] | `padRight` | [завершує рядок до заданої довжини справа |#padRight] @@ -168,7 +169,7 @@ breakLines .[filter] bytes(int precision = 2) .[filter] ---------------------------------- -Форматує розмір у байтах у зручну для читання форму. +Форматує розмір у байтах у зручну для читання форму. Якщо задано [локаль |develop#locale], використовуються відповідні десяткові та тисячні роздільники. ```latte {$size|bytes} 0 B, 1.25 GB, … @@ -255,13 +256,14 @@ AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO date(string format) .[filter] ----------------------------- -Повертає дату в заданому форматі, використовуючи опції функцій PHP [php:strftime] або [php:date]. Фільтр отримує дату у вигляді мітки часу UNIX, рядка або об'єкта типу `DateTime`. +Форматує дату і час відповідно до маски, що використовується функцією PHP [php:date]. Фільтр приймає дату у форматі мітки часу UNIX, як рядок або як об'єкт `DateTimeInterface`. ```latte -{$today|date:'%d.%m.%Y'} {$today|date:'j. n. Y'} ``` +Дивіться також [localDate |#localDate]. + escapeUrl .[filter] ------------------- @@ -418,6 +420,68 @@ length .[filter] ``` +localDate(string format = null, string date = null, string time = null) .[filter] +--------------------------------------------------------------------------------- +Форматує дату і час відповідно до [локалі |develop#locale], забезпечуючи узгоджене і локалізоване відображення часових даних у різних мовах і регіонах. Фільтр приймає дату у вигляді мітки часу UNIX, рядка або об'єкта `DateTimeInterface`. + +```latte +{$date|localDate} {* 15. dubna 2024 *} +{$date|format: yM} {* 4/2024 *} +{$date|localDate: date: medium} {* 15. 4. 2024 *} +``` + +Якщо ви використовуєте фільтр без жодних параметрів, він виведе дату в довгому форматі, як пояснюється далі. + +**a) Використання формату** + +Параметр `format` описує, які компоненти часу слід відображати. Він використовує літерні коди, де кількість повторень впливає на ширину виводу: + +| Рік | `y` / `yy` / `yyyy` | `2024` / `24` / `2024` +| Місяць | `M` / `MM` / `MMM` / `MMMM` | `8` / `08` / `сер` / `серпень` +| День | `d` / `dd` / `E` / `EEEE` | `1` / `01` / `нд` / `неділя` +| Година | `j` / `H` / `h` | бажана / 24-годинна / 12-годинна +| Хвилина | `m` / `mm` | `5` / `05` (2 цифри в поєднанні з секундами) +| Секунда | `s` / `ss` | `8` / `08` (2 цифри у поєднанні з хвилинами) + +Порядок кодів у форматі не має значення, оскільки порядок компонентів буде відображено відповідно до умов локалізації. Таким чином, формат не залежить від локалі. Наприклад, формат `yyyyMMMMd` у локалі `en_US` виводить `April 15, 2024`, тоді як у локалі `cs_CZ` він виводить `15. dubna 2024`: + +| locale: | uk-UA | en_US +|--- +| `format: 'dMy'` | 10.08.2024 | 8/10/2024 +| `format: 'yM'` | 08.2024 | 8/2024 +| `format: 'yyyyMMMM'` | серпень 2024 р. | August 2024 +| `format: 'MMMM'` | серпень | August +| `format: 'jm'` | 17:54 | 5:54 PM +| `format: 'Hm'` | 17:54 | 17:54 +| `format: 'hm'` | 5:54 пп | 5:54 PM + + +**b) Використання попередньо встановлених стилів** + +Параметри `date` і `time` визначають рівень деталізації відображення дати і часу. Ви можете вибрати один з декількох рівнів: `full`, `long`, `medium`, `short`. Ви можете відображати лише дату, лише час або обидва: + +| locale: | uk-UA | en_US +|--- +| `date: short` | 23.01.78 | 1/23/78 +| `date: medium` | 23 січ. 1978 р. | Jan 23, 1978 +| `date: long` | 23 січня 1978 р. | January 23, 1978 +| `date: full` | понеділок, 23 січня 1978 р. | Monday, January 23, 1978 +| `time: short` | 08:30 | 8:30 AM +| `time: medium` | 08:30:59 | 8:30:59 AM +| `time: long` | 08:30:59 GMT+1 | 8:30:59 AM GMT+1 +| `date: short, time: short` | 23.01.78, 08:30 | 1/23/78, 8:30 AM +| `date: medium, time: short` | 23 січ. 1978 р., 08:30 | Jan 23, 1978, 8:30 AM +| `date: long, time: short` | 23 січня 1978 р. о 08:30 | January 23, 1978 at 8:30 AM + +Для дати можна також використовувати префікс `relative-` (наприклад, `relative-short`), який для дат, близьких до теперішнього часу, покаже `yesterday`, `today` або `tomorrow`; в іншому випадку, він буде відображатися стандартним чином. + +```latte +{$date|localDate: date: relative-short} {* yesterday *} +``` + +Див. також [дата |#date]. + + lower .[filter] --------------- Перетворює значення в нижній регістр. Потрібне розширення PHP `mbstring`. @@ -475,16 +539,64 @@ Unescaped: hello number(int decimals = 0, string decPoint = '.', string thousandsSep = ',') .[filter] ------------------------------------------------------------------------------------ -Форматує число до заданої кількості десяткових знаків. Ви також можете вказати символ десяткової крапки та роздільник тисяч. +Форматує число до вказаної кількості десяткових знаків. Якщо задано [локаль |develop#locale], використовуються відповідні роздільники десяткових і тисячних знаків. ```latte -{1234.20 |number} 1,234 +{1234.20|number} 1,234 {1234.20 |number:1} 1,234.2 {1234.20 |number:2} 1,234.20 -{1234.20 |number:2, ',', ' '} 1 234,20 +{1234.20|number:2, ',', ' '} 1 234,20 ``` +number(string format) .[filter] +------------------------------- +Параметр `format` дозволяє визначити зовнішній вигляд чисел точно відповідно до ваших потреб. Для цього потрібна встановлена [локаль |develop#locale]. Формат складається з декількох спеціальних символів, повний опис яких можна знайти в документації "DecimalFormat":https://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns: + +- обов'язкова цифра, завжди відображається, навіть якщо це нуль +- `#` необов'язкова цифра, відображається тільки якщо на цьому місці в числі є цифра +- `@` значуща цифра, допомагає відобразити число з певною кількістю значущих цифр +- `.` позначає, де повинен стояти десятковий роздільник (кома або крапка, залежно від локалі) +- `,` використовується для відокремлення груп цифр, зазвичай тисяч +- `%` множить число на 100 і додає знак відсотків + +Розглянемо кілька прикладів. У першому прикладі два знаки після коми є обов'язковими, у другому - необов'язковими. У третьому прикладі з обох боків додаються нулі, а в четвертому відображаються лише наявні цифри: + +```latte +{1234.5|number: '#,##0.00'} {* 1,234.50 *} +{1234.5|number: '#,##0.##'} {* 1,234.5 *} +{1.23 |number: '000.000'} {* 001.230 *} +{1.2 |number: '##.##'} {* 1.2 *} +``` + +Значущі цифри визначають, скільки цифр, незалежно від десяткової крапки, слід відображати, округлюючи число, якщо це необхідно: + +```latte +{1234|number: '@@'} {* 1200 *} +{1234|number: '@@@'} {* 1230 *} +{1234|number: '@@@#'} {* 1234 *} +{1.2345|number: '@@@'} {* 1.23 *} +{0.00123|number: '@@'} {* 0.0012 *} +``` + +Простий спосіб відобразити число у відсотках. Число множиться на 100 і додається знак `%`: + +```latte +{0.1234|number: '#.##%'} {* 12.34% *} +``` + +Ми можемо визначити різний формат для додатних і від'ємних чисел, розділених символом `;`. Таким чином, наприклад, додатні числа можуть відображатися зі знаком `+`: + +```latte +{42|number: '#.##;(#.##)'} {* 42 *} +{-42|number: '#.##;(#.##)'} {* (42) *} +{42|number: '+#.##;-#.##'} {* +42 *} +{-42|number: '+#.##;-#.##'} {* -42 *} +``` + +Пам'ятайте, що фактичний вигляд чисел може відрізнятися залежно від налаштувань локалі. Наприклад, у деяких країнах замість крапки в якості десяткового роздільника використовується кома. Цей фільтр автоматично враховує це, тому вам не потрібно про це турбуватися. + + padLeft(int length, string pad = ' ') .[filter] ----------------------------------------------- Доповнює рядок до певної довжини іншим рядком зліва. @@ -615,7 +727,7 @@ slice(int start, int length = null, bool preserveKeys = false) .[filter] sort(?Closure comparison, string|int|\Closure|null by=null, string|int|\Closure|bool byKey=false) .[filter] ----------------------------------------------------------------------------------------------------------- -Фільтр використовується для сортування елементів масиву або ітератора зі збереженням ключів асоціацій: +Фільтр сортує елементи масиву або ітератора зі збереженням їхніх асоціативних ключів. Якщо задано [локаль |develop#locale], сортування відбувається за її правилами, якщо не вказано власну функцію порівняння. ```latte {foreach ($names|sort) as $name}