企业官网建设流程全解析

如何给 GitHub MCP Server 配上多语言：完整落地指南

【免费下载链接】github-mcp-serverGitHub's official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server

团队里有人反馈：AI 助手列出来的那上百个工具，说明全是英文，新人根本读不懂。想让这些工具描述变成中文、日文，要改源码吗？不用。GitHub MCP Server 的国际化机制其实是一套「三层覆盖」的文本替换系统：代码里每个文案都绑了一个翻译键，你在环境变量或配置文件里给这个键换值，工具描述就跟着变。下面把它的规则、落地方式和常见坑一次讲清，照着做十分钟就能让 MCP Server 中文配置生效。

一张图看懂：谁的词说了算

先建立心智模型：每段文案只有一个生效值，来源按「环境变量 > JSON 配置文件 > 代码默认值」的顺序依次覆盖。高优先级有值就用它，没值就落到下一层。

记住这一点：翻译键就是这套机制里的「挂钩」。键名对上了，换语言就是改配置的事，一行代码都不用动。

机制拆解：键名长什么样，查找走什么顺序

核心实现只有一个小文件：pkg/translations/translations.go。TranslationHelper()返回一个函数，任何工具在注册时都会带上这个函数来取文案。拿 pkg/github/git.go 里的「获取仓库树」工具为例：

Description: t("TOOL_GET_REPOSITORY_TREE_DESCRIPTION", "Get the tree structure (files and directories) of a GitHub repository..."), Title: t("TOOL_GET_REPOSITORY_TREE_USER_TITLE", "Get repository tree"),

两句话点破它：第一个参数是翻译项，第二个参数是兜底的英文默认值。键名的拼写规律是TOOL_+ 大写工具名 + 后缀，后缀决定翻译的是哪段文字：

查找顺序用一个生活化的比喻：像点外卖时「先看你备注写了什么（环境变量），没写就按店铺会员卡的默认口味（配置文件），还没有就按菜单默认（代码兜底值）」。环境变量之所以排第一，是因为它在容器、CI 这类环境里最方便临时注入，不用带文件；配置文件适合把一整套翻译固化下来随仓库走。

查找完成后结果会写进一个内存 map，同一个键第二次取就直接命中缓存，不再重复查环境变量和配置文件。

三种方式给 MCP Server 换语言（可直接复制）

方式一：环境变量（改单条最快）

export GITHUB_MCP_TOOL_GET_COMMITS_DESCRIPTION="获取GitHub仓库中提交的详细信息" export GITHUB_MCP_TOOL_GET_COMMITS_USER_TITLE="获取提交详情" ./github-mcp-server

规则就一条：把翻译键整体加上GITHUB_MCP_前缀，值想写什么语言写什么语言。

方式二：JSON 配置文件（整套固化）

在进程工作目录放一个github-mcp-server-config.json，服务启动时会自动读入：

{ "TOOL_GET_COMMITS_DESCRIPTION": "获取GitHub仓库中提交的详细信息", "TOOL_GET_COMMITS_USER_TITLE": "获取提交详情", "TOOL_LIST_BRANCHES_DESCRIPTION": "列出GitHub仓库中的所有分支" }

文件名和位置是写死的（当前目录、固定文件名），不需要额外配置项。

方式三：混合部署（容器场景推荐）

配置文件挂载进容器作为基线，个别键再用环境变量临时覆盖：

docker run \ -v $(pwd)/github-mcp-server-config.json:/app/github-mcp-server-config.json \ -e GITHUB_MCP_TOOL_GET_COMMITS_USER_TITLE="提交详情（内测）" \ ghcr.io/github/github-mcp-server

这样翻译基线可版本管理，灰度实验又不污染文件。

踩坑实录：配了却没生效怎么办

🛠️ 踩坑前先看这里。四个高频问题，每个配一条排查命令。

坑一：前缀拼错，配置形同虚设。键必须带GITHUB_MCP_前缀，写成TOOL_XXX直接不生效。排查：

env | grep GITHUB_MCP_

坑二：键名抄错字母。翻译项对不上时静默落回英文，没有任何报错。把键名和源码里的原文对一遍：

grep -rn "TOOL_GET_COMMITS" pkg/github/

坑三：配置文件没被加载。两个隐藏条件：文件名必须是github-mcp-server-config.json，且必须在进程的工作目录下。用 Docker 时容器的工作目录未必是/app。排查：

docker run --rm --entrypoint pwd 镜像名

坑四：改了环境没重启。缓存按进程生命周期待生效，改了环境变量必须重启服务，热改不会刷新已缓存的键。

边界与性能：缓存的取舍与不适用场景

内存上几乎可以忽略：每个键只存一个字符串，几百个工具撑死几 KB，缓存命中率随启动后的工具注册快速拉满，对性能是净收益。真正要认清的是它的适用边界：

• 启动时定死，不支持运行时切换语言。想在同一个服务上让中文用户看到中文、日文用户看到日文，这套机制做不到，因为它没有按请求解析语言的能力（也没有读Accept-Language的逻辑）。多语言并存只能起多个实例，各自注入一套配置。
• 只翻译文案，不翻译数据。Issue 标题、PR 描述、代码搜索结果都是 GitHub 返回的原始内容，换语言后依旧是原样。
• 翻译是「覆盖」不是「字典」。你没配的键永远显示英文，没有缺省回退到某门语言再回退到英文的多级机制。

往后的路

这套「键 + 三层覆盖」的设计轻到只依赖一个函数签名，却把文案的归属权从代码彻底让渡给了运维配置，这是它最值得学的地方。可以预期后续演进方向是运行时语言协商和翻译键的自动清单导出——其实代码里已经埋了伏笔：helper 的清理函数会把全部翻译键 dump 成 JSON，等于自带了「导出待翻译键清单」的能力。对使用者来说，当下最实用的路径就是把 pkg/translations/translations.go 的规则记牢，先用环境变量把最关键的几个工具换成中文，再逐步把整套配置固化成文件——多语言这件事，从这个项目开始，真的只是改配置的事。

【免费下载链接】github-mcp-serverGitHub's official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server