## Esun MultiLocaleTranslation

这个模块是按你当前需求实现的“低复杂度维护”版：

- 后台支持“按实体弹窗翻译” Product / Category / CMS Page / CMS Block / Mageplaza Blog Post / Wiki Category / Wiki Homepage
- CMS Page / Block / Mageplaza Blog Post / Wiki 使用同一套实体 ID，不复制实体，使用额外翻译表进行同 ID 覆盖
- CMS Page / Block 编辑页提供 `Scope` 切换；切换 Store View 后原生表单直接显示并保存该语言内容
- 先保留现有 Magento 的多语言/多网站机制，只加一个轻量可控的翻译入口
- 支持 DeepL 和 Google Cloud Translation Advanced v3 自动翻译，弹窗可选择 Provider

### 已安装文件说明

- `Block/Adminhtml/*`：后台翻译弹窗和按钮入口
- `Controller/Adminhtml/Translation/*`：获取字段 / 保存字段 API
- `Model/Entity/*`：不同实体的可翻译字段映射
- `Plugin/Cms/*`：前台渲染时把 CMS 翻译覆盖到同一 page/block id
- `Plugin/Blog/*`：前台详情页和博客列表按 Store View 覆盖 Blog Post 译文
- `etc/db_schema.xml`：新增表 `esun_localetranslation_cms`

### 安装与生效（开发/测试环境）

```bash
php bin/magento module:enable Esun_MultiLocaleTranslation
php bin/magento setup:upgrade
php bin/magento cache:flush
```

清缓存后，检查后台：

1. 打开任意商品编辑页、分类编辑页、CMS 页面/区块、Mageplaza Blog Post 或 Wiki 编辑页
2. 页面右上角看到 `Translate` 按钮
3. 点击后在当前编辑页面打开弹窗，并自动加载除源语言外的全部 Store View
4. 也可以重新选择部分 Store View，再点 `Load Fields` 按需加载
5. 点 `Save All Translations`，一次保存当前显示的全部目标 Store View

自动翻译会按 Store View 逐个处理，并显示当前 Store、总进度、成功数和失败数。单个 Store 翻译失败不会中断其余 Store，结束后可根据提示检查失败项。

### 跳过不需要翻译的字段

配置位置：

`Stores > Configuration > Esun > Multi-Locale Translation > General > Skipped Fields`

- 默认不选择任何字段，继续翻译程序当前支持的全部字段。
- 选择后的字段不会出现在翻译弹窗中，也不会进入批量翻译 API 请求、翻译日志或目标 Store View 保存流程。
- 支持分别配置 Category、Product、CMS Page 和 CMS Block 的现有可翻译字段。
- 保存配置并刷新已打开的编辑页面后生效；此设置不会删除以前已保存的译文。

### 业务规则（和你需求一致）

- `entity_type`
  - `product`：商品
  - `category`：分类
  - `cms_page`：CMS 页面（同 `page_id`）
  - `cms_block`：CMS 区块（同 `block_id`）
- 源语言：`source_store_id`
  - 可能是 `0`（默认值）
  - 弹窗会显示 `Default Store View` 或具体 Store View 名称
- 目标语言：`target_store_id`
  - 不能与源语言相同

### CMS Page / Block 原生 Scope

- 默认 Scope 编辑原始 `cms_page` / `cms_block` 数据。
- 选择具体 Store View 后，原生表单显示该 Store View 的翻译内容。
- CMS Page 可翻译 `title`、`content_heading`、`content` 和 SEO 字段。
- CMS Block 可翻译 `title` 和 `content`；`identifier`、启用状态和 Store View 分配继续共用默认数据。
- Mageplaza Blog Post 可翻译 `name`、`short_description`、`post_content` 和 SEO 字段；`url_key`、图片、作者、日期、状态、Store View 和关联数据继续共用默认数据。
- Blog Post 的 `url_key` 永不进入人工翻译、自动翻译或队列保存，因此所有语言继续使用原始 URL。
- Wiki Category 可翻译 `title`、`summary`、`content` 和 SEO 字段；`slug`、`custom_url_path`、层级、状态和功能开关继续共用默认数据。
- Wiki Homepage 可翻译 `title`、`content` 和 SEO 字段；前台会按当前 Store View 读取对应译文。
- 勾选 `Use Default Value` 后保存，会删除该字段的 Store View 翻译并继承默认值。
- Store View Scope 下保存不会修改默认 Page / Block，也不会创建新的 Page / Block ID。

### 数据库（CMS 同ID翻译）

表名：`esun_localetranslation_cms`

字段含义：

- `entity_type`: `page|block|blog_post`
- `entity_id`: CMS page_id、block_id 或 Mageplaza post_id（同站点复用同 ID）
- `store_id`: 目标 Store View ID
- `field_name`: title/content/... 
- `translated_value`: 翻译结果

