latte 3.0.18

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}
 ===================================================
 

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` <small>(2 цифри, когато се комбинира със секунди)</small>
+| Секунда | `s` / `ss` | `8` / `08` <small>(2 цифри, когато се комбинират с минути)</small>
+
+Редът на кодовете във формата няма значение, тъй като редът на компонентите ще бъде показан в съответствие с конвенциите на локала. Следователно форматът е независим от локала. Например, форматът `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: <b>hello</b>
 
 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 
+
+- <c id=6/> задължителна цифра, която винаги се показва, дори ако е нула
+- `#` незадължителна цифра, показва се само ако числото има цифра на това място
+- `@` значима цифра, помага за показване на числото с определен брой значими цифри
+- `.` маркира мястото, където трябва да се намира десетичният разделител (запетая или точка, в зависимост от локала)
+- `,` се използва за разделяне на групи от цифри, обикновено хиляди
+- `%` умножава числото по 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}

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}
 ====================================