This commit is contained in:
2026-09-15 10:35:56 +08:00
commit 782f8ea7aa
4086 changed files with 631288 additions and 0 deletions
+223
View File
@@ -0,0 +1,223 @@
# 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,例如 `<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:
```text
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
```
如管理员看不到按钮,请检查:
```text
System > Permissions > User Roles
```
## 验证方法
PHP 语法检查:
```bash
find app/code/Esun/Translation -name "*.php" -print0 | xargs -0 -n1 php -l
```
Windows PowerShell:
```powershell
Get-ChildItem -Recurse -Filter *.php app\code\Esun\Translation | ForEach-Object { php -l $_.FullName }
```
单元测试:
```bash
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 副本内容。
## 卸载
```bash
php bin/magento module:disable Esun_Translation
php bin/magento setup:upgrade
php bin/magento cache:flush
```
删除代码目录:
```text
app/code/Esun/Translation
```
本模块不创建数据库表。旧 `Evebit_ProductTranslation` 配置会在 `setup:upgrade` 时自动复制到新的 `esun_translation/*` 配置路径。