### Google V3 自动翻译

配置位置：

`Stores > Configuration > Esun > Multi-Locale Translation > Google Cloud Translation`

1. 在 Google Cloud 项目启用 Cloud Translation API。
2. 创建有 Cloud Translation 权限的 Service Account，并下载 JSON Key。
3. 后台上传 Service Account JSON、选择 Location，然后启用 Google 翻译。
4. 翻译弹窗点击 `Google Auto Translate`，检查结果后再点击保存。

JSON Key 会被验证并保存在 Magento `var/esun/multilocale_translation/google/` 私有目录，不会放入 `pub/media` 或输出到浏览器。Google 的所有 HTML 字段都会先提取可见文字、分批翻译，再按原位置写回；Page Builder HTML、CSS、JavaScript 和标签结构不会发送给 Google。
Default Scope 使用后台配置的源语言（默认 `en`）；从具体 Store View 翻译时使用该 Store View 的 Locale。

不使用术语表时 Location 选择 `global`。使用 Google Glossary 时填写 Glossary ID，并把 Location 改为 `us-central1`。

后续增加其他 Provider 时，只需实现 `TranslationProviderInterface` 并注入 `ProviderPool`，实体保存逻辑无需变更。人工填写流程继续保留。

### DeepL 自动翻译

配置位置同样在：

`Stores > Configuration > Esun > Multi-Locale Translation`

1. General 中把 Default Translation Provider 设置为 `DeepL`。
2. 在 DeepL Translation API 中启用 DeepL。
3. API Free 选择 `https://api-free.deepl.com/v2/translate`；API Pro 选择 `https://api.deepl.com/v2/translate`。
4. 填写 DeepL API Key。Key 使用 Magento 加密配置保存，不会输出到浏览器。
5. 翻译弹窗选择 DeepL 并点击 `Auto Translate`。

DeepL 的所有 HTML 字段都会先提取可见文字、分批翻译，再按原位置写回。HTML 标签、注释、CSS、JavaScript、Magento 指令和编码后的代码块不会发送给 DeepL；文字片段使用 `tag_handling=html` 和 v2 标签算法。

### Translation API Log

后台菜单 `Esun > Translation API Log` 显示每个自动翻译字段的调用记录，包括：

- Provider、成功/失败状态、实体类型、实体 ID 和字段名
- 源/目标 Store View 与语言
- 原文、译文、字符数和调用时间
- 失败请求的错误信息（在 Columns 中打开 `Error` 列）

日志支持筛选、分页、列显示控制和批量删除。日志仅记录点击 `Auto Translate` 产生的结果；人工编辑和最终保存不重复记录。
HTML 字段的日志只保存和显示实际送去翻译的可见文字，不记录 Page Builder HTML、CSS、JavaScript 等结构代码；历史日志在列表显示时也会自动提取可见文字。
`Clear All Logs` 可在二次确认后一次清空全部 Translation API Log，不会删除队列或已保存译文。

### Batch Translation Queue

- Product、CMS Page、CMS Block、Mageplaza Blog Post 列表的批量操作中选择 `Add to Translation Queue`。
- Category 可在原生分类树中勾选多个节点后点击 `Translate Selected`，也可以在后台 `Esun > Batch Translation` 输入多个 Category ID。
- Wiki Category 可在 Wiki 分类列表勾选多个节点后点击 `Add Selected to Translation Queue`，再选择目标 Store Views 和翻译服务加入队列。
- 在确认页面选择 Source Store View、一个或多个 Target Store View 和 Provider。
- 每个“实体 × Target Store View”生成一条数据库队列任务；重复的 Pending/Processing 任务会跳过。
- Magento Cron 默认每分钟最多处理 10 条任务，并在约 50 秒后停止领取新任务；当前任务会执行完成。可在 `Esun > Translation Management > Configuration > Translation Queue` 调整（数量 1–50，时间 10–300 秒）。
- `Esun > Translation Queue` 查看 Pending、Processing、Success、Failed、执行次数和错误信息。
- Failed 任务可批量 `Retry Failed`，非 Processing 任务可批量删除。
- `Clear All Queue` 可在二次确认后清空所有队列记录；已被 Cron 取走并正在执行的任务无法中断，仍可能完成翻译写入。

队列依赖 Magento Cron。服务器必须已经配置每分钟执行：

```bash
* * * * * php /path/to/magento/bin/magento cron:run 2>&1 | grep -v "Ran jobs by schedule" >> /path/to/magento/var/log/magento.cron.log
```

开发环境可手动执行一次 `php bin/magento cron:run`；若服务器没有 Magento Cron，任务会保持 Pending，不会丢失。

### 注意

- 插件不会改写现有 URL 或多站点主站映射逻辑
- 不建议与已有同名翻译覆盖逻辑并行写入 CMS 同字段，避免内容互相覆盖