# Shoplazza 应用开发指南：多语言支持与前端优化
  
  ## 目录
  
  1. [多语言支持](#多语言支持)
  2. [前端优化与 Lessjs 集成](#前端优化与-lessjs-集成)
  3. [与店匠主题的适配](#与店匠主题的适配)
  
  ---
  
  ## 多语言支持
  
  ### 1. 概述
  
  Shoplazza 应用支持 16 种语言，通过 Liquid 模板的 `t` 过滤器和 `shop.locale` 对象实现自动语言适配。
  
  ### 2. 支持的语言列表
  
  根据 [Lessjs 文档](https://lessjs.shoplazza.com/latest/docs/introduction/)，Shoplazza 支持以下语言：
  
  | 语言代码 | 语言名称 | 示例文本 |
  |---------|---------|---------|
  | `ar-SA` | 阿拉伯语(沙特阿拉伯) | أضف إلى السلة |
  | `de-DE` | 德语 | In den Warenkorb legen |
  | `en-US` | 英语 | Add to cart |
  | `es-ES` | 西班牙语 | Añadir a la cesta |
  | `fr-FR` | 法语 | Ajouter au panier |
  | `id-ID` | 印度尼西亚语 | Masukkan ke keranjang |
  | `it-IT` | 意大利语 | Aggiungi al carrello |
  | `ja-JP` | 日语 | カートに追加 |
  | `ko-KR` | 韩语 | 카트에 추가하십시오 |
  | `nl-NL` | 荷兰语 | Voeg toe aan winkelkar |
  | `pl-PL` | 波兰语 | Dodaj do koszyka |
  | `pt-PT` | 葡萄牙语 | Adicionar ao carrinho |
  | `ru-RU` | 俄语 | Добавить в корзину |
  | `th-TH` | 泰语 | เพิ่มลงในรถเข็น |
  | `zh-CN` | 中文（简体中文） | 加入购物车 |
  | `zh-TW` | 中文（繁体中文） | 加入購物車 |
  
  ### 3. 实现方式
  
  #### 3.1 目录结构
  
  ```
  extensions/your-extension/
  ├── blocks/
  │   └── your-block.liquid
  ├── assets/
  │   └── your-block.css
  └── locales/
      ├── zh-CN.json
      ├── en-US.json
      ├── ko-KR.json
      ├── ja-JP.json
      └── ... (其他语言文件)
  ```
  
  #### 3.2 语言文件格式
  
  每个语言文件（如 `locales/zh-CN.json`）应包含完整的翻译键值对：
  
  ```json
  {
    "search": {
      "placeholder": "搜索商品...",
      "loading": "搜索中，请稍候...",
      "no_results": "未找到相关商品",
      "error": "搜索失败，请重试",
      "results_count": "找到 {count} 个结果",
      "sort_label": "排序：",
      "sort_default": "默认排序",
      "sort_price_asc": "价格：低到高",
      "sort_price_desc": "价格：高到低",
      "sort_newest": "最新上架",
      "facet_category": "类目",
      "facet_brand": "品牌",
      "facet_tag": "标签",
      "pagination_prev": "上一页",
      "pagination_next": "下一页",
      "out_of_stock": "缺货",
      "unknown_product": "未知商品",
      "enter_keyword": "请输入搜索关键词",
      "searching": "搜索中..."
    }
  }
  ```
  
  #### 3.3 Liquid 模板中的使用
  
  ##### 3.3.1 获取店铺语言
  
  ```liquid
  {% comment %} 获取店铺当前语言 {% endcomment %}
  {{ shop.locale }}
  ```
  
  ##### 3.3.2 使用翻译过滤器
  
  在 HTML 属性中使用：
  
  ```liquid
  <input 
    type="text" 
    placeholder="{{ 'search.placeholder' | t }}"
    aria-label="{{ 'search.placeholder' | t }}"
  />
  ```
  
  在 HTML 内容中使用：
  
  ```liquid
  <label>{{ 'search.sort_label' | t }}</label>
  ```
  
  在 `<option>` 标签中使用（需要配合 JavaScript 确保正确显示）：
  
  ```liquid
  <select id="sort-select">
    <option value="" data-translation-key="sortDefault">
      {{ 'search.sort_default' | t }}
    </option>
    <option value="min_price:asc" data-translation-key="sortPriceAsc">
      {{ 'search.sort_price_asc' | t }}
    </option>
  </select>
  ```
  
  #### 3.4 JavaScript 中的多语言支持
  
  ##### 3.4.1 将翻译传递给 JavaScript
  
  在 `<script>` 标签中，通过 Liquid 将翻译文本传递给 JavaScript：
  
  ```javascript
  <script>
  (function() {
    // 获取店铺语言
    const shopLocale = "{{ shop.locale }}" || "zh-CN";
    
    // 翻译文本（通过 Liquid 的 t 过滤器获取）
    const translations = {
      placeholder: "{{ 'search.placeholder' | t }}",
      loading: "{{ 'search.loading' | t }}",
      noResults: "{{ 'search.no_results' | t }}",
      error: "{{ 'search.error' | t }}",
      resultsCount: "{{ 'search.results_count' | t }}",
      // ... 更多翻译键
    };
    
    // 工具函数：替换占位符
    function translate(key, params) {
      let text = translations[key] || key;
      if (params) {
        Object.keys(params).forEach(param => {
          text = text.replace(`{${param}}`, params[param]);
        });
      }
      return text;
    }
    
    // 使用翻译
    function showResults(total) {
      const message = translate('resultsCount', { count: total });
      document.getElementById('status').textContent = message;
    }
  })();
  </script>
  ```
  
  ##### 3.4.2 处理动态内容翻译
  
  对于动态生成的内容（如排序下拉框），需要确保翻译正确显示：
  
  ```javascript
  // 初始化排序下拉框文本（确保翻译正确显示）
  function initSortSelect() {
    const sortSelect = document.getElementById('sort-select');
    if (sortSelect) {
      // 遍历所有选项，使用 JavaScript 设置文本
      Array.from(sortSelect.options).forEach((option, index) => {
        const translationKey = option.getAttribute('data-translation-key');
        if (translationKey && translations[translationKey]) {
          option.text = translations[translationKey];
        }
      });
    }
  }
  
  // 在 DOM 加载完成后初始化
  document.addEventListener('DOMContentLoaded', function() {
    initSortSelect();
  });
  ```
  
  ##### 3.4.3 翻译回退机制（可选）
  
  如果 Liquid 翻译失败，可以实现 JavaScript 回退机制：
  
  ```javascript
  function checkAndLoadTranslations() {
    const firstTranslation = translations.placeholder;
    const isLikelyEnglish = firstTranslation === 'Search products...' || 
                           firstTranslation === 'search.placeholder' ||
                           firstTranslation === '';
    
    // 如果检测到可能是英语，且店铺语言不是英语，尝试加载正确的翻译
    if (isLikelyEnglish && shopLocale && shopLocale !== 'en-US' && shopLocale !== 'en') {
      const localeFile = `/extensions/your-extension/locales/${shopLocale}.json`;
      fetch(localeFile)
        .then(response => response.json())
        .then(data => {
          if (data && data.search) {
            // 更新翻译对象
            translations = {
              ...translations,
              placeholder: data.search.placeholder || translations.placeholder,
              loading: data.search.loading || translations.loading,
              // ... 更多翻译
            };
            
            // 重新初始化UI
            initSortSelect();
          }
        })
        .catch(error => {
          console.warn('Failed to load translation file:', error);
        });
    }
  }
  ```
  
  ### 4. 最佳实践
  
  1. **完整性**：确保所有语言文件包含相同的翻译键，避免缺失导致显示键名
  2. **占位符**：使用 `{count}` 等占位符支持动态内容，如 `"找到 {count} 个结果"`
  3. **命名规范**：使用有意义的键名，如 `search.placeholder` 而不是 `text1`
  4. **测试**：在不同语言环境下测试应用，确保所有文本正确显示
  5. **回退机制**：为关键翻译提供默认值，避免显示空白或键名
  
  ---
  
  ## 前端优化与 Lessjs 集成
  
  ### 1. Lessjs 简介
  
  **Lessjs** 是 Shoplazza（店匠）官方提供的前端组件库，基于 **Web Components** 开发。它提供了：
  
  - 高性能页面构建能力
  - 现成的组件（轮播图、视频、瀑布流等）
  - 自定义组件支持
  - 与 Shoplazza 主题的深度集成
  
  **官方文档**：
  - [Lessjs 简介](https://lessjs.shoplazza.com/latest/docs/introduction/)
  - [自定义组件](https://lessjs.shoplazza.com/latest/docs/custom-component/)
  
  ### 2. 引入 Lessjs
  
  #### 2.1 通过 CDN 引入
  
  在 Liquid 模板的 `<head>` 标签中引入 Lessjs：
  
  ```liquid
  <head>
    <meta charset="UTF-8">
    <title>Your App</title>
    
    {% comment %} 引入 Lessjs {% endcomment %}
    <script async crossorigin="anonymous" src="https://static.staticdj.com/cuttlefish/v1/spz.min.js"></script>
    
    {% comment %} Lessjs 加载前的样式（必须）{% endcomment %}
    <style>
      body {
        -webkit-animation: -spz-start 8s steps(1,end) 0s 1 normal both;
        -moz-animation: -spz-start 8s steps(1,end) 0s 1 normal both;
        -ms-animation: -spz-start 8s steps(1,end) 0s 1 normal both;
        animation: -spz-start 8s steps(1,end) 0s 1 normal both;
      }
      @-webkit-keyframes -spz-start {
        from { visibility: hidden; }
        to { visibility: visible; }
      }
      @-moz-keyframes -spz-start {
        from { visibility: hidden; }
        to { visibility: visible; }
      }
      @-ms-keyframes -spz-start {
        from { visibility: hidden; }
        to { visibility: visible; }
      }
      @-o-keyframes -spz-start {
        from { visibility: hidden; }
        to { visibility: visible; }
      }
      @keyframes -spz-start {
        from { visibility: hidden; }
        to { visibility: visible; }
      }
    </style>
    <noscript>
      <style>
        body {
          -webkit-animation: none;
          -moz-animation: none;
          -ms-animation: none;
          animation: none;
        }
      </style>
    </noscript>
  </head>
  ```
  
  **重要要求**：
  1. 脚本必须带有 `async` 属性
  2. 必须包含上述 CSS 样式，用于在 Lessjs 加载前隐藏页面内容
  3. 必须包含 `<noscript>` 标签的样式回退
  
  #### 2.2 HTML lang 属性
  
  确保 HTML 的 `lang` 属性设置为支持的语言代码之一（见[支持的语言列表](#2-支持的语言列表)）：
  
  ```liquid
  <html lang="{{ shop.locale | default: 'zh-CN' }}">
  ```
  
  ### 3. 创建自定义 Lessjs 组件
  
  #### 3.1 基础结构
  
  Lessjs 自定义组件基于 ES6 class，继承 `SPZ.BaseElement`：
  
  ```liquid
  {% comment %} 使用自定义组件 {% endcomment %}
  <spz-custom-ai-search layout="container"></spz-custom-ai-search>
  
  {% comment %} 定义自定义组件 {% endcomment %}
  <spz-script layout="logic" type="application/javascript">
    class SpzCustomAiSearch extends SPZ.BaseElement {
      constructor(element) {
        super(element);
        // 初始化变量
        this.searchQuery = '';
        this.currentPage = 1;
      }
  
      isLayoutSupported(layout) {
        // 支持的布局类型
        return layout == SPZCore.Layout.CONTAINER;
      }
  
      buildCallback() {
        // 构建回调：组件开始构建时触发，用于初始化
        console.log('Component building...');
      }
  
      mountCallback() {
        // 挂载回调：组件挂载完成后触发，用于数据请求
        console.log('Component mounted, fetching data...');
        this.performSearch();
      }
  
      unmountCallback() {
        // 卸载回调：组件卸载前触发，用于清理
        console.log('Component unmounting, cleaning up...');
        // 移除事件监听器等
      }
  
      layoutCallback() {
        // 布局回调：元素及子节点完全挂载完成，用于 DOM 操作
        console.log('Layout complete, ready for DOM operations');
      }
    }
  
    // 注册自定义组件
    SPZ.defineElement('spz-custom-ai-search', SpzCustomAiSearch);
  </spz-script>
  ```
  
  #### 3.2 命名规范
  
  - **组件名称**：必须以 `spz-custom-` 开头，如 `spz-custom-ai-search`
  - **私有变量/函数**：以 `_` 结尾，如 `this.searchQuery_`
  - **公共 API 方法**：不以 `_` 结尾，如 `this.performSearch()`
  
  #### 3.3 生命周期函数
  
  | 函数名 | 触发时机 | 用途 |
  |--------|---------|------|
  | `constructor` | 组件创建时 | 初始化变量，必须调用 `super(element)` |
  | `isLayoutSupported` | 布局检查时 | 返回组件支持的布局类型 |
  | `buildCallback` | 组件开始构建时 | 初始化工作 |
  | `mountCallback` | 组件挂载完成后 | 数据请求、API 调用 |
  | `unmountCallback` | 组件卸载前 | 清理事件监听、重置变量 |
  | `layoutCallback` | DOM 完全挂载后 | DOM 操作、事件绑定 |
  
  #### 3.4 this 对象
  
  自定义组件中的 `this` 对象提供以下属性和方法：
  
  | 属性/方法 | 说明 |
  |----------|------|
  | `this.element` | 当前组件 DOM 元素 |
  | `this.win` | window 对象 |
  | `this.getViewport()` | 获取 Viewport 服务（参考 [SPZServices 文档](https://lessjs.shoplazza.com/latest/docs/spz-services/)） |
  
  #### 3.5 完整示例：AI 搜索组件
  
  ```liquid
  {% use "ai-search.css" %}
  
  <div id="ai-search" class="ai-search-container">
    <spz-custom-ai-search layout="container">
      <!-- 搜索框 -->
      <form class="search-form" id="search-form">
        <div class="search-input-wrapper">
          <input 
            type="text" 
            id="search-input"
            class="search-input" 
            placeholder="{{ 'search.placeholder' | t }}"
            autocomplete="off"
          />
          <button type="submit" class="search-button" id="search-button">
            <svg class="search-icon" viewBox="0 0 24 24" width="20" height="20">
              <path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/>
            </svg>
          </button>
        </div>
      </form>
      
      <!-- 搜索结果容器 -->
      <div class="search-results-container" id="search-results-container"></div>
    </spz-custom-ai-search>
  </div>
  
  <spz-script layout="logic" type="application/javascript">
    class SpzCustomAiSearch extends SPZ.BaseElement {
      constructor(element) {
        super(element);
        this.apiEndpoint = 'https://saas-ai-api.essa.top/app-api/app/shoplazza/search/';
        this.state = {
          query: '',
          currentPage: 1,
          pageSize: 20
        };
      }
  
      isLayoutSupported(layout) {
        return layout == SPZCore.Layout.CONTAINER;
      }
  
      buildCallback() {
        // 初始化翻译
        this.shopLocale = "{{ shop.locale }}" || "zh-CN";
        this.translations = {
          placeholder: "{{ 'search.placeholder' | t }}",
          loading: "{{ 'search.loading' | t }}",
          noResults: "{{ 'search.no_results' | t }}",
          // ... 更多翻译
        };
      }
  
      mountCallback() {
        // 绑定搜索表单事件
        const form = this.element.querySelector('#search-form');
        if (form) {
          form.addEventListener('submit', (e) => this.handleSearch(e));
        }
      }
  
      async handleSearch(event) {
        event.preventDefault();
        
        const searchInput = this.element.querySelector('#search-input');
        const query = searchInput.value.trim();
        
        if (!query) {
          alert(this.translations.enterKeyword);
          return;
        }
        
        this.state.query = query;
        this.state.currentPage = 1;
        
        await this.performSearch();
      }
  
      async performSearch() {
        const resultsContainer = this.element.querySelector('#search-results-container');
        resultsContainer.innerHTML = `<div class="loading">${this.translations.loading}</div>`;
        
        try {
          const response = await fetch(this.apiEndpoint, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              query: this.state.query,
              size: this.state.pageSize,
              from: (this.state.currentPage - 1) * this.state.pageSize
            })
          });
          
          const data = await response.json();
          this.renderResults(data);
        } catch (error) {
          resultsContainer.innerHTML = `<div class="error">${this.translations.error}</div>`;
        }
      }
  
      renderResults(data) {
        const resultsContainer = this.element.querySelector('#search-results-container');
        // 渲染搜索结果...
      }
  
      unmountCallback() {
        // 清理工作
      }
    }
  
    SPZ.defineElement('spz-custom-ai-search', SpzCustomAiSearch);
  </spz-script>
  ```
  
  ### 4. 使用 Lessjs 的优势
  
  1. **性能优化**：Lessjs 基于 Web Components，提供更好的性能
  2. **主题集成**：与 Shoplazza 主题深度集成，样式更统一
  3. **组件复用**：可以使用 Lessjs 提供的现成组件（轮播图、视频等）
  4. **标准化**：遵循 Shoplazza 的开发规范，减少兼容性问题
  
  ---
  
  ## 与店匠主题的适配
  
  ### 1. 样式适配
  
  #### 1.1 使用主题变量
  
  尽可能使用 Shoplazza 主题提供的 CSS 变量：
  
  ```css
  /* 使用主题颜色变量 */
  .ai-search-container {
    color: var(--color-text, #333);
    background: var(--color-background, #fff);
    border-color: var(--color-border, #e0e0e0);
  }
  
  /* 使用主题字体变量 */
  .ai-search-container {
    font-family: var(--font-body-family, sans-serif);
    font-size: var(--font-body-size, 14px);
  }
  ```
  
  #### 1.2 响应式设计
  
  遵循 Shoplazza 的响应式断点：
  
  ```css
  /* 移动端 */
  @media (max-width: 749px) {
    .ai-search-container {
      padding: 10px;
    }
  }
  
  /* 平板 */
  @media (min-width: 750px) and (max-width: 989px) {
    .ai-search-container {
      padding: 20px;
    }
  }
  
  /* 桌面端 */
  @media (min-width: 990px) {
    .ai-search-container {
      padding: 30px;
    }
  }
  ```
  
  ### 2. 功能适配
  
  #### 2.1 使用 Shoplazza 全局对象
  
  在 JavaScript 中，可以使用 Shoplazza 提供的全局对象：
  
  ```javascript
  // 访问店铺信息
  const shopDomain = window.Shopify?.shop || "{{ shop.domain }}";
  const shopLocale = window.Shopify?.locale || "{{ shop.locale }}";
  
  // 使用 Shoplazza 的工具函数（如果可用）
  if (window.Shoplazza?.utils) {
    // 使用工具函数
  }
  ```
  
  #### 2.2 事件处理
  
  遵循 Shoplazza 的事件处理规范：
  
  ```javascript
  // 使用事件委托，提高性能
  document.addEventListener('click', (e) => {
    if (e.target.closest('.search-button')) {
      handleSearch(e);
    }
  });
  
  // 避免直接操作 DOM，使用 Lessjs 组件生命周期
  ```
  
  ### 3. 性能优化建议
  
  1. **延迟加载**：非关键资源使用 `defer` 或 `async`
  2. **图片优化**：使用 Shoplazza 的图片 CDN 和响应式图片
  3. **代码分割**：将大型 JavaScript 拆分为多个模块
  4. **缓存策略**：合理使用浏览器缓存和 CDN 缓存
  
  ### 4. 测试清单
  
  - [ ] 在不同语言环境下测试多语言显示
  - [ ] 在不同设备上测试响应式布局
  - [ ] 测试与不同 Shoplazza 主题的兼容性
  - [ ] 测试 Lessjs 组件的加载和渲染
  - [ ] 测试 API 调用的错误处理
  - [ ] 测试页面加载性能
  
  ---
  
  ## 总结
  
  1. **多语言支持**：使用 Liquid 的 `t` 过滤器和 `shop.locale`，确保所有语言文件完整
  2. **Lessjs 集成**：使用 Lessjs 自定义组件提升性能和主题适配
  3. **主题适配**：使用主题变量和响应式设计，确保与店匠主题良好集成
  
  遵循以上指南，可以开发出高质量、高性能、多语言支持的 Shoplazza 应用。
  
  ---
  
  ## 参考资源
  
  - [Lessjs 官方文档](https://lessjs.shoplazza.com/latest/docs/introduction/)
  - [Lessjs 自定义组件文档](https://lessjs.shoplazza.com/latest/docs/custom-component/)
  - [Shoplazza 开发者文档](https://www.shoplazza.dev/)