企业官网建设流程全解析

LibreTranslate 离线翻译 API 部署教程：三步搞定断网环境可用的本地机器翻译

【免费下载链接】LibreTranslateFree and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.项目地址: https://gitcode.com/GitHub_Trending/li/LibreTranslate

网络一断，依赖云端接口的翻译服务立刻罢工；气闸隔离的内部环境，按合规要求本来就不许调用外部 API；出差驻场时，你总不能指望流量去翻技术文档。好消息是，LibreTranslate 这个免费开源的机器翻译 API 天生就是自托管、可离线设计的——语言模型落到本地之后，服务不再触碰任何外部接口。

读完这篇，你可以：

• 按语言对挑选模型，避免几 GB 的全量下载
• 在完全无网的目标机器上装好全部 Python 依赖
• 让/translate和/detect两个接口在本地端口跑起来，并用 curl 验证

一、先选路：动手前把路线定好

选对路，比跑得快更重要。

💡 提示：三条路线的差异只在“模型下载”这一步放在哪台机器做，后面的用法完全一样。

二、环境自检

先自检，能省掉后面一半排障时间。

路线 B 需要两台机器：一台打包机（有网），一台目标机（无网）。核心依赖版本可在 pyproject.toml 里核对：翻译引擎为argos-translate-lt==1.12.1，Web 框架 Flask 2.2.5。

三、按步执行

整个流程里唯一的联网窗口是第 2 步，其余全部可以离线完成。

第 1 步：获取源码并装好主程序

本步目标：在打包机上拿到 v1.9.6 源码，且不污染系统环境。

# 克隆源码并创建独立虚拟环境 git clone https://gitcode.com/GitHub_Trending/li/LibreTranslate cd LibreTranslate python -m venv venv

# 激活环境并安装主程序（Windows 用 venv\Scripts\activate） source venv/bin/activate pip install .

如何确认成功：pip show libretranslate输出Version: 1.9.6。

第 2 步：选择性下载语言模型（关键离线步骤）

本步目标：只下载你要的语言对，把体积压下来——这步必须在有网时完成。

# 只下载英、中、法之间的互译模型 python scripts/install_models.py --load_only_lang_codes "en,zh,fr"

如何确认成功：日志出现Loaded support for X languages (Y models total)!，且~/.local/share/argos-translate目录下出现模型文件（Windows 在%LOCALAPPDATA%\argos-translate）。

⚠️ 注意：语言代码写错会直接报错Unavailable language codes: xx。对照 libretranslate/locales/ 下的目录名核对，如zh、fr、ja。不传参数裸跑则下载全量模型，占用数 GB。

第 3 步：把依赖和模型打成离线包

本步目标：把“装的时候要联网的东西”全部变成文件。

# 导出依赖清单并下载所有 wheel 到本地目录 pip freeze > requirements.txt pip download -r requirements.txt -d wheels/

# 把模型复制进项目，然后打包源码+wheel+模型 cp -r ~/.local/share/argos-translate ./models tar -czf lt-offline.tar.gz --exclude='venv' --exclude='.git' .

如何确认成功：ls -lh lt-offline.tar.gz看到压缩包（体积以实际输出为准）；tar -tzf lt-offline.tar.gz | head能看到wheels/和models/都在里面。

⚠️ 注意：wheel 是平台相关的。打包机的操作系统和架构必须与目标机一致，否则第 4 步会缺包，只能回打包机重新pip download。

第 4 步：离线机上安装并验证服务

本步目标：在断网环境把服务跑通，确认翻译、检测接口可用。

先把压缩包传到目标机解压，然后：

# 恢复模型到 Argos 默认读取位置 mkdir -p ~/.local/share cp -r models ~/.local/share/argos-translate

# 重建环境、仅从本地 wheel 安装、启动服务 python -m venv venv && source venv/bin/activate pip install --no-index --find-links=wheels/ . python main.py --host 127.0.0.1 --port 5000

如何确认成功：启动日志出现Loaded support for X languages...!。然后另开终端：

# 调翻译接口：英文翻中文 curl -X POST http://127.0.0.1:5000/translate \ -d "q=Hello world&source=en&target=zh"

响应里translatedText是正确译文，即通过。再顺手验证语言检测和语言列表：

# 检测语言 + 查看已装语言列表 curl http://127.0.0.1:5000/detect -d "q=Bonjour tout le monde" curl http://127.0.0.1:5000/languages

前者应识别出fr，后者返回你第 2 步选的语言集合。

第 5 步（路线 C）：用 Docker 替代手工打包

本步目标：目标机有 Docker 时，跳过手工装依赖，直接交付“代码+模型”镜像。

# 在打包机构建只含中、英、法模型的镜像 docker build -t lt-offline:1.9.6 -f docker/Dockerfile \ --build-arg with_models=true --build-arg models="en,zh,fr" .

# 导出镜像文件 → 传到离线机 → 加载 → 启动 docker save lt-offline:1.9.6 -o lt-offline.tar docker load -i lt-offline.tar docker run -d -p 5000:5000 --name lt lt-offline:1.9.6

如何确认成功：docker logs lt出现Loaded support for X languages...!，宿主机 curl 5000 端口能拿到译文。

⚠️ 注意：docker/Dockerfile 基于python:3.11.14-slim，无网机需要先把这个基础镜像用docker save/load搬过去，构建时同样要联网拉包。

四、排障：常见报错修复

离线环境八成是“哪份文件没拷过来”这类问题。

症状：启动时看到Cannot update models (normal if you're offline)最可能原因：libretranslate/init.py 尝试刷新远端模型索引被断网挡住，是提示不是错误解决命令：无需处理；确认UPDATE_MODELS为默认 False 即可（见 libretranslate/default_values.py）

症状：下载模型时报ValueError: Unavailable language codes: xx最可能原因：语言代码不在 Argos 包列表里解决命令：先跑python scripts/install_models.py --load_only_lang_codes "en,zh"单对验证，再逐个加

症状：离线机启动后语言列表为空、翻译报语言不支持最可能原因：模型没有恢复到~/.local/share/argos-translate解决命令：ls ~/.local/share/argos-translate确认为空时，重跑第 4 步的cp -r models ~/.local/share/argos-translate

症状：Address already in use最可能原因：5000 端口被占用解决命令：python main.py --port 5001换端口（环境变量LT_PORT等效）

症状：pip install --no-index报找不到依赖最可能原因：wheel 是在不同操作系统/架构的机器上下的解决命令：回到与目标机同平台的打包机，重新执行第 3 步的pip download再打包

五、进阶优化（可选，非必做）

服务跑稳是第一目标，优化是锦上添花，以下都不做也完全能上线。

六、上线前清单

上线前，把下面几项逐条过一遍：

• 启动日志出现Loaded support for X languages，数量与所选语言对一致
• /translate、/detect、/languages三个接口均正常响应
• 拔掉网线重启一次，服务仍然可用
• UPDATE_MODELS保持 False，不会偷偷尝试连远端
• 长期对外使用时已配置LT_REQ_LIMIT、LT_CHAR_LIMIT防滥用

版本与更新方式：版本号记录在 VERSION（当前 1.9.6），建议离线包按“版本号+日期”命名，例如lt-offline-1.9.6-20250901.tar.gz。需要升级时，在有网机器上跑python scripts/install_models.py --update --load_only_lang_codes "en,zh,fr"增量更新模型，再把新的models/目录重新压缩成一个小更新包传过去替换即可，不必重建整个离线包。

【免费下载链接】LibreTranslateFree and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.项目地址: https://gitcode.com/GitHub_Trending/li/LibreTranslate