Templating in practice : Internationalization helpers

Overview

Displaying localized content is not a worry in Symfony thanks to the internationalization helpers. They will transparently process localized content (dates, numbers, currencies) according to the user culture.

Date helpers

Symfony simplifies the display of dates and numbers according to the user culture. For an international website, all dates and numbers should be output through a internationalization filter, and that's what the following helpers do.

All these helpers have a culture argument, which is the last argument and is optional. If omitted, the helper uses the user culture instead. To learn more about cultures and internationalization, read the i18n chapter.

First, declare the need of the helper at the top of your template:

<?php use_helper('Date') ?>

Here are two functions aimed at date and date plus time display:

<?php echo format_date($date) ?>
<?php echo format_date($date, 'd', 'en') ?>
 
<?php echo format_datetime($date) ?>

The second argument is the format, that can be specified either with predefined patterns:

Or directly with the basic keys.

For instance, to display the month with 2 digits and the year with 4, you can write:

<?php echo format_date($date, 'MM/yyyy') ?>

And if you have a date interval, another helper manages all the cases for you:

<?php echo format_daterange($start_date, $end_date, 'MM/yy', 'from %s to %s', 'starting from %s', 'until %s') ?>

The last three arguments specify the text to be used when:

• two dates exist
• only the start date is given
• only the end date is given

The %s are replaced by the formatted dates.

For instance, if $start_date is the 1st of April 2005 and $end_date the 3rd of July 2005, the displayed text will be from 04/05 to 07/05.

Number helpers

It is also possible to format a number:

<?php use_helper('Number') ?>
 
<?php echo format_number(12000.10) ?>
// will generate in HTML for an American user
12,000.10
// will generate in HTML for a French user
12 000,10

To format a monetary amount, use the currency_format function. It takes as optional argument the ISO currency code of your amount.

<?php echo format_currency(12000.10, 'EUR') ?>
// will generate in HTML for an American user
€12,000.10
// will generate in HTML for a French user
12 000,10 €

The last two helpers are here to return a text version of the interval separating two dates:

<?php echo distance_of_time_in_words($from_time, $to_time, $include_seconds = false) ?>
<?php echo time_ago_in_words($from_time, $include_seconds = false) ?>

Country and language names

You will probably need to display country names, for instance in addresses. Country names differ according to the culture (for instance, 'Great Britain' in French is 'Grande-Bretagne'). If the data format is a
two-digit ISO code (like 'GB' for Great-Britain), the country and language helpers do the job for you.

In order to use the internationalization helpers, you must include the I18N helper module.

<?php use_helper('I18N') ?>
 
<?php echo format_country('GB') ?>    
// will generate in HTML for an American user
Great Britain
// will generate in HTML for a French user
Grande-Bretagne
 
<?php echo format_language('EN') ?>    
// will generate in HTML for an American user
English
// will generate in HTML for a French user
anglais

Countries and languages are often displayed in selection lists for data input in forms. If you do so, you shouldn't need the previous helpers since Sensio provides a select_country_tag helper, described in the form helpers chapter.