Skip to main content

​
Overview

OpenCart’s localization features enable you to sell globally with support for multiple languages, currencies, tax zones, and regional preferences. Configure these settings to provide a localized experience for customers worldwide.
Access localization settings from System → Localization in the admin panel.

​
Languages

​
Managing Languages

Add multiple languages to your store for international customers. 
// From language.php controller
namespace Opencart\Admin\Controller\Localisation;

class Language extends \Opencart\System\Engine\Controller {
    public function index(): void {
        $this->load->model('localisation/language');
        $languages = $this->model_localisation_language->getLanguages();
    }
}
1

Add a Language

Navigate to System → Localization → Languages and click Add New.Required Fields:
  • Language Name (e.g., “English”, “Español”)
  • Code (ISO 639-1, e.g., “en”, “es”)
  • Locale (e.g., “en-US”, “es-ES”)
  • Image/Flag icon
  • Sort Order
  • Status (Enabled/Disabled)
2

Install Language Pack

Download language extensions from the OpenCart Marketplace and install via Extensions → Installer.
3

Set Default Language

Go to System → Settings and select the default language for your store.

​
Language Code Structure

// Language files location
/catalog/language/{language_code}/
/admin/language/{language_code}/

// Example: English translations
/catalog/language/en-gb/common/header.php
/catalog/language/en-gb/product/product.php
Name - Display name shown to customersCode - Two-letter ISO code (en, es, fr, de)Locale - Full locale identifier (en-US, en-GB, es-ES)Image - Flag icon for language switcherDirectory - Folder name in language directoryStatus - Enable/disable languageSort Order - Display order in language selector

​
Currencies

​
Managing Currencies

Support multiple currencies with automatic or manual exchange rates. 
// From currency.php controller
$this->load->model('localisation/currency');
$currencies = $this->model_localisation_currency->getCurrencies();
1

Add Currency

Navigate to System → Localization → Currencies and click Add New.
// Currency fields
$data = [
    'title' => 'US Dollar',
    'code' => 'USD',
    'symbol_left' => '$',
    'symbol_right' => '',
    'decimal_place' => '2',
    'value' => '1.00000000',
    'status' => 1
];
2

Configure Exchange Rates

Set the exchange rate relative to your default currency.Auto-update: Install currency extension (ECB, Fixer.io) to automatically update rates.
3

Set Default Currency

Go to System → Settings and select the default currency for pricing.

​
Currency Auto-Update

OpenCart includes extensions for automatic exchange rate updates. 
// extension/opencart/catalog/controller/currency/ecb.php
namespace Opencart\Catalog\Controller\Extension\Opencart\Currency;

class ECB extends \Opencart\System\Engine\Controller {
    public function currency(array $default = []): array {
        $curl = curl_init();
        curl_setopt($curl, CURLOPT_URL, 'https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml');
        // Parse XML and update rates
    }
}
Free service from European Central Bank, updated daily.
Set up a cron job to run cron/currency route daily for automatic rate updates.

​
Countries and Zones

​
Countries

Manage the list of countries available for shipping and billing addresses. 
// From country.php model
public function getCountries(array $data = []): array {
    $sql = "SELECT * FROM `" . DB_PREFIX . "country`";
    
    if (!empty($data['filter_name'])) {
        $sql .= " WHERE `name` LIKE " . $this->db->escape('%' . $data['filter_name'] . '%');
    }
    
    $sql .= " ORDER BY `name` ASC";
    
    return $this->db->query($sql)->rows;
}
Country Name - Full country nameISO Code 2 - Two-letter code (US, GB, CA)ISO Code 3 - Three-letter code (USA, GBR, CAN)Address Format - Template for formatting addressesPostcode Required - Mandate postal code in addressesStatus - Enable/disable country for checkout

​
Zones (States/Provinces)

Define regions within countries for tax and shipping calculations. 
// From zone.php model
public function getZonesByCountryId(int $country_id): array {
    $query = $this->db->query(
        "SELECT * FROM `" . DB_PREFIX . "zone` 
        WHERE `country_id` = '" . (int)$country_id . "' 
        AND `status` = '1' 
        ORDER BY `name`"
    );
    
    return $query->rows;
}

United States

50 states + territories (DC, PR, GU, etc.)

Canada

13 provinces and territories

Australia

8 states and territories

Custom Zones

Add custom regions for any country

​
Geo Zones

​
Creating Geo Zones

Geo zones are groups of countries/regions used for targeted shipping and tax rules.
1

Create Geo Zone

Navigate to System → Localization → Geo Zones and add a new zone.Example: “European Union”, “North America”, “Asia Pacific”
2

Add Countries/Zones

Select specific countries or regions to include in the geo zone.
// Geo zone structure
$geo_zone = [
    'name' => 'European Union',
    'description' => 'EU member countries',
    'countries' => [
        ['country_id' => 81, 'zone_id' => 0], // Germany (all zones)
        ['country_id' => 74, 'zone_id' => 0], // France (all zones)
        // ... more countries
    ]
];
3

Apply to Tax/Shipping

Use geo zones in tax classes and shipping method restrictions.

​
Use Cases for Geo Zones

Create a geo zone for EU countries to apply VAT tax rates correctly.
Offer free shipping for specific regions by creating a geo zone and configuring shipping methods.
Limit payment methods to specific regions based on geo zones.

​
Tax Configuration

​
Tax Classes

Define tax categories for products (e.g., “Taxable Goods”, “Digital Services”). 
// Tax class structure
$tax_class = [
    'title' => 'Taxable Goods',
    'description' => 'Standard VAT rate',
    'tax_rules' => [
        [
            'tax_rate_id' => 87,  // 20% VAT
            'based' => 'shipping', // shipping, payment, or store
            'priority' => 1
        ]
    ]
];

​
Tax Rates

Set up tax rates for different regions.
1

Create Tax Rate

Navigate to System → Localization → Tax Rates.Fields:
  • Tax Name (e.g., “VAT”, “GST”, “Sales Tax”)
  • Tax Rate (percentage)
  • Type (Percentage or Fixed)
  • Geo Zone (where to apply)
2

Link to Tax Class

Add tax rates to tax classes via Tax Classes screen.
3

Assign to Products

Select tax class when creating/editing products.
Tax Calculation Based On:
  • Shipping Address (recommended for most regions)
  • Payment Address
  • Store Address
Ensure this matches your local tax regulations.

​
Length and Weight Classes

​
Length Classes

Define units of measurement for product dimensions.
Length ClassValueCommon Use
Centimeter1.00000Base unit
Millimeter10.00000Small items
Inch0.39370US/UK markets
Meter0.01000Large items

​
Weight Classes

Define units of measurement for product weight.
Weight ClassValueCommon Use
Kilogram1.00000Base unit
Gram1000.00000Small items
Pound2.20462US/UK markets
Ounce35.27400Lightweight items
Set one unit as the base (value = 1.00000) and calculate others relative to it.

​
Stock Status

​
Managing Stock Statuses

Define stock availability messages shown to customers. 
// Common stock statuses
$statuses = [
    'In Stock',
    'Out of Stock',
    'Pre-Order',
    '2-3 Days',
    'Discontinued'
];

In Stock

Product available for immediate shipment

Out of Stock

Product currently unavailable

Pre-Order

Accept orders for upcoming inventory

Backorder

Temporarily out, ships when restocked

Store Settings

Configure general store settings

Extensions

Install currency and language extensions

SEO

Multi-language SEO configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us