﻿内容级多语言说明
================================================================================
注意：这里说的是「内容」多语言（同一条视频/文章/分类给不同语言的访客展示不同的
名称、简介、正文……），与「界面语言包」（application/lang/ 下 admin 后台文案）是
两套独立的东西，配置项也不同，不要混淆。


一、这个功能做了什么
--------------------------------------------------------------------------------
1. 新增一张表 mac_content_lang，按 (content_type, content_id, lang_code) 一行，
   存 Vod/Art/Manga/Topic/Type/Link/Task/Actor/Website/Live 的可翻译字段（整体
   一段 JSON）；播放器/下载器/服务器组这类不落库的配置，译文就近存在
   application/extra/vod{player,downer,server}.php 各条目里。
2. 系统设置里新增「前台内容语言」配置：一个默认语言 + 一份已启用语言清单
   （System → 网站参数，配置键 content_lang_default / content_lang_list）。
3. 前台按 ?lang=xx-xx → cookie(mac_content_lang，30 天) → Accept-Language →
   默认语言 的顺序决定当前访客看到的语言。
4. 后台各模块编辑页在启用 2 种及以上语言时，按语言分标签页：默认语言那一页还是
   原来的表单字段（name 属性不变，老的采集/导入照常工作），其它语言页提交到
   content_lang[语言代码][字段名]，与主表单一次性一起保存。
5. 可选钩子 content_translate：装了对应「自动翻译」插件后，各字段旁出现「自动
   翻译」按钮；没装插件按钮不显示，全程手工填写也能用。

对只用单语言的老站是无侵入的：不启用第二语言时，所有表单还是原来的平铺布局，
mac_content_lang_overlay() 也永远原样返回未翻译的原始行。


二、数据库
--------------------------------------------------------------------------------
· 全新安装：无需操作，install.sql 已包含 mac_content_lang。
· 存量站点升级：后台「在线升级」会自动建表（data/update/database.php 里
  if (empty($col_list[$pre.'content_lang'])) { CREATE TABLE ... } 增量判断），
  无需手动执行 SQL。
· 不改动任何现有表；默认语言的内容仍然存在 mac_vod / mac_art / … 原处，只有
  其它语言的译文进新表。


三、开启方法
--------------------------------------------------------------------------------
1. 后台 → 系统 → 网站参数，找到「前台内容语言」区块：一组语言复选框
   （content_lang_list）+ 默认内容语言单选（content_lang_default，默认 zh-cn）。
2. 勾选希望访客能切换的语言。默认语言总是隐含包含，不必单独勾。
3. 保存即生效，无需清缓存或重启。
   · 启用 0 或 1 种语言：后台表单维持原平铺布局，编辑体验完全不变。
   · 启用 2 种及以上：上述模块编辑页出现语言分页签。


四、各模块可翻译字段
--------------------------------------------------------------------------------
技术/配置类字段（URL、ID、颜色、排序、播放来源等）一律不可翻译。
拼音/英文名（*_en）是 URL 重写 slug、首字母（*_letter）是 A-Z 字母筛选键，
前台路由/筛选按库里原值匹配，二者也一律不参与翻译覆盖。当前覆盖：

  Vod      名称、副标题、TAG、备注、扩展分类、简介、详情、
           地区、语言、资源版本、资源类别
  Art      名称、副标题、TAG、备注、扩展分类、简介
  Manga    名称、副标题、TAG、备注、扩展分类、简介、详情
  Topic    名称、副标题、备注、类型、TAG、SEO 标题/关键字/描述、
           简介、详情
  Type     名称、SEO 标题/关键字/描述、扩展分类
  Link     名称
  Task     名称、描述
  Actor    名称、别名、地区、籍贯、星座、毕业院校、备注、代表作、
           TAG、扩展分类、简介、详情
  Website  名称、副标题、地区、语言、TAG、扩展分类、备注、简介、详情
  Live     频道名称、副标题、简介、详情
  服务器组 名称、提示
  播放器   名称、备注、提示
  下载器   名称、备注、提示

明确不在本次范围：Vod 花絮重复项列表、分集播放来源标题（都在单独编码、
带缓存持久化的字符串里，安全翻译需要更大的独立改动）；前台列表/搜索/聚合页
（走 listData()，见第五节）也不做译文覆盖。


五、前台语言切换
--------------------------------------------------------------------------------
访客在任意 URL 加 ?lang=en-us 切换，选择写入 mac_content_lang cookie（30 天），
后续请求不带参数也保持。不在已启用清单里的语言代码静默回退默认语言。
整页 HTML 缓存 key 已带上当前内容语言，各语言互不串台。

生效范围＝详情页 + 分类导航，不含列表/搜索/聚合页：
· 各模块 infoData()（详情页数据入口）返回前把当前语言译文覆盖到行上；某字段没有
  译文时回退默认语言原文（译文允许不完整）。Vod 详情里的线路/播放器/下载器名称、
  提示也按当前语言覆盖（就近取自各条目的 content_lang[语言代码]）。
· 分类（Type）前台走 getCache('type_list' / 'type_tree') 缓存，setCache() 会为每个
  已启用语言各存一份 overlay 过的变体；{maccms:type} 导航标签也带语言维度缓存。
· 但 {maccms:vod}/{maccms:art} 等「列表循环」、站内搜索结果、专题聚合列表走的是
  listData()，不做译文覆盖，一律显示默认语言原文——访客在这些页面看到的仍是原始
  名称，点进详情页才切到所选语言。批量 overlay 列表需要更大的独立改动，不在本次范围。


六、可选：AI 自动翻译插件
--------------------------------------------------------------------------------
非默认语言字段旁的「自动翻译」按钮，仅当某个已安装插件注册了 content_translate
钩子时才显示。插件钩子约定：

    public function content_translate($params)
    {
        // $params: ['text'=>..., 'from'=>'zh-cn', 'to'=>'en-us',
        //           'context'=>['content_type'=>'vod']]
        // 返回译文字符串表示已处理；返回 null 交给下一个插件
    }

本代码库不自带此类插件，这是纯扩展点。后台「自动翻译」动作按管理员做了限流
（默认 40 次/分钟、600 次/小时），未装插件时不计数、直接放行。


七、上线自检
--------------------------------------------------------------------------------
[ ] mac_content_lang 表存在（新装自动；老站在线升级或手动脚本）
[ ] 系统 → 网站参数 能看到语言复选/单选并正常保存
[ ] 启用 2 种及以上语言后，打开任一 Vod/Art/… 编辑页确认出现语言分页签
[ ] 在非默认语言页保存一条译文，重新打开编辑页应能回显
[ ] 前台详情页带 ?lang=<已启用代码> 访问，确认译文生效（留空字段回退原文）
[ ] 前台分类页 / 分类导航切换语言后分类名称随之变化
[ ] 已知预期：列表页/搜索结果里的名称仍是默认语言原文，点进详情才切换——非缺陷
[ ] mac_content_lang 表尚未建（模拟老站未升级）时，后台仍能正常保存 Vod/Art（写译文
    这一步静默跳过，不报 500）
