---
description: Localization coding standards and best practices guide
globs: *.liquid,schemas/*
alwaysApply: false
---
# Localization Standards

## Translation Requirements

- **Every user-facing text** must use translation filters
- **Update `locales/en.default.json`** with all new keys
- **Use descriptive, hierarchical keys** for organization
- **Only add English text** - translators handle other languages

## Translation Filter Usage

**Use `{{ 'key' | t }}` for all text:**

```liquid
<!-- Good -->
<h2>{{ 'sections.featured_collection.title' | t }}</h2>
<p>{{ 'sections.featured_collection.description' | t }}</p>
<button>{{ 'products.add_to_cart' | t }}</button>

<!-- Bad -->
<h2>Featured Collection</h2>
<p>Check out our best products</p>
<button>Add to cart</button>
```

## Translation with Variables

**Use variables for interpolation:**

```liquid
<!-- Liquid template -->
<p>{{ 'products.price_range' | t: min: product.price_min | money, max: product.price_max | money }}</p>
<p>{{ 'general.pagination.page' | t: page: paginate.current_page, pages: paginate.pages }}</p>
```

**Corresponding keys in Locale files:**

```json
{
  "products": {
    "price_range": "From {{ min }} to {{ max }}"
  },
  "general": {
    "pagination": {
      "page": "Page {{ page }} of {{ pages }}"
    }
  }
}
```

## Best Practices

**Content Guidelines:**
- Write clear, concise text
- Use sentence case for UI elements
- Be consistent with terminology
- Consider character limits for UI elements

**Variable Usage:**
- Use interpolation rather than appending strings together
- Naming should be prioritize clarity over brevity
- Escape variables whenever they aren't expected to output HTML: `{{ variable | escape }}`