224 lines
5.8 KiB
Markdown
224 lines
5.8 KiB
Markdown
# 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=".renditions/wysiwyg/product_details/demo.png"}}` 会在 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/*` 配置路径。
|