Files
esun3d/app/code/Esun/Translation/README_CN.md
T
2026-09-15 10:35:56 +08:00

224 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/*` 配置路径。