Locales

The Locales folder serves as the global localization engine for a Soppiya theme. It contains a collection of JSON files that house translation strings for every piece of text appearing on the storefront and within the Theme Editor. By centralizing text data, Soppiya allows developers to build internationalized stores that can seamlessly switch between languages such as English, Bengali, and others.

---

Folder Location

Locale files are stored in the /locales directory at the root of the theme.

└── theme
    └── locales
        ├── bn.json               # Bengali Storefront Translations
        ├── default.json          # Fallback Storefront Translations
        └── default.schema.json   # Theme Editor (Admin) Translations

---

Locale File Types

Soppiya distinguishes between two types of localization files to ensure both the customer and the merchant have a localized experience.

Storefront Locales (.json)

These files control the text visible to customers on the live website (e.g., "Search," "Add to Cart," "Checkout").

• The Default File: One file must be named default.json. This acts as the "master" language and the system's fallback if a translation is missing in other language files.

Schema Locales (.schema.json)

These files are specifically for the Soppiya Theme Editor. They translate the labels, headers, and informational text used in your settings_schema.json and section schemas. This ensures that a merchant using the admin panel in Bengali sees "ফিচারড কালেকশন" instead of "Featured Collection."

---

JSON Structure & Organization

Locale files follow a nested JSON structure. To maintain a scalable codebase, translations should be grouped by their functional area (e.g., sections, general, products).

Example: Storefront Translation (bn.json)

{
  "sections": {
    "header": {
      "search": "অনুসন্ধান",
      "menu_title": "সব কালেকশন"
    },
    "featured_collections": {
      "section_title": "ফিচারড কালেকশন"
    }
  }
}

---

Technical Implementation: The t Filter

To render these translations in your Liquid files, use the Translation (t) filter. This filter looks up the corresponding key in the active language file and returns the string.

Basic Usage

Reference the path to the JSON key using dot notation:

• Liquid Input: {{ 'sections.header.search' | t }}
• Output (Bengali): অনুসন্ধান
• Output (English): Search

Advanced Localization Patterns

note

Interpolation: You can pass dynamic variables into translations.

• JSON: "welcome": "স্বাগতম, {{ name }}!"
• Liquid: {{ 'general.welcome' | t: name: customer.first_name }}

tip

HTML-Safe Strings: If a translation contains HTML tags (like <strong>), append _html to the key name (e.g., brand_note_html) to prevent Soppiya from escaping the HTML characters.

---

Naming Conventions

Soppiya follows standard IETF language tags. Proper naming ensures the platform automatically detects and serves the correct file based on the customer's market or browser settings.

Language	Storefront File	Schema File
English (Default)	default.json	default.schema.json
Bengali	bn.json	bn.schema.json
Spanish	es.json	es.schema.json

---

Developer Best Practices

• Avoid Hardcoding: Never hardcode text directly into Liquid templates. Always use the t filter to ensure the store remains accessible to international markets.
• Descriptive Keys: Use clear, hierarchical keys. sections.cart.empty_message is much easier to maintain than a generic key like text.message1.
• Consistency: When adding a new key to default.json, ensure you immediately add the corresponding key to all other language files in your theme to prevent "Missing Translation" errors.

---

For information on how to manage the global configuration of these languages, proceed to the Config documentation.