Cedric SADAI - Consulting en strat?gie Internet

One of the recurring concern when developing an internationalized application, is to not let any element untranslated. This is natively complicated, even with the brand new symfony 1.1. You often end up with untranslated URLs or meta tags. But using the Framework in conjonction with the Yahoo!’s plugin ysfDimensionsPlugin will fill all the blanks you could have experienced once.

The role of the plugin is to let you define specific dimensions (can be cultures, can be themes, etc.), and to make it possible to override any part of your application (actions, templates, config) by simply adding a subdirectory, with the name of your dimension.

Let’s have a quick exemple.

First of all, you will have to link your existing project to the plugin SVN.

svn propedit svn:externals plugins/

Then append to the file:

ysfDimensionsPlugin http://svn.symfony-project.com/plugins/ysfDimensionsPlugin/branches/1.1/

Update everything:

svn up

Configuration

Let’s say we want to internationalize the application in english and french. That means we will add a “culture” dimension with two possibilities in it: en, and fr. To do that, create a /config/dimensions.yml file and write:

allowed:
  culture: [en, fr]

Now, we have to edit the main configuration script, so the plugin can add our brand new configuration levels.

require_once '/path/to/your/project/lib/vendor/symfony/lib/autoload/sfCoreAutoload.class.php';
sfCoreAutoload::register();

require_once '/path/to/your/project/plugins/ysfDimensionsPlugin/lib/config/ysfProjectConfiguration.class.php';

class ProjectConfiguration extends ysfProjectConfiguration
{
	public function setup()
	{
	}
}

Notice that the ProjectConfiguration class now extends ysfProjectConfiguration (against sfProjectConfiguration, the y stands for yahoo!).

The dimension will be set up on an application level. In my example, the user culture is determined by the domain he is browsing. French will be something like fr.mydomain.com, and his culture will be set to english otherwise. To industrialize this behaviour, we have to edit our application configuration file.

Edit /apps/YOURAPP/config/yourAppConfiguration.class.php. First, manually require the plugin library.

require_once(dirname(__FILE__).'/../../../plugins/ysfDimensionsPlugin/lib/config/ysfApplicationConfiguration.class.php');

Then, make your class extend the Yahoo! Application configuration class, instead of the core symfony one.

class frontConfiguration extends ysfApplicationConfiguration // instead of sfApplicationConfiguration

Ok. Now, let’s define the dimension, in the configure method.

public function configure()
{
    //-- hacky. Demonstration purpose only.
	$host_part = explode('.', $_SERVER['HTTP_HOST']);
	$culture = (
		strLen($host_part[0])==2 &&
		(in_array($host_part[0], array('fr', 'en')))
	)?$host_part[0]:'en';

	$this->setDimension(array('culture' => $culture));
	parent::configure();
}

Note: this should go with an appropriate filter, like the one used here in symfonians.

Cool, we’re almost done. If you have an APC extension up and running on your environment, you can pretty safely trigger a symfony cc command. If everything goes as usual, try to browse your app, and if you nothing weird happens, you’re good to go.

If you don’t have APC, you have good chance it won’t work. Indeed, the plugin natively caches the configuration directories in the memory, using the PHP6 core library APC (you can grab it with “pecl install apc”).

If you can’t make it work, this is your last hope: override the main construction call, to make use of local cache or, if in debug mode, no cache at all (bad for production of course).

There you go:

class frontConfiguration extends ysfApplicationConfiguration
{
	public function configure()
	{
		$this->debug = true;

		//-- Hacky. Demonstration purpose only.
		$host_part = explode('.', $_SERVER['HTTP_HOST']);
		$culture = (
			strLen($host_part[0])==2 &&
			(in_array($host_part[0], array('fr', 'en')))
		)?$host_part[0]:'en';

		// setup dimensions before calling parent::configure();
		$this->dimension = new ysfConfigDimension(
			$this->getEventDispatcher(),
			(!isset($this->debug) || (isset($this->debug) && $this->debug === true))
			? new sfNoCache() :
			new sfCache(
				array(
					'prefix' => 'symfony.dimensions.config.default:'.$this->application.':'.$this->environment,
					'automatic_cleaning_factor' => 0, 'lifetime' => 86400)
			)
		);

		$this->setDimension(array('culture' => $culture));
		parent::configure();
	}
}

I had to force the $this->debug = true; because I had mysterious bugs on my development machine (Mac OSX). Try to remove it, if it works without that, it’s even better.

Now, let’s trigger a clear cache (symfony cc) and hit a fresh browser pointing to your application. Everything works as expected? Congrats, now we can go to the fun part.

Internalization with sfDimensionPlugin

In a big scale project, you generally have four types of I18N:

symfony natively supports nb 1 (thanks to Doctrine or Propel), nb 2, and that’s pretty much it. Let’s go back to our little project. You’re working hard on it, and the whole project is almost done. You have written pretty short SEO-friendly URL in /apps/YOUR_APP/config/routing.yml, and nice metas in your /apps/YOUR_APP/modules/YOUR_MOD/config/view.yml. Last, but not least, you decided to put all the static content in a “static” module, where you have empty actions and 5 to 10 HTML fragments.

Let’s internationalize everything:

routing.yml

homepage:
  url: /
  param: { module: home, action: index }

team:
  url: /team
  param: { module: team, action: index }

about_us:
  url: /about-us
  param: { module: static, action: about }

Obviously, we don’t need to translate the first routing rule (@homepage). So let’s create a routing.yml file in /apps/YOUR_APP/config/fr/routing.yml. (create the fr directory if it doesn’t exist yet).

team:
  url: /equipe

about_us:
  url: /a-propos

And that’s it! The plugin is smart enough to automatically inherit your main routing file, and as we gave them the same names, you can restrict your work to defining only the elements that change.

Now, try to go to http://fr.yoursite.dev, and hover a link to @team. It should show the french version now. Now point to the @about_us page. The URL is in french, but the content is in english, right? Remember, it’s a static page we created in a dedicated module. Let’s correct that:

Create a fr directory in

/apps/YOUR_APP/modules/static/templates

Now, copy the aboutSuccess.php template in that directory, and translate all its content. When it’s done, refresh your page. And boom, you should now have the french version.

This process can be done for almost anything in your website. It’s especially useful for metas. Just create a fr directory in /apps/YOUR_APP/modules/YOUR_MOD/config/fr/, and a view.yml file in it, and enjoy:

indexSuccess:
  metas:
    title: My French Title

[etc..]

When you’ve done that work once, you can reproduce a fully I18n environnement very quickly for your new project. Don’t forget that this ysfDimensionsPlugin is very powerful, and can be the perfect solution when you need to build many websites using the same engine (like a white label).

If you have any tip with I18N or ysfDimensionsPlugin, feel free to leave a comment.

• Installer Symfony avec SVN
• De Symfony à Wordpress
• Notre dernier projet
• L’architecture décentralisée
• Dailymotion passe à Symfony
• Jobeet: Une vision convaincante
• 24 tutoriaux pour symfony 1.2
• Yahoo! Answers, c’est du symfony !
• Historique du développement web