Mini Tutorial: Creating a Custom Locale in Magento

Recently I was asked about creating a new, custom locale in Magento. Initial thinking would be that adding this shouldn’t be too difficult and one may think it may even work similarly to adding a module or new theme. Unfortunately it’s just a little bit trickier than that.

Before progressing further, I should note that this is not a tutorial on how to add new translations to an existing locale (For example, you have an English and French store and are using US-EN and FR-FR locales). This tutorial explains how to add another locale, say, ES-US (a Spanish translation for the United States).

Behind the Scenes

If we take a look at the admin backend, we can see in System > Configuration > General we have the locale drop-down before us. Every one of these options in the drop-down are individual locales, which have their own language packs found in app/locale (if you’ve downloaded additional language packs to support the locales).

If you’re wondering how Magento finds these locales, it’s a little bit unfortunate. It looks as if the locale names are hardcoded in Mage_Core_Model_Locale_Config, and other places, even as deep down into lib/Zend/Locale.php. Upon further digging, you may find the core_language table in the install scripts with language codes within it. This table, however, was dropped in subsequent Magento versions. You may also notice the use of the config path XML_PATH_ALLOW_CODES in Mage_Core_Model_Locale, however this path has also been deprecated. It looks like you used to be able to specify codes in the config, which would’ve been helpful to us…

Two Options for Creating a Custom Locale in Magento

We now have two options for creating our own locale:

1) Rewriting Mage_Core_Model_Locale_Config and other classes (such as the Zend lib) to include our new locale (not recommended as it’s so much work)


2) Define your own custom language to “piggyback” on another locale and use their code for your custom language pack.

For example, in app/locale, you could place the folder gl_ES, copy over a Spanish language pack, and make the modifications you need for that language. Then for your store’s locale in the dropdown (System > Configuration > General > Locale) you can choose Galician (Galician). Seems simple enough, right?

Remember if you’re rewriting Mage_Core_Model_Locale_Config or any other core class that you properly rewrite in your own module. Happy translating!