awesome-jev（bestjev）是由社区维护的 Jev 开源项目目录，收录了 992 个已核验的项目。本文解析 awesome-jev 国际化（i18n）实现原理：英语、简体中文、日语、韩语、西班牙语和巴西葡语 6 种语言，如何保证 992 条目录数据逐条对齐、UI 文案不遗漏、多语言页面 SEO 完整，全部在构建期自动完成。

1. 为什么 992 条目录要做 6 种语言？

多语言目录最大的痛点不是"翻译"，而是数据一致性：992 条项目如果人工维护 6 份，新增一个项目就要改 6 个文件，极易出现某条目录只有 5 种语言的情况。

awesome-jev 的解法很直接：目录数据本身就是六份并行的 Markdown 文件，每种语言一份，且结构完全相同：

每份文件用相同的### 分类 (数量)标题组织 11 个分类，条目用统一的 Markdown 表格行描述（项目链接、Star、语言、收录日期、本地化简介）。格式统一是后续所有自动校验的前提。

2. 语言路由：en 占根路径，其余 5 种用路径前缀

站点基于 Astro 构建，在 astro.config.mjs 中声明了 i18n 配置：

i18n: { locales: ['en', 'zh', 'ja', 'ko', 'es', 'pt-br'], defaultLocale: 'en', routing: { prefixDefaultLocale: false }, }

这里有个值得注意的细节：prefixDefaultLocale: false让英语占据根路径，其余 5 种语言使用/zh/、/ja/等前缀。对应的页面文件放在 src/pages/[locale]/ 动态路由目录下，例如 src/pages/[locale]/index.astro 通过getStaticPaths只生成 5 个非默认语言版本，再复用同一套页面组件渲染。

语言元数据（语言标签、国旗图标、OpenGraph locale、对应 README 文件名）集中在 src/i18n/config.ts 的localeConfig中，新增一种语言只需在 3 处登记：localeConfig、语言文件映射、README 数据文件。

3. UI 文案同步：TypeScript 类型约束 + 默认回退

网站界面的按钮、标题、提示语等文案放在 src/i18n/messages/ 下，同样每种语言一个文件。这里有两个保证"不漏译"的设计：

① 类型即契约。英语文件 src/i18n/messages/en.ts 导出Messages类型，其余 5 个语言文件都声明为const zh: Messages = {...}——少翻译一个字段，类型检查直接报错，而不是留到运行时才发现页面缺字。

② 默认回退。以 src/i18n/messages/ko.ts 为例，文件开头是...en展开英语文案，再逐项覆盖韩语翻译。某个 key 漏写时会自动回退到英语，页面永远不会出现空白或 undefined。

文案的分组也体现了"可维护性优先"：seo、nav、hero、catalog、footer等模块各自成组，动态文案（如标题中的项目数量）统一用函数形式(projects: number) => ...表达，6 种语言共享同一套参数结构。

4. 992 条数据如何逐条对齐？构建期一致性校验

这是整个 i18n 方案的核心。src/lib/catalog.ts 在构建时会依次解析全部 6 份 README，然后做三层严格比对：

1. 分类数量一致：每种语言的分类数必须与英语版相同，否则抛出Catalog category count mismatch；
2. 每个分类的行数一致：任何分类的项目条数不等，抛出Catalog row count mismatch；
3. 同一位置的项目 URL 一致：逐行比对仓库链接，顺序错位或漏项会抛出Catalog project mismatch。

也就是说，只要某语言漏了一条、或某条目顺序对不上，构建直接失败，问题在 CI 阶段就暴露，而不是上线后用户才发现。校验通过的数据会按语言组装成本地化目录（描述、分类名用当前语言，URL、Star、收录日期用英语源数据），并通过searchText把 6 种语言的描述拼在一起，让任意语言下搜索都能命中其他语言的关键词。

收录日期也有独立校验：每份 README 表格中的日期必须与 src/data/catalog-added-at.json 记录一致，进一步保证 6 份数据快照的同一性。

5. 多语言页面的 SEO：hreflang 与语言切换器

国际化站点的 SEO 重点是让搜索引擎知道"这是同一页面的 6 个语言版本"。awesome-jev 在两处做了处理：

• sitemap：src/pages/sitemap.xml.ts 为每个路由 × 每个语言生成条目，并输出 6 条xhtml:link rel="alternate" hreflang交叉引用外加x-default指向英语版，保证 992 条目录的所有分类页、今日新增页都有完整的语言映射；
• 语言切换器：src/components/SiteLayout.astro 侧边栏的语言菜单基于localeConfig动态生成，每个选项同时设置lang和hreflang属性，配合 public/flags/ 下的国旗图标，用户一键切换到同路径的其他语言页面。

6. 自动同步工具链：连 CHANGELOG 都自动生成

多语言仓库的日常维护靠两个脚本兜底，位于 scripts/ 目录：

• scripts/sync-changelog.mjs：从 README 表格生成 CHANGELOG.md，并带--check模式在 CI 中校验文件是否为最新，防止手工编辑；
• scripts/sync-added-at.mjs：通过遍历README.md的 git 历史，自动为每个项目仓库反查"首次被收录"的时间戳，生成catalog-added-at.json，让"今日新增 / 本周新增"功能在 6 种语言页面下数据一致。

配合 src/pages/catalog/[locale].json.ts 为每种语言输出的机读 JSON 目录，下游工具（如语言模型）也能按语言消费同一套已核验数据。

7. 小结：awesome-jev i18n 的四个关键设计

1. 一份格式、六份数据：语言差异只存在于"描述文本"，结构由统一模板锁定；
2. 类型系统兜底 UI 文案：Messages类型 +...en默认回退，漏译在编译期暴露；
3. 构建期逐条校验 992 条数据：分类数、行数、URL 三层比对，不一致即构建失败；
4. SEO 与工具链自动化：hreflang sitemap、CHANGELOG 与收录时间全部脚本生成，人工维护成本最小化。

对新手来说，这套方案的可借鉴之处在于：多语言同步不靠纪律和检查单，而是靠"格式约定 + 类型检查 + 构建失败"三道自动化闸门，让 992 条 × 6 语言 ≈ 6000 条记录的一致性由机器保证。