13.1. User Culture

All the built-in i18n features in symfony are based on a parameter of the user session called the culture. The culture is the combination of the country and the language of the user, and it determines how the text and culture-dependent information are displayed. Since it is serialized in the user session, the culture is persistent between pages.

13.1.1. Setting the Default Culture

By default, the culture of new users is the default_culture. You can change this setting in the settings.yml configuration file, as shown in Listing 13-1.

Listing 13-1 - Setting the Default Culture, in frontend/config/settings.yml

all:
  .settings:
    default_culture: fr_FR

Keeping both the language and the country in the culture is necessary because you may have a different French translation for users from France, Belgium, or Canada, and a different Spanish content for users from Spain or Mexico. The language is coded in two lowercase characters, according to the ISO 639-1 standard (for instance, en for English). The country is coded in two uppercase characters, according to the ISO 3166-1 standard (for instance, GB for Great Britain).

13.1.2. Changing the Culture for a User

The user culture can be changed during the browsing session — for instance, when a user decides to switch from the English version to the French version of the application, or when a user logs in to the application and uses the language stored in his preferences. That's why the sfUser class offers getter and setter methods for the user culture. Listing 13-2 shows how to use these methods in an action.

Listing 13-2 - Setting and Retrieving the Culture in an Action

// Culture setter
$this->getUser()->setCulture('en_US');

// Culture getter
$culture = $this->getUser()->getCulture();
 => en_US

page:
  url: /:sf_culture/:page
  requirements: { sf_culture: (?:fr|en|de) }
  params: ...

article:
  url: /:sf_culture/:year/:month/:day/:slug
  requirements: { sf_culture: (?:fr|en|de) }
  params: ...

13.1.3. Determining the Culture Automatically

In many applications, the user culture is defined during the first request, based on the browser preferences. Users can define a list of accepted languages in their browser, and this data is sent to the server with each request, in the Accept-Language HTTP header. You can retrieve it in symfony through the sfWebRequest object. For instance, to get the list of preferred languages of a user in an action, type this:

$languages = $request->getLanguages();

The HTTP header is a string, but symfony automatically parses it and converts it into an array. So the preferred language of the user is accessible with $languages[0] in the preceding example.

It can be useful to automatically set the user culture to its preferred browser language in a site home page or in a filter for all pages. But as your website will probably only support a limited set of languages, it's better to use the getPreferredCulture() method. It returns the best language by comparing the user preferred languages and the supported languages:

$language = $request->getPreferredCulture(array('en', 'fr')); // the website is available in English and French

If there is no match, the method returns the first supported language (en in the preceding example).