一、语言包格式规范
MaxKB v2.10.0-lts 支持自定义国际语言包，语言包统一为 ZIP 压缩包格式，拥有严格的命名与文件结构规范，所有文件名称必须保持一致，否则语言包无法生效。
1.1 命名规则
-
语言包整体压缩包名称：国际语言代码.zip
-
压缩包内部必须包含两个文件：国际语言代码.json、国际语言代码.po
-
核心要求：ZIP 压缩包名称、JSON 文件名称、PO 文件名称必须完全一致
1.2 示例说明
以德语为例，德语国际语言代码为 de：
-
语言包压缩包：
de.zip -
包内文件：
de.json、de.po
1.3 语言代码查询方式
目标语言对应的标准国际语言代码（ISO 639 语言码），可通过官方查询网站获取：
https://www.udtool.com/toolbox/langcodes.html
二、自定义语言包制作步骤
MaxKB 默认提供中文语言包，可基于中文语言包快速制作任意国际语言包，具体步骤如下：
步骤1：查询目标语言代码
打开上方语言代码查询网址，查找需要适配的目标语言对应的纯字母国际语言代码（如英语：en、日语：ja、韩语：ko）。
步骤2：解压并翻译源语言包
解压 MaxKB 原始中文语言包，复制包内的 zh.json 和 zh.po 源文件，将文件内所有中文文本逐条翻译为目标语言文本，保证语义准确、适配系统界面场景。
步骤3：重命名语言包文件
将翻译完成的两个文件，重命名为目标语言国际代码格式，严格遵循命名规范：
-
原文件：zh.json、zh.po
-
修改后：xx.json、xx.po（xx 为目标语言代码）
步骤4：打包生成自定义语言包
将重命名后的 xx.json、xx.po 两个文件，压缩为同名 ZIP 压缩包，最终生成 xx.zip 格式的自定义语言包。
三、语言包部署安装方法
自定义语言包制作完成后，需放置到 MaxKB 指定的语言包目录，分为原生部署和Docker 容器部署两种场景。
3.1 原生部署（服务器直接安装）
-
进入 MaxKB 安装目录的语言包文件夹，默认路径：
/opt/maxkb/local/locales -
若该目录不存在，可手动创建目录：
mkdir -p /opt/maxkb/local/locales -
将制作好的
xx.zip自定义语言包，放入该目录下
3.2 Docker 镜像部署
Docker 部署需通过目录映射，将宿主机语言包同步至容器内部指定目录，操作如下：
-
在宿主机创建语言包目录（可自定义路径），放入自定义语言包 ZIP 文件
-
启动/重启容器时，添加目录挂载参数，将宿主机目录映射至容器内：
容器固定语言包路径：/opt/maxkb/local/locales -
若容器内无
/opt/maxkb/local/locales目录，可进入容器手动创建
四、生效方式
语言包放置完成后，必须 重启 MaxKB 服务，重启完成后，即可在 MaxKB 系统后台的语言切换选项中，选择并使用自定义的国际语言。
五、注意事项
-
严格保证 压缩包、json文件、po文件三者名称完全一致，大小写需统一，否则语言包无法识别
-
仅支持标准 ISO 639 国际语言代码，不可自定义非标准代码
-
翻译内容需适配系统界面、按钮、提示文本等场景，避免语义错乱
-
Docker 部署务必保证目录挂载生效，否则容器无法读取自定义语言包