# Esun_Translation 安装与使用说明 ## 模块说明 `Esun_Translation` 是 Magento 2 后台 AI 辅助多语言翻译模块。当前支持: 当前版本:`1.2.2` - 产品:编辑页按钮、产品列表顶部按钮、产品列表行操作。 - CMS Page:编辑页按钮、列表行操作。 - CMS Block:编辑页按钮、列表行操作。 模块按配置的语言组列出目标 Store View,管理员打开统一翻译工作台后,可以调用 OpenAI-compatible Chat Completions API 生成翻译结果,并在人工确认后写入对应 Store View 或 CMS store-specific 副本。 ## 安装步骤 将压缩包中的目录放到 Magento 根目录: ```text app/code/Esun/Translation ``` 执行: ```bash php bin/magento module:enable Esun_Translation php bin/magento setup:upgrade php bin/magento cache:flush ``` 生产模式下再执行: ```bash php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f php bin/magento cache:flush ``` 确认模块状态: ```bash php bin/magento module:status Esun_Translation ``` ## 后台配置 入口: ```text Stores > Configuration > Services > Esun Translation ``` ### General - `Enabled`:启用或关闭模块。 - `Source Locale`:源语言,例如 `en`。 - `Source Store ID`:产品源 Store ID,通常为 `0`。CMS 使用当前打开的 Page/Block 作为源内容。 - `Translatable Product Attributes`:产品可翻译属性 code,逗号或换行分隔。 - `Language Store View Groups`:语言和 Store View 映射,每行一个语言组。 语言组格式: ```text 语言名称|目标语言代码|store_code_1,store_code_2 ``` 示例: ```text English|en|us_EN,de_EN German|de|us_DE,de_DE French|fr|us_FR,de_FR ``` ### AI Provider - `Provider`:当前支持 `OpenAI Compatible`。 - `API Base URL`:默认 `https://api.openai.com/v1`。 - `API Key`:AI 接口密钥,使用 Magento encrypted config 保存。 - `Model`:模型名称。 - `Temperature`:建议 `0.2`。 - `Timeout Seconds`:建议 `60`。 模块会优先要求 AI 返回符合 JSON Schema 的严格 JSON: ```json {"translations":{"field_key":"translated text"}} ``` 服务端会校验所有请求字段必须存在,且不得返回额外字段。 ## 使用方法 ### 产品翻译 入口: ```text Catalog > Products ``` 可在产品编辑页点击 `Translate`,也可在产品列表行操作中点击 `Translate`。列表顶部的 `Translate` 按钮要求只选择一个产品。 ### CMS Page 翻译 入口: ```text Content > Elements > Pages ``` 可在 Page 编辑页点击 `Translate`,也可在 Page 列表行操作中点击 `Translate`。 应用时,模块会按目标 Store View 查找相同 `identifier` 的 Page: - 找到时更新该 Page 的翻译字段。 - 找不到时创建一个绑定到目标 Store View 的 Page 副本。 - 如果源 Page 绑定 `All Store Views` 且目标副本不存在,会拒绝自动创建,避免 identifier 冲突。 ### CMS Block 翻译 入口: ```text Content > Elements > Blocks ``` 操作方式与 CMS Page 一致。Block 使用相同 `identifier` 和目标 Store View 匹配或创建副本。 ### 翻译工作台 1. 选择语言组,例如 `German: us_DE, de_DE`。 2. 点击语言组旁边的 `Translate`。 3. 弹窗左侧是源内容,右侧是目标语言当前内容。 4. 可人工修改左侧源内容作为本次 AI 输入。 5. 点击弹窗右上角 `Translate` 调用 AI。 6. 检查并修改右侧结果。 7. 点击 `Apply` 写入目标 Store View。 ## HTML 字段处理 产品 `description`、`short_description`,以及 CMS `content` 会按 HTML 处理: 1. 服务端解析 HTML。 2. 只提取可翻译文本节点。 3. 跳过 `script`、`style`、`code`、`pre`。 4. 保护 Magento directive、URL、占位符等内容。 5. AI 只翻译文本节点。 6. 服务端写回原始 DOM 结构。 7. 应用前重新校验 HTML。 应用前会拦截危险 HTML,例如 `