5.8 KiB
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 匹配或创建副本。
翻译工作台
- 选择语言组,例如
German: us_DE, de_DE。 - 点击语言组旁边的
Translate。 - 弹窗左侧是源内容,右侧是目标语言当前内容。
- 可人工修改左侧源内容作为本次 AI 输入。
- 点击弹窗右上角
Translate调用 AI。 - 检查并修改右侧结果。
- 点击
Apply写入目标 Store View。
HTML 字段处理
产品 description、short_description,以及 CMS content 会按 HTML 处理:
- 服务端解析 HTML。
- 只提取可翻译文本节点。
- 跳过
script、style、code、pre。 - 保护 Magento directive、URL、占位符等内容。
- AI 只翻译文本节点。
- 服务端写回原始 DOM 结构。
- 应用前重新校验 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=".renditions/wysiwyg/product_details/demo.png"}}会在 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
后台手工测试:
- 配置并启用模块。
- 配置至少一个目标语言组。
- 分别从产品、CMS Page、CMS Block 打开翻译工作台。
- 点击语言组
Translate,确认字段加载正常。 - 点击弹窗内
Translate,确认 AI 返回后右侧字段被填充。 - 修改右侧内容并点击
Apply。 - 切换目标 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/* 配置路径。