企业官网建设流程全解析

1. Angular 多语言项目里 i18n-ally 到底解决什么问题

如果你正在维护一个 Angular 项目，早期只做了中文，现在要加英文、日文甚至更多语种，最头疼的往往不是写代码，而是文案散落各处：模板里有{{ 'Layout.Personal' | translate }}，组件里有this.translate.instant('WorkSpace.Prompt.History.Copy.Success')，弹窗、表单校验、Toast 提示各写各的。等到要补一份en-US.json，你根本不知道哪些 key 已经存在、哪些漏了、哪些拼错了。

i18n-ally 就是 VS Code 里专门管这件事的插件。它能做什么？简单说三件事：第一，扫描你项目里的国际化调用，把用到的 key 和语言包 JSON 做比对；第二，在代码里直接内联显示当前语言对应的文案，鼠标悬停就能看到所有语种；第三，缺翻译、key 拼错、语言包结构不一致时给你下划线提示，点一下快速修复。适合谁？适合所有用 Angular + ngx-translate（或类似方案）做多语言、又不想手动维护 JSON 的团队。

我试过在一个中型 Angular 后台里，语言包从 300 多个 key 涨到 900 多个，纯靠人肉对 JSON 基本会崩。i18n-ally 把「提取文案 → 写入 JSON → 翻译 → 校验」这条链路压缩到编辑器内完成，效率提升非常明显。而翻译这一步，如果每次都要手动复制到网页翻译工具再贴回来，依然很碎。所以这篇会把 TaoToken 作为统一的模型调用通道接进来，让 i18n-ally 的翻译辅助流程有一个稳定的 Key 出口。

核心检索词先明确：i18n-ally 是 VS Code 插件，Angular 国际化靠 JSON 语言包，i18n-ally 配置写在.vscode/settings.json，翻译辅助走 OpenAI 兼容接口。下面从目录约定开始，一步步把配置、接入、验证、排障讲清楚。

2. TaoToken 前置准备：统一 Key 通道接入翻译辅助

在讲配置之前，先把「Key 从哪来」这件事说清楚。i18n-ally 的翻译功能支持调用 OpenAI 兼容接口，你需要填一个apiKey和一个apiModel。如果每个项目、每个同事都各自去申请、各自填一份 Key，管理会非常乱，额度也难统计。TaoToken 在这里的角色就是一个统一的模型调用通道：你拿到一个 Key，配好 Base URL，就能在 i18n-ally 里调用模型做翻译辅助。

先做前置准备。打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册并登录后进入控制台。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在里面可以创建 API Key。创建完记得复制保存，Key 一般只显示一次。

拿到 Key 之后，你需要知道两个地址：

• Base URL：https://taotoken.net/api（注意这个不加 UTM，直接用于配置）
• API Key：控制台里生成的那串

模型 ID 方面，i18n-ally 的apiModel字段填你实际要用的模型名即可，比如常见的对话模型 ID。如果你不确定当前有哪些可用模型，可以到模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 里先试一下，确认模型能正常返回，再填进配置。

这里要强调一个点：i18n-ally 调用的是 OpenAI 兼容的/v1/chat/completions风格接口。TaoToken 的 API 地址是https://taotoken.net/api，在 i18n-ally 里通常需要填成带/v1的完整形式，具体以插件字段要求为准。如果插件只让你填 Base URL，那就填https://taotoken.net/api/v1；如果它要求填完整 endpoint，就补全到/chat/completions。这一点在后面的配置片段里会写清楚。

另外，如果你后续要做更长期的编码辅助、Agent 流程，可以了解 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它和 i18n-ally 的翻译辅助是两条线，前者偏长期编码，后者偏语言包翻译，按需使用。

前置准备做完，你手里应该有三样东西：Base URL、API Key、Model ID。这三件套是后面所有配置的基础，缺一不可。很多人卡在 401，就是因为 Key 没填对或者 Base URL 少了/v1。

3. 可复制配置：i18n-ally + Angular 目录约定

这一节是全文最核心的可复制部分。先约定 Angular 项目的目录结构，再给.vscode/settings.json的完整片段。

Angular 项目里，语言包一般放在src/assets/i18n/下，文件名按 locale 命名，比如zh-CN.json、en-US.json、ja-JP.json。ngx-translate 的 loader 通常这样写：

export function createTranslateLoader(http: HttpClient) { return new TranslateHttpLoader(http, './assets/i18n/', '.json'); } TranslateModule.forRoot({ defaultLanguage: 'zh-CN', loader: { provide: TranslateLoader, useFactory: createTranslateLoader, deps: [HttpClient], }, });

对应的 JSON 结构建议用嵌套（nested）风格，比如：

{ "Layout": { "Personal": "个人中心" }, "WorkSpace": { "Message": { "Error": "操作失败" }, "Prompt": { "History": { "Copy": { "Success": "复制成功" } } } } }

现在写.vscode/settings.json。这个文件放在项目根目录的.vscode文件夹里，团队共享，保证每个人打开项目都是同一套 i18n-ally 行为：

{ "i18n-ally.localesPaths": ["src/assets/i18n"], "i18n-ally.pathMatcher": "{locale}.json", "i18n-ally.keystyle": "nested", "i18n-ally.namespace": true, "i18n-ally.sortKeys": true, "i18n-ally.displayLanguage": "zh-CN", "i18n-ally.preferredDelimiter": "_", "i18n-ally.ignoredLocales": [], "i18n-ally.translate.openai.apiModel": "你的模型ID", "i18n-ally.translate.openai.apiKey": "你的TaoToken Key", "i18n-ally.translate.openai.apiBaseUrl": "https://taotoken.net/api/v1" }

逐字段说明一下。localesPaths指向语言包目录，数组形式，支持多个目录。pathMatcher用{locale}.json匹配文件名，这样zh-CN.json会被识别为zh-CN语种。keystyle设成nested，和上面 JSON 的嵌套结构对应；如果你项目用的是扁平 key（比如Layout.Personal直接作为一级 key），就改成flat。namespace开启后，i18n-ally 会按命名空间组织 key。sortKeys让保存时自动排序，减少 diff 噪音。displayLanguage设成zh-CN，代码里内联显示中文。

翻译相关三个字段最关键：apiModel填模型 ID，apiKey填 TaoToken 的 Key，apiBaseUrl填https://taotoken.net/api/v1。注意这里我写的是带/v1的 Base URL，因为 i18n-ally 内部会拼接/chat/completions。如果你的插件版本字段名不同（有的版本叫apiBase或apiUrl），以插件实际提示为准，但地址主体不变。

如果你用的是 Cline MCP 或 Codex 的auth.json那套配置，逻辑是一样的三件套：Base URL、Key、Model ID。比如 Codex 的auth.json里会写OPENAI_BASE_URL和OPENAI_API_KEY，把 Base URL 指向https://taotoken.net/api/v1，Key 填 TaoToken 的 Key，模型 ID 填对应模型即可。CC Switch 这类工具也是同样思路，核心就是这三件套对齐。

配置保存后，重启一下 VS Code 或者执行Developer: Reload Window，让 i18n-ally 重新加载。此时打开任意一个.ts或.html文件，如果配置正确，你应该能看到translate调用旁边出现内联文案。

4. 验证请求：新增 key 的补全与校验动作

配置写完不能只看「没报错」，要实际跑一遍新增 key 的流程，确认补全、写入、翻译、校验都通。

第一步，在模板里写一个还没提取的文案。比如：

<nz-alert nzType="error" [nzMessage]="'WorkSpace.Message.Error' | translate" nzShowIcon></nz-alert>

如果WorkSpace.Message.Error这个 key 在zh-CN.json里不存在，i18n-ally 会给它加下划线。鼠标悬停会提示「缺失翻译」或「key 不存在」。这时候按Ctrl + .（macOS 是Cmd + .）触发快速修复，选择「提取文案到 i18n」，插件会让你填保存路径，比如WorkSpace.Message.Error，确认后它会自动把 key 写进zh-CN.json，并把代码里的硬编码中文替换成translate调用。

第二步，验证补全。在模板里输入{{ '之后，i18n-ally 会弹出 key 补全列表，输入Work就能看到WorkSpace.开头的所有 key。选中后回车，key 自动补全。这一步能过，说明localesPaths和pathMatcher配置正确。

第三步，验证翻译辅助。选中一个只有中文的 key，右键选择 i18n-ally 的翻译动作（不同版本菜单名略有差异，常见是「Translate」或「翻译此 key」），插件会调用你配置的 OpenAI 兼容接口。请求发到https://taotoken.net/api/v1/chat/completions，带上你的 Key 和模型 ID。如果返回正常，en-US.json里会新增对应英文翻译，并且编辑器里能看到进度提示。

第四步，验证校验。故意把某个 key 拼错，比如写成WorkSpace.Messag.Error，i18n-ally 会标红提示「key 不存在」。再故意删掉en-US.json里的一个翻译，插件会提示「缺失翻译」。这两个动作能触发，说明校验链路是通的。

如果你在模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 里先手动发一条翻译请求，确认模型能返回，再回到 VS Code 里操作，会更容易定位问题。因为如果模型对话都不通，那 i18n-ally 里大概率也不通，问题就在 Key 或 Base URL 上。

实测下来，新增 key 的完整链路是：写文案 → 下划线提示 → 快速修复提取 → 写入 JSON → 补全可用 → 翻译辅助填充其他语种 → 校验通过。这一套跑顺之后，团队里任何人加文案都不会再漏翻译。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错来对。i18n-ally 接模型接口时，最常见的几类错误如下。

401 Unauthorized。这是最高频的。原因通常是三个：Key 填错、Key 前后有空格、Base URL 少了/v1。先检查apiKey字段是不是完整复制了 TaoToken 控制台里的 Key，注意不要带引号外的空格。再检查apiBaseUrl是不是https://taotoken.net/api/v1。如果插件字段叫apiBase，填https://taotoken.net/api也可能被内部拼成/chat/completions而缺/v1，这时候要手动补/v1。排查方法：到 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 重新生成一个 Key，替换后重载窗口。

local proxy failed。这个报错通常出现在插件尝试走本地代理时。i18n-ally 某些版本会读取 VS Code 的代理设置。如果你本机没有开代理，但 VS Code 配置里残留了http.proxy，就会失败。解决方式是检查 VS Code 的settings.json里有没有http.proxy字段，有就删掉；同时确认系统环境变量里没有指向本地端口的代理配置。清掉之后重载窗口，再试翻译。

reading 'choices'。这个报错说明插件拿到了响应，但响应结构里没有choices字段。常见原因是 Base URL 指向的接口返回了非 OpenAI 兼容格式，或者模型 ID 填错导致接口返回错误对象。先确认apiModel填的是有效模型 ID，再确认apiBaseUrl指向的是https://taotoken.net/api/v1。如果还不行，到模型对话页面手动发一条请求，看返回结构里有没有choices。如果手动请求正常，那就是插件字段拼接问题，检查是不是多写了/chat/completions导致路径重复。

OAuth 相关报错。有些工具链（比如 Codex 的auth.json）默认走 OAuth 登录流程，如果你直接填 API Key，可能会提示 OAuth 失败。这时候要确认工具是否支持 API Key 模式。Codex 的auth.json里应该写OPENAI_API_KEY和OPENAI_BASE_URL，而不是走 OAuth。CC Switch 同理，切到 API Key 模式，填三件套：Base URLhttps://taotoken.net/api/v1、Key、Model ID。如果工具强制 OAuth，那就换用支持 API Key 的配置方式。

再补一个容易忽略的：语言包路径不对。如果localesPaths写成了src/assets/i18n/（带尾斜杠）而插件要求不带，或者pathMatcher和实际文件名不匹配，i18n-ally 会识别不到语言包，表现为「没有可用 locale」。这时候检查目录下文件名是不是zh-CN.json这种格式，pathMatcher是不是{locale}.json。

排障顺序建议：先确认模型对话能通，再确认 VS Code 配置三件套，最后确认语言包路径。三步都过，基本不会有大问题。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到字段不确定可以对照看。

6. 把 TaoToken 接进 i18n-ally 翻译流程的长期用法

配置跑通之后，日常用法其实很轻。团队里每个人打开项目，.vscode/settings.json已经共享，i18n-ally 自动生效。新增文案时，写中文 → 快速修复提取 → 补全 key → 翻译辅助填充其他语种。整个过程不需要离开编辑器。

对于长期做 Angular 国际化的团队，建议把语言包 key 的命名规范也定下来，比如按模块分命名空间：Layout.*、WorkSpace.*、Common.*。i18n-ally 的namespace和sortKeys配合这套规范，能让 JSON diff 非常干净。翻译辅助走 TaoToken 统一通道，好处是 Key 集中管理，不会出现某个同事的 Key 额度用完导致翻译中断。

如果你后续要做更复杂的编码辅助，比如让模型帮忙批量检查语言包一致性、生成缺失 key 的占位翻译，可以了解 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它和 i18n-ally 的翻译辅助不冲突，一个偏编辑器内即时翻译，一个偏长期编码流程。

最后给一个实用技巧：把i18n-ally.sortKeys打开后，每次保存 JSON 都会自动排序，这样两个人同时加 key 时冲突会少很多。另外，i18n-ally.displayLanguage设成zh-CN后，代码里内联显示中文，review 时一眼就能看出文案对不对，不用来回切语言包文件。这两个设置配合使用，日常体验会顺很多。

整套流程的核心就是三件套对齐：Base URL 指向https://taotoken.net/api/v1，Key 用 TaoToken 控制台生成的，Model ID 填有效模型。三件套对了，i18n-ally 的翻译辅助就能稳定跑起来，Angular 国际化 JSON 也就真正管起来了。