Translation Guide

This guide explains how to add, manage, and update translations for your Shopify theme.

How Translations Work

1. Locale Files store translations in JSON format (e.g., ar.json, fr.json)
2. Liquid Tags reference translations: {{ 'key.path' | t }}
3. Shopify Admin manages language enablement
4. Automatic Loading serves correct translations based on customer locale

Locale File Structure

{
  "general": {
    "accessibility": {
      "skip_to_content": "Translation here"
    },
    "meta": {
      "page": "Translation with {{ variable }}"
    }
  },
  "products": {
    "product": {
      "add_to_cart": "Translation here"
    }
  }
}

Adding New Translations

Step 1: Create Locale File

Create the JSON file for your language (e.g., ar.json for Arabic).

Step 2: Enable in Shopify Admin

Go to Settings > Languages, add the language, and publish it.

Step 3: Upload Translations

Either import via Settings > Languages or edit the locale file directly in the theme editor.

Step 4: Test

Preview your theme and switch languages to verify translations.

Best Practices

Maintain Consistency

Use the same terminology and spelling throughout. Don’t mix formal/informal forms for the same words.

Consider Text Length

RTL text can be shorter or longer than English. Always test with actual translations, not placeholders.

Handle Pluralization

Arabic has 6 plural forms:

{
  "product_count": {
    "zero": "No products",
    "one": "One product",
    "two": "Two products",
    "few": "{{ count }} products",
    "many": "{{ count }} products",
    "other": "{{ count }} products"
  }
}

Cultural Considerations

• Currency: Use the correct currency symbol for the region
• Numbers: Keep Western Arabic numerals (1, 2, 3) unless specifically requested
• Date formats: Use locale-appropriate formats

Avoid Concatenation

Bad:

{{ 'general.welcome' | t }} {{ customer.name }}

Good:

{
  "welcome_message": "Welcome {{ name }} to our store"
}

{{ 'general.welcome_message' | t: name: customer.name }}

Priority Translation Order

1. Critical: Navigation, product actions (Add to Cart, Buy Now), accessibility labels, checkout flow, error messages
2. High: Product details, search, account/login, footer links, form labels
3. Medium: Marketing copy, product descriptions, blog content
4. Low: Legal pages, advanced features

Working with Translators

Provide a translation brief including:

• Target audience and region
• Tone (formal, casual, luxurious)
• Important brand terms and their translations
• Items not to translate (brand names, SKUs, URLs, size codes)
• Desired format: valid JSON, UTF-8 encoding

Quality Checklist

• All keys translated
• Pluralization rules followed
• Variables ({{ }}) preserved
• JSON syntax valid
• Reviewed by native speaker

Testing Translations

1. Enable locale in Shopify Admin
2. Upload translation file
3. Preview theme with locale
4. Navigate all pages: Homepage, Collections, Products, Cart, Search, Account, 404
5. Check for missing translations, text overflow, broken layouts, and incorrect plurals

Common Issues

Special characters breaking JSON: Escape quotes within translations: \"quoted text\"

Variables not replacing: Ensure variables use double curly braces: {{ price }} not just price

Plural forms not working: Use the correct plural form structure with zero, one, two, few, many, other keys as needed.

Updating Translations

When new features are added or text changes:

1. Compare old vs new English locale to identify new/changed keys
2. Send changes to translator
3. Update locale files
4. Test changes across all pages