Cache locale baseline for CI builds

README.md

@@ -23,7 +23,7 @@ bun run release:package
 
 构建会生成 `dist/theme-github-dev.css` 和 `dist/theme-github-dev-dark.css`，并同步输出到 `.gitea/custom/public/assets/css/` 供 Gitea custom 目录使用。Docker 预览当前默认加载 `github-dev-dark`，便于检查未登录页面 dark 模式。
 
-locale 只在 `options/locale-overrides/` 维护增量 key。构建会按当前 Gitea 版本从官方仓库获取完整 locale，合并增量后输出到 `.gitea/custom/options/locale/`。
+locale 官方基线提交在 `options/locale/`，项目增量只在 `options/locale-overrides/` 维护。构建会合并基线和增量后输出到 `.gitea/custom/options/locale/`，CI 不依赖外网拉取 locale。
 
 ## 发布
 

docs/official-style-map.md

@@ -72,7 +72,7 @@ Gitea custom 输出：
 
 模板覆盖由本项目 `templates/` 维护，构建时同步到 `.gitea/custom/templates/`。
 
-locale 增量由本项目 `options/locale-overrides/` 维护。构建时 `scripts/locale.ts` 会从 Gitea 官方 `v1.26.1` 获取完整 locale，再合并本项目增量并输出到 `.gitea/custom/options/locale/`。
+locale 官方基线由本项目 `options/locale/` 缓存，增量由 `options/locale-overrides/` 维护。构建时 `scripts/locale.ts` 会合并基线和本项目增量并输出到 `.gitea/custom/options/locale/`。
 
 后续迁移时，如果只是改颜色主题值，优先放到 `themes/`。`styles/tokens/` 只负责把当前主题输出成 CSS 变量，不直接维护具体颜色表。
 

docs/rules.md

@@ -18,7 +18,7 @@
 
 `templates/` 放 Gitea 模板覆盖文件。模板修改应尽量保持最小化，避免把样式逻辑写进模板。
 
-`options/locale-overrides/` 放本项目新增或修改的 locale 增量 key。Gitea 运行时需要完整 locale 文件，所以构建时会从当前 Gitea 版本的官方仓库获取完整 locale，再合并这里的增量覆盖并输出到 `.gitea/custom/options/locale/`。
+`options/locale/` 放当前 Gitea 版本的官方 locale 基线。`options/locale-overrides/` 放本项目新增或修改的 locale 增量 key。Gitea 运行时需要完整 locale 文件，所以构建时会合并基线和增量覆盖并输出到 `.gitea/custom/options/locale/`。
 
 `src/` 放构建辅助代码、类型和聚合逻辑。这里不直接承载某个具体页面的样式规则。
 
@@ -54,7 +54,7 @@
 
 使用 `bun run preview` 启动本地预览页面。
 
-使用 `bun run locale:sync` 按 `package.json` 里的 Gitea 版本从官方仓库获取 locale，并合并 `options/locale-overrides/`。
+使用 `bun run locale:sync` 从本地 `options/locale/` 基线合并 `options/locale-overrides/`。需要刷新官方基线时，运行 `bun scripts/locale.ts --remote`。
 
 使用 `bun run test` 构建 light/dark 两套主题并检查必要输出是否存在。
 
@@ -74,4 +74,4 @@
 
 修改模板时，先确认 Gitea 原始模板结构，再把覆盖文件放入 `templates/`。`bun run build` 会同步到 `.gitea/custom/templates/`。
 
-修改翻译时，只改 `options/locale-overrides/` 里的增量 key。不要在源码里手工维护完整 `options/locale/locale_*.json`，构建脚本会从官方 `v1.26.1` locale 合并生成 Gitea 运行时需要的完整文件。
+修改翻译时，只改 `options/locale-overrides/` 里的增量 key。不要手工编辑 `options/locale/locale_*.json`；它是当前 Gitea 版本的官方基线缓存，仅在升级 Gitea 版本或显式远程刷新时更新。

scripts/build.ts

@@ -81,9 +81,9 @@ async function build() {
 
   await Promise.all([
     syncDir(join(root, "templates"), join(root, ".gitea", "custom", "templates")),
-    syncDir(join(root, "options"), join(root, ".gitea", "custom", "options"), new Set(["locale-overrides"])),
-    syncLocales(),
+    syncDir(join(root, "options"), join(root, ".gitea", "custom", "options"), new Set(["locale", "locale-overrides"])),
   ]);
+  await syncLocales();
 
   console.log(`built ${cssOutputs.length} css outputs`);
 }

scripts/locale.ts

@@ -5,9 +5,11 @@ const root = process.cwd();
 const packageJson = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as { version: string };
 const giteaVersion = packageJson.version;
 const localeNames = ["locale_zh-CN.json"];
+const localLocaleBaseDir = join(root, "options", "locale");
 const remoteLocaleBaseUrl =
   process.env.GITEA_LOCALE_BASE_URL ??
   `https://raw.githubusercontent.com/go-gitea/gitea/v${giteaVersion}/options/locale`;
+const refreshRemote = process.env.GITEA_LOCALE_REFRESH === "1" || process.argv.includes("--remote");
 
 async function readJsonFile(path: string): Promise<Record<string, string>> {
   return JSON.parse(await readFile(path, "utf8")) as Record<string, string>;
@@ -28,10 +30,29 @@ async function fetchOfficialLocale(name: string): Promise<Record<string, string>
   return (await response.json()) as Record<string, string>;
 }
 
+async function readOfficialLocale(name: string): Promise<Record<string, string>> {
+  if (!refreshRemote) {
+    try {
+      return await readJsonFile(join(localLocaleBaseDir, name));
+    } catch (error) {
+      const code = error instanceof Error && "code" in error ? error.code : undefined;
+
+      if (code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+
+  const official = await fetchOfficialLocale(name);
+  await writeJsonFile(join(localLocaleBaseDir, name), official);
+
+  return official;
+}
+
 export async function syncLocales() {
   await Promise.all(
     localeNames.map(async (name) => {
-      const official = await fetchOfficialLocale(name);
+      const official = await readOfficialLocale(name);
       const overrides = await readJsonFile(join(root, "options", "locale-overrides", name));
       const merged = { ...official, ...overrides };
 
@@ -42,5 +63,9 @@ export async function syncLocales() {
 
 if (import.meta.main) {
   await syncLocales();
-  console.log(`synced ${localeNames.length} locale file from ${remoteLocaleBaseUrl}`);
+  console.log(
+    refreshRemote
+      ? `synced ${localeNames.length} locale file from ${remoteLocaleBaseUrl}`
+      : `synced ${localeNames.length} locale file from ${localLocaleBaseDir}`,
+  );
 }