Latte: One Line and Localization Done for You

The key feature of Latte version 3.0.18 is the ability to set the locale. It's just a matter of one line of code:

$latte = new Latte\Engine;
$latte->setLocale('cs_CZ');

With this simple step, all localized filters will respect the Czech locale. You can, of course, use any valid IETF language tag, such as en_US for English in the United States or de_DE for German in Germany.

Setting the locale affects the sort, number, bytes, and the brand new localDate filters.

New Filter |localDate

This filter is a real gem of the new version. It allows you to display dates and times according to local customs. It offers two main ways to use it, covering practically all your needs for formatting time data.

Parameter format

This is a string that allows you to specify exactly how the resulting date should look. It's similar to PHP functions date() or strftime(). But be careful, this format is somewhat magical. It adapts to any language. Let's demonstrate.

{$date|localDate: 'd MMMM yyyy'}

The letters d, M, and y represent the day, month, and year. yyyy indicates that the year should be written in full four-digit form, and similarly, the “long” MMMM indicates the full month name. But what about the order of the day and month? Or the separators? These differ significantly across locales!

Leave that to Latte. You don't need to worry about the order of the day and month or which separators to use. Latte handles all that for you and displays the date correctly:

• In English: August 6, 2024
• In Czech: 6. srpna 2024
• In German: 6. August 2024

As you can see, the format is completely independent of the locale setting. It could actually be written like this: yyyyMMMMd, as the order of symbols and spaces between them does not matter.

Let's look at more examples:

{* year and month *}
{$date|localDate: 'yyyyMMMM'}
{* EN: April 2024, CZ: duben 2024 *}

{* short date format *}
{$date|localDate: 'yMd'}
{* EN: 4/15/2024, CZ: 15. 4. 2024 *}

{* basic time format *}
{$time|localDate: 'jm'}
{* EN: 2:30 PM, CZ: 14:30 *}

{* short format without AM/PM *}
{$time|localDate: 'Hm'}
{* EN: 14:30, CZ: 14:30 *}

You can find a similar description in the localDate filter documentation.

Predefined Templates with date and time

The second way to use the localDate filter offers predefined templates date and time. These act as shortcuts for the most common date and time formats. There are four levels of detail available: full, long, medium, and short. You can combine them or use them separately:

{* date only *}
{$date|localDate: date: short}
{* EN: 4/15/24, CZ: 15.04.2024 *}

{* time only *}
{$date|localDate: time: medium}
{* EN: 2:30:45 PM, CZ: 14:30:45 *}

{* short date and time format *}
{$date|localDate: date: short, time: short}
{* EN: 4/23/24, 2:30 PM, CZ: 23.04.2024 14:30 *}

A bonus is the ability to use the relative- prefix for dates, which outputs relatively close dates as yesterday, today, and tomorrow. This is handy for applications that need to display dates naturally:

{$yesterday|localDate: date: relative-short}
{* Output: yesterday *}

If you call the filter without parameters, it outputs in long date format:

{$date|localDate}
{* EN: April 23, 2024, CZ: 23. dubna 2024 *}

Using the localDate filter for formatting time allows you to create international applications with minimal effort. It's also great if you're creating an application in just one language.

• Automatic adaptation: One format automatically adapts to local customs. You don't need to write conditions for different languages.
• Code readability: Your code remains clean and understandable, no matter how many different locales you support.
• Consistency: Ensures that times are always displayed correctly according to users' expectations in each country.

Filter |number: A Familiar Face with New Tricks

The number filter has been in Latte since the beginning. Its standard behavior remains unchanged and fully backward compatible in the new version. Once you set the locale, it automatically uses national separators for decimal points and thousands:

{* With English (US) locale set *}
{1234.56|number}  {* Output: 1,234.56 *}

{* With Czech locale set *}
{1234.56|number}  {* Output: 1 234,56 *}

And now for the best part – you can customize the appearance of numbers as never before. With a new parameter for number formatting, you gain unprecedented control over how they are displayed. Here are a few examples:

{1234.5|number: '#,##0.00'}     {* 1,234.50 *}
{1234.5|number: '#,##0.##'}     {* 1,234.5 *}
{1234.5|number: '@@'}           {* 1200 *}
{1234.5|number: '@@@'}          {* 1230 *}
{1234.56|number: '#,##0.00 ¤'}  {* 1 234,56 Kč *}

You can find a similar format description in the number filter documentation.

With the number filter, you get the best of both worlds – ease of use and detailed control over number formatting. Whether you're creating an e-shop, a financial application, or anything where numbers are important, this filter will make your work easier and ensure your data always looks professional and is understandable to users worldwide.

Enhancements to |sort and |bytes Filters

These filters have been upgraded in the new Latte version and now fully respect the set locale. The sort filter now sorts according to local rules, which is especially important for languages with diacritics or special characters:

{['Železo', 'Jablko', 'Čaj']|sort}
{* Output in CZ: ['Čaj', 'Jablko', 'Železo'] *}

This ensures that all template data not coming from the database will always be sorted correctly according to user expectations in each country. If this is not desirable, you can pass a different comparison function to the filter.

The bytes filter now automatically uses the correct decimal separator according to the set locale:

{120000|bytes}
{* Output in US: 117.19 KB *}
{* Output in CZ: 117,19 KB *}

How to Start with New Features in Presenters

Implementing these features in your projects is simple and straightforward. The key is setting the correct locale using the setLocale() function. You can set it in presenters like this:

$this->template->getLatte()->setLocale($locale);

For projects that run in only one language, it's more efficient to set the locale globally in the configuration:

latte:
	locale: cs

This setting ensures that all Latte instances used by presenters and components throughout the application will automatically use the Czech locale.

Note: To use these new localization features, you need to have the PHP intl extension installed. Also, using the format in the localDate filter requires PHP 8.1.