> ## Documentation Index
> Fetch the complete documentation index at: https://help.eaglecart.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Eaglecart Theme Customization: Settings, Sections & i18n

> Define merchant settings, build Liquid sections with schema blocks, manage CDN assets, and add multi-language translation support to your Eaglecart theme.

Eaglecart's theme system gives you precise control over every layer of the storefront. You can define merchant-friendly settings that appear in the no-code Theme Editor, build reusable sections with their own configuration schemas, serve optimised CSS and JavaScript through the asset pipeline, and support multiple languages with a straightforward translation API — all without leaving the Liquid template layer.

> [!WARNING]
>
> Never edit your active (live) theme directly when testing new features. Always duplicate the theme first — go to **Online Store → Themes → \[your theme] → ⋯ → Duplicate** — develop on the copy, then publish once you've verified everything works as expected.

> [!TIP]
>
> Use the [Eaglecart Theme CLI](https://github.com/eaglecart/eaglecart-cli) (`eaglecart-cli`) to sync theme files between your local machine and the admin. Run `eaglecart-cli theme pull` to download the current theme, edit files in your editor of choice, and push changes back with `eaglecart-cli theme push`. The CLI also supports a `--watch` flag to sync changes automatically as you save.

***

## Theme Settings Schema

Themes support a `settings_schema.json` file that defines merchant-editable settings. These settings appear as form controls inside **Online Store → Themes → Customize**, letting merchants adjust colours, logos, typography, and layout without touching any code.

The schema is an array of setting group objects. Each group has a `name` (the section heading in the editor UI) and a `settings` array of individual setting definitions.

```json /config/settings_schema.json theme={null}
[
  {
    "name": "Colors",
    "settings": [
      {
        "type": "color",
        "id": "color_scheme",
        "label": "Primary brand color",
        "default": "#1a56db",
        "info": "Used for buttons, links, and accent elements across the storefront."
      },
      {
        "type": "color",
        "id": "background_color",
        "label": "Page background color",
        "default": "#ffffff"
      }
    ]
  },
  {
    "name": "Logo",
    "settings": [
      {
        "type": "image_picker",
        "id": "logo",
        "label": "Logo image"
      },
      {
        "type": "range",
        "id": "logo_width",
        "label": "Logo width (px)",
        "min": 60,
        "max": 300,
        "step": 10,
        "default": 120,
        "unit": "px"
      }
    ]
  }
]
```

Access any setting value in Liquid templates using the `settings` object and the setting's `id`:

```liquid Accessing settings in Liquid theme={null}
{% comment %}Apply the merchant's chosen brand colour to a button{% endcomment %}
<button style="background-color: {{ settings.color_scheme }}">
  Add to cart
</button>

{% comment %}Render the logo at the configured width{% endcomment %}
{% if settings.logo %}
  <img
    src="{{ settings.logo | img_url: settings.logo_width }}"
    alt="{{ shop.name }}"
    width="{{ settings.logo_width }}"
  >
{% endif %}
```

> [!NOTE]
>
> Eaglecart supports the following setting types: `text`, `textarea`, `number`, `range`, `color`, `font_picker`, `image_picker`, `url`, `select`, `checkbox`, `radio`, and `header` (label-only, no value). Refer to the Theme Settings Schema reference for a full list of properties each type accepts.

***

## Creating a Custom Section

Sections are Liquid files in `/sections/` that combine markup with a `{% schema %}` block. Merchants can add, reorder, and configure sections in the Theme Editor; you control exactly which settings are available.

**1. Create the section file**

Add a new `.liquid` file inside the `/sections/` directory of your theme. Name it with a lowercase, hyphenated slug that describes the section's purpose — for example, `/sections/promo-banner.liquid`.

**2. Add your Liquid markup**

Write the HTML and Liquid code that renders the section. Use `section.settings.<id>` to access the values merchants configure in the Theme Editor.

**3. Define the section schema**

Append a `{% schema %}` block to the bottom of the file. The schema is a JSON object that declares the section's settings, presets, and optional block types. The schema block must be the last tag in the file.

**4. Include the section in a template**

Reference the section in any template file using the `{% section %}` tag. Pass the filename without the `.liquid` extension.

```liquid Render a section statically theme={null}
{% section 'promo-banner' %}
```

To make a section dynamically addable from the Theme Editor, add it to the template's JSON wrapper file (e.g. `templates/index.json`) instead.

Here is a complete minimal section example that renders a promotional banner with a merchant-editable heading, subheading, and background colour:

```liquid /sections/promo-banner.liquid theme={null}
<div class="promo-banner" style="background-color: {{ section.settings.background_color }}">
  <div class="promo-banner__inner">
    {% if section.settings.heading != blank %}
      <h2 class="promo-banner__heading">{{ section.settings.heading }}</h2>
    {% endif %}
    {% if section.settings.subheading != blank %}
      <p class="promo-banner__subheading">{{ section.settings.subheading }}</p>
    {% endif %}
    {% if section.settings.button_label != blank and section.settings.button_url != blank %}
      <a class="promo-banner__cta" href="{{ section.settings.button_url }}">
        {{ section.settings.button_label }}
      </a>
    {% endif %}
  </div>
</div>

{% schema %}
{
  "name": "Promo Banner",
  "tag": "section",
  "class": "section-promo-banner",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Summer Sale — Up to 50% Off"
    },
    {
      "type": "text",
      "id": "subheading",
      "label": "Subheading",
      "default": "Limited time only. Shop the collection now."
    },
    {
      "type": "url",
      "id": "button_url",
      "label": "Button link"
    },
    {
      "type": "text",
      "id": "button_label",
      "label": "Button label",
      "default": "Shop now"
    },
    {
      "type": "color",
      "id": "background_color",
      "label": "Background colour",
      "default": "#1a56db"
    }
  ],
  "presets": [
    {
      "name": "Promo Banner"
    }
  ]
}
{% endschema %}
```

***

## Using the Asset Pipeline

All CSS, JavaScript, image, and font files placed in the `/assets/` directory are served through Eaglecart's CDN-backed asset pipeline. Reference them in Liquid using the `asset_url` filter.

### Stylesheets and scripts

```liquid Referencing assets in Liquid theme={null}
{% comment %}Render a <link> tag for a stylesheet{% endcomment %}
{{ 'main.css' | asset_url | stylesheet_tag }}

{% comment %}Render a <script> tag for a JS file{% endcomment %}
{{ 'theme.js' | asset_url | script_tag }}

{% comment %}Get the raw URL for use in a custom tag or variable{% endcomment %}
{% assign logo_src = 'logo.png' | asset_url %}
<img src="{{ logo_src }}" alt="{{ shop.name }}">
```

### Minification

Eaglecart automatically serves the minified version of any file whose name contains `.min.` — for example, `theme.min.js` or `main.min.css`. Keep both the source and minified versions in `/assets/` during development, and reference the `.min.` file in production templates for faster load times.

```liquid Conditionally use the minified build theme={null}
{% if settings.enable_minified_assets %}
  {{ 'theme.min.js' | asset_url | script_tag }}
{% else %}
  {{ 'theme.js' | asset_url | script_tag }}
{% endif %}
```

> [!NOTE]
>
> Files in `/assets/` are hashed at deploy time for cache busting. Never hard-code the full CDN URL in your templates — always use `asset_url` so Eaglecart can append the correct hash query string automatically.

***

## Translation / i18n

Eaglecart's built-in translation system lets you maintain a single set of Liquid templates that render in multiple languages. Add translation strings to locale files in `/locales/` and output them in templates using the `t` filter.

### Adding translation strings

Create or edit the appropriate locale file. Use a nested JSON structure to organise strings by feature area:

```json /locales/en.json theme={null}
{
  "general": {
    "search": {
      "placeholder": "Search our store"
    }
  },
  "products": {
    "product": {
      "add_to_cart": "Add to cart",
      "sold_out": "Sold out",
      "unavailable": "Unavailable",
      "quantity_label": "Quantity"
    }
  },
  "cart": {
    "general": {
      "title": "Your cart",
      "empty": "Your cart is empty.",
      "checkout": "Proceed to checkout",
      "subtotal": "Subtotal"
    }
  }
}
```

Add an equivalent file for each additional locale your store supports — for example, `/locales/fr.json` for French:

```json /locales/fr.json theme={null}
{
  "products": {
    "product": {
      "add_to_cart": "Ajouter au panier",
      "sold_out": "Épuisé",
      "unavailable": "Indisponible",
      "quantity_label": "Quantité"
    }
  }
}
```

### Using translations in Liquid

Reference a translation key in any template using the `t` filter with the dot-separated path to the string:

```liquid Using the t filter theme={null}
{% comment %}Render "Add to cart" in the active language{% endcomment %}
<button type="submit">
  {{ 'products.product.add_to_cart' | t }}
</button>

{% comment %}Pass dynamic values into a translation string{% endcomment %}
{% comment %}en.json: "items_in_cart": "You have {{ count }} item(s) in your cart."{% endcomment %}
<p>{{ 'cart.general.items_in_cart' | t: count: cart.item_count }}</p>

{% comment %}Use a translation as an HTML attribute{% endcomment %}
<input
  type="search"
  placeholder="{{ 'general.search.placeholder' | t }}"
>
```

If a key is missing from the active locale file, Eaglecart automatically falls back to `en.json`. If the key is also missing there, the raw key path is rendered — a useful signal during development that a translation string needs to be added.

> [accordion] Pluralisation
>
> Eaglecart supports the standard `one` / `other` pluralisation convention. Define both forms in your locale file and pass the `count` variable to the `t` filter:
>
> ```json /locales/en.json (pluralisation) theme={null}
> {
>   "cart": {
>     "general": {
>       "item_count": {
>         "one": "{{ count }} item",
>         "other": "{{ count }} items"
>       }
>     }
>   }
> }
> ```
>
> ```liquid Plural in Liquid theme={null}
> {{ 'cart.general.item_count' | t: count: cart.item_count }}
> ```

> [accordion] RTL language support
>
> For right-to-left locales such as Arabic or Hebrew, add `"rtl": true` to the locale file's root object. Eaglecart adds `dir="rtl"` to the `<html>` element automatically when a RTL locale is active, so your CSS `dir` selectors work without any extra Liquid logic.
>
> ```json /locales/ar.json (RTL) theme={null}
> {
>   "rtl": true,
>   "products": {
>     "product": {
>       "add_to_cart": "أضف إلى السلة"
>     }
>   }
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.