Files
2026-09-15 10:35:56 +08:00

5.8 KiB
Raw Permalink Blame History

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 根目录:

app/code/Esun/Translation

执行:

php bin/magento module:enable Esun_Translation
php bin/magento setup:upgrade
php bin/magento cache:flush

生产模式下再执行:

php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

确认模块状态:

php bin/magento module:status Esun_Translation

后台配置

入口:

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 映射,每行一个语言组。

语言组格式:

语言名称|目标语言代码|store_code_1,store_code_2

示例:

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:

{"translations":{"field_key":"translated text"}}

服务端会校验所有请求字段必须存在,且不得返回额外字段。

使用方法

产品翻译

入口:

Catalog > Products

可在产品编辑页点击 Translate,也可在产品列表行操作中点击 Translate。列表顶部的 Translate 按钮要求只选择一个产品。

CMS Page 翻译

入口:

Content > Elements > Pages

可在 Page 编辑页点击 Translate,也可在 Page 列表行操作中点击 Translate。

应用时,模块会按目标 Store View 查找相同 identifier 的 Page:

  • 找到时更新该 Page 的翻译字段。
  • 找不到时创建一个绑定到目标 Store View 的 Page 副本。
  • 如果源 Page 绑定 All Store Views 且目标副本不存在,会拒绝自动创建,避免 identifier 冲突。

CMS Block 翻译

入口:

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,例如 <script>、事件属性、javascript: URL、损坏的 Magento directive。

1.2.2 修复了 Magento media directive 在 HTML 属性中被 DOM 解析器改写的问题,例如:

  • {{media url=wysiwyg/precision.png}} 不会再被转成 %7B%7Bmedia%20url=wysiwyg/precision.png%7D%7D。
  • {{media url=&quot;.renditions/wysiwyg/product_details/demo.png&quot;}} 会在 directive 内还原为 {{media url=".renditions/wysiwyg/product_details/demo.png"}}。

权限

新增 ACL:

Esun_Translation::config
Esun_Translation::translate_product
Esun_Translation::apply_product_translation
Esun_Translation::translate_cms_page
Esun_Translation::apply_cms_page_translation
Esun_Translation::translate_cms_block
Esun_Translation::apply_cms_block_translation

如管理员看不到按钮,请检查:

System > Permissions > User Roles

验证方法

PHP 语法检查:

find app/code/Esun/Translation -name "*.php" -print0 | xargs -0 -n1 php -l

Windows PowerShell:

Get-ChildItem -Recurse -Filter *.php app\code\Esun\Translation | ForEach-Object { php -l $_.FullName }

单元测试:

php vendor/bin/phpunit app/code/Esun/Translation/Test/Unit

后台手工测试:

  1. 配置并启用模块。
  2. 配置至少一个目标语言组。
  3. 分别从产品、CMS Page、CMS Block 打开翻译工作台。
  4. 点击语言组 Translate,确认字段加载正常。
  5. 点击弹窗内 Translate,确认 AI 返回后右侧字段被填充。
  6. 修改右侧内容并点击 Apply。
  7. 切换目标 Store View 检查产品字段或 CMS 副本内容。

卸载

php bin/magento module:disable Esun_Translation
php bin/magento setup:upgrade
php bin/magento cache:flush

删除代码目录:

app/code/Esun/Translation

本模块不创建数据库表。旧 Evebit_ProductTranslation 配置会在 setup:upgrade 时自动复制到新的 esun_translation/* 配置路径。