x1ao4/chinese-localization-for-plex

Chinese Localization for Plex 镜像文档

镜像概述和主要用途

Chinese Localization for Plex（简称CLP）是一款针对Plex服务器的中文本地化工具，通过与Plex服务器交互，对媒体库中的电影、电视节目、艺人、专辑、曲目和合集等元数据进行处理。核心功能包括将中文标题转换为拼音首字母缩写以实现拼音排序和搜索，以及将英文标签（类型、氛围、风格等）汉化为中文，从而优化中文媒体库的管理和使用体验。

核心功能和特性

核心功能

• 拼音排序与搜索：将电影、电视节目、艺人、专辑、曲目、合集的标题排序字段转换为拼音首字母缩写，支持按拼音首字母排序和搜索（含模糊搜索），不影响中文标题显示
• 标签汉化：将媒体项目的英文标签（类型、氛围、风格等）自动转换为中文，如"Action"→"动作"、"Comedy"→"喜剧"

处理模式

• 处理所有项目（all）：对指定资料库中的所有项目进行处理，已处理或无需处理的项目会被跳过
• 处理新增项目（new）：通过Webhooks监听Plex服务器事件，实时处理新增项目（需Plex Pass订阅）

使用场景和适用范围

适用于所有使用Plex服务器管理中文媒体库的用户，尤其适合中文媒体内容较多、需要按拼音排序和搜索，或希望标签显示为中文的用户。无论是个人媒体库还是小型共享服务器，均可通过该工具提升中文内容的管理效率和使用体验。

详细的使用方法和配置说明

运行条件

• 已安装Docker和Docker Compose

Docker Compose配置

Plex Pass订阅用户

yaml
version: "2"
services:
  clp-scheduler:
    image: mcuadros/ofelia:latest
    container_name: clp-scheduler
    depends_on:
      - clp-all
    command: daemon --docker -f label=com.docker.compose.project=${COMPOSE_PROJECT_NAME}
    labels:
      ofelia.job-run.clp-all.schedule: 0 30 22 * * *
      ofelia.job-run.clp-all.container: clp-all
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped
  clp-all:
    image: x1ao4/chinese-localization-for-plex:latest
    container_name: clp-all
    command: python chinese-localization-for-plex.py --all
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /自定义目录/chinese-localization-for-plex/config:/app/config
  clp-new:
    image: x1ao4/chinese-localization-for-plex:latest
    container_name: clp-new
    command: python chinese-localization-for-plex.py --new
    ports:
      - 8088:8088
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /自定义目录/chinese-localization-for-plex/config:/app/config
    restart: unless-stopped
networks: {}

非Plex Pass订阅用户

yaml
version: "2"
services:
  clp-scheduler:
    image: mcuadros/ofelia:latest
    container_name: clp-scheduler
    depends_on:
      - clp-all
    command: daemon --docker -f label=com.docker.compose.project=${COMPOSE_PROJECT_NAME}
    labels:
      ofelia.job-run.clp-all.schedule: 0 30 22 * * *
      ofelia.job-run.clp-all.container: clp-all
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped
  clp-all:
    image: x1ao4/chinese-localization-for-plex:latest
    container_name: clp-all
    command: python chinese-localization-for-plex.py --all
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /自定义目录/chinese-localization-for-plex/config:/app/config
networks: {}

配置文件说明

配置文件路径：/config/config.ini，需配置以下参数：

ini
[server]
# Plex服务器地址，格式为http://IP:32400或http(s)://域名:端口
address = http://127.0.0.1:32400
# Plex服务器认证token（X-Plex-Token）
token = xxxxxxxxxxxxxxxxxxxx
# 需要跳过的资料库，多个库名用分号分隔，无则留空
skip_libraries = 云电影；云电视剧；演唱会

标签映射文件：/config/tags.json，预置常用影视类型标签的中英翻译，可自行添加其他标签映射，保持JSON格式一致。

使用步骤

1. Plex Pass用户：在Plex服务器设置→Webhooks中添加Webhook地址http://Docker所在设备IP:8088并保存（非Plex Pass用户跳过此步）
2. 下载对应Compose文件，保存至chinese-localization-for-plex目录
3. 编辑Compose文件，将/自定义目录/chinese-localization-for-plex/config替换为宿主机实际目录
4. 终端切换至Compose文件目录，执行docker-compose up -d启动服务
5. 编辑宿主机配置目录下的config.ini，填写Plex服务器地址和token
6. 重启服务使配置生效：docker-compose restart

运行说明

• clp-all容器：执行"处理所有项目"任务，运行一次后停止。可通过手动启动或计划任务触发，处理指定范围内所有项目
• clp-new容器：（Plex Pass用户）创建Flask服务器监听8088端口，接收Plex Webhook事件，实时处理新增项目，持续运行
• clp-scheduler容器：管理计划任务，默认每天22:30触发clp-all运行，可通过修改labels中的schedule表达式自定义频率（如"@every 3h"表示每3小时运行一次）

注意事项

• 确保Plex服务器地址和token正确，使用管理员账号token以获取足够权限
• 库名需与Plex中完全一致，多个库名用分号分隔
• 网络问题：若无法连接Plex服务器，检查网络或尝试使用host网络模式部署
• 标题含日文假名的项目会被跳过拼音排序处理
• 处理后的字段会被锁定，防止元数据刷新时重置；需修改时需手动解锁
• 修改配置文件后需重启容器使配置生效
• 使用"处理新增项目"模式时，确保Plex服务器设置→网络中已勾选Webhooks选项