How do I create a custom locale in Magento?

How do I create a custom locale in Magento?

August 6, 2026 · Illustrated author avatarBy Stefan Bogdanescu
How do I create a custom locale in Magento?

Creating a Custom Locale in Magento

Magento offers a wide range of pre-installed locales for localization purposes, but sometimes you might need to create your own. This guide will walk you through the process of creating a custom locale - specifically, Spanish (U.S.) - step by step.

Understanding Magento Localization

Before we dive into the creation process, it’s important to understand how Magento handles localization. The system divides locales into two main components: language and area (country-specific settings).

In our case, we want to create a Spanish locale for the United States. This means we need to combine the Spanish language with U.S.-specific country settings.

Creating Your Custom Locale

Step 1: Copy an Existing Localization Directory

As the Magento KB article suggests, creating a new locale involves copying an existing localization directory as a base. For our Spanish (U.S.) locale, let’s use the English (U.S.) directory as a starting point:

/app/locale/en_US

Copy this entire folder and rename it to match your desired locale:

/app/locale/es_US

Step 2: Update Language Files

Navigate to the newly created es_US folder. Inside, you’ll find several language files with the .mo extension (e.g., en_US.mo, en_US.csv). These files contain the actual translations for your interface.

For our Spanish (U.S.) locale, we need to replace the content of these files with the corresponding Spanish translations. You can obtain these translations from a professional translation service or use an online translation tool like Google Translate as a starting point.

Update each .mo file with the appropriate Spanish text. The .csv file is optional but can be used for additional customizations if needed.

Step 3: Update Country Files

Next, we need to modify the country-specific files located in the app/country/ directory:

/app/country

Here, you’ll find folders like US, representing various countries. Since our locale is specific to the United States, update the US folder with any Spanish translations or customizations required for U.S.-specific settings.

Step 4: Compile and Save

After updating all necessary files, compile your changes using Magento’s built-in localization compiler:

php -f shell/compiler.php --locale es_US

This command generates the required .mo files and saves them to the app/i18n/ directory.

Step 5: Set Your Custom Locale in Magento

Now that your custom locale is created, you need to set it as active in your Magento store:

  1. Log in to your Magento admin panel.
  2. Navigate to Stores > Configuration > General > General.
  3. Under the ‘Locale Options’ section, select your new es_US locale from the ‘Locale’ dropdown menu.
  4. Click Save Config.

Conclusion

Creating a custom locale in Magento allows you to provide a localized experience tailored to your specific target audience. By following these steps, you’ve successfully created and activated the Spanish (U.S.) locale for your store.

Remember, translations should always be done by professional linguists to ensure accuracy and cultural relevance. Online tools can serve as a starting point but may not capture the nuances of the language.

If you’re looking for additional Magento localization tips or need help with other aspects of e-commerce development, feel free to explore our blog at https://laravelcompany.com. We cover various topics related to Magento, Laravel, and e-commerce best practices.

Happy localizing!

Extensions Configuration Import/Export

Our network