ci: restore machine-translated link targets before the build

.gitattributes

@@ -1,3 +1,8 @@
+# Normalise line endings in the repository, matching .editorconfig's
+# `end_of_line = lf`. Without this a checkout on Windows can reintroduce
+# CRLF and the next save shows up as a whole-file diff.
+* text=auto eol=lf
+
 /.yarn/**            linguist-vendored
 /.yarn/releases/*    binary
 /.yarn/plugins/**/*  binary

.github/workflows/main.yml

@@ -55,13 +55,25 @@ jobs:
       - name: Install dependencies (immutable)
         run: yarn --immutable
 
+      # The integrity check is what stands between a truncated machine
+      # translation and the published site, so it is itself tested -- on every
+      # event, not just the pushes that translate.
+      - name: Test the translation integrity check
+        run: yarn test:translation
+
       - name: generate id
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: ./add_id.sh docs/en/solutions && ./add_id.sh docs/en/articles
 
-      - name: translate
+      # Translate, verify, and retranslate whatever came back incomplete. A single
+      # pass is not trustworthy: this model has dropped a whole section, invented
+      # a table, and rewritten link targets into the literal `URL` from its own
+      # prompt example -- none of which the build would notice. If a document is
+      # still incomplete after the retries, this step fails and nothing is
+      # committed, so a short page never reaches the site.
+      - name: Translate and verify
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: yarn translate -s en -t zh -g "*"
+        run: node scripts/translate-verified.mjs
 
       - name: Build
         run: yarn build
@@ -81,3 +93,17 @@ jobs:
         with:
           branch: ${{ github.ref }}
           github_token: ${{ secrets.KNOWLEDGE_SECRET }}
+
+      # Nothing is committed unless the build passes, so a failed run otherwise
+      # discards the generated translations and leaves no way to see what the
+      # model produced. Keep them for post-mortems. docs/en is included because
+      # add_id.sh rewrites it earlier in the same run.
+      - name: Upload generated docs on failure
+        if: failure() && github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v4
+        with:
+          name: generated-docs-${{ github.run_id }}
+          path: |
+            docs/en
+            docs/zh
+          retention-days: 7

docs/en/solutions/Pipeline_Policy_Constraints_with_Tekton_and_Kyverno.md

@@ -6,6 +6,7 @@ kind:
   - Solution
 ProductsVersion:
   - 4.3.x
+id: KB260800021
 ---
 # Pipeline Policy Constraints with Tekton and Kyverno
 

docs/zh/solutions/How_to_Migrate_MySQL_57_to_80.md

@@ -6,7 +6,6 @@ products:
 ProductsVersion:
   - 4.x
 id: KB260300002
-sourceSHA: 42488d5a3548fdf9f213199c719714baf2fc5c10e533ae99782ddc71a85b77e5
 ---
 
 # MySQL 5.7 到 8.0 迁移指南

docs/zh/solutions/How_to_Use_PostgreSQL_Hot_Standby_Cluster.md

@@ -6,7 +6,6 @@ products:
 ProductsVersion:
   - 4.x
 id: KB251000009
-sourceSHA: 5eae23c900f5a89e26fec5e773b3d048e043b171bab6d6bbf975d3c26b823250
 ---
 
 # PostgreSQL 热备份集群配置指南

docs/zh/solutions/Install_Multi-Primary_Service_Mesh_on_Different_Networks.md

@@ -4,7 +4,6 @@ products:
   - Alauda Service Mesh
 kind:
   - Solution
-sourceSHA: 2ddecfc3b826a970015660a1889242c353532f50620e1b85d1af72fb9325b3ab
 ---
 
 # 多主不同网络服务网格架构的安装指南

docs/zh/solutions/Software_Supply_Chain_Security_of_Alauda_Container_Platform_with_Tekton_and_Kyverno.md

@@ -4,7 +4,6 @@ products:
   - Alauda Container Platform
 kind:
   - Solution
-sourceSHA: 7e3980ae21e998f2fd0014ace7f2cd8b3264c605d2948ce55999536f20eab834
 ---
 
 ```yaml

docs/zh/solutions/ecosystem/opensearch/How_to_Migrate_from_Elasticsearch_to_OpenSearch.md

@@ -4,7 +4,6 @@ products:
 kind:
   - Solution
 id: KB260100026
-sourceSHA: 4d71480f5d5df1aa4044adeeedaadb443b8cd9b2bd075df00f762f1ec153febe
 ---
 
 # 如何从 Elasticsearch 迁移到 OpenSearch

doom.config.ts

@@ -1,28 +1,113 @@
 import { defineConfig } from "@alauda/doom/config";
+// Pulls in doom's module augmentation of rspress's UserConfig, which is where
+// `translate` is declared.
+import type {} from "@alauda/doom/types";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { blogPostResolver } from "./plugins/plugin-post-resolver/index.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// The default prompt shipped by doom has two properties this repository cannot
+// live with, both of which produced real damage in run 33057885704 and before:
+//
+//  1. It illustrates its rules with literal placeholders -- a link written as
+//     [text](URL), an image written as ![alt](src). When the model loses the
+//     thread mid-chunk it recites its own instructions into the prose, and those
+//     placeholders arrive as real markup: `URL` became a dead link and `src`
+//     became "Module not found", both of which failed the build.
+//  2. It never says the translation has to be complete. It asks for the format
+//     to be preserved and says nothing about the content, so dropping an entire
+//     section, 46 code blocks or every table in the document breaks no rule it
+//     was given. Three articles in this repository lost about a third of their
+//     content that way, unnoticed, because nothing checked.
+//
+// So: describe the rules instead of illustrating them with copyable fake values,
+// put completeness first, and forbid emitting these instructions outright.
+// scripts/check-translation-integrity.mjs is the backstop that catches what slips.
+const TRANSLATE_SYSTEM_PROMPT = `
+You are a professional technical documentation engineer. Translate the document below from <%= sourceLang %> into <%= targetLang %>, so that it reads as if the same engineer had written it in <%= targetLang %>, at the same level of precision.
+
+## What you return
+
+Return the translated document, and nothing else: no preamble, no closing remark, no code fence wrapped around the whole answer, no notes about what you did.
+
+Never reproduce any part of these instructions in your output. They are not part of the document. If you find yourself writing a heading such as "Baseline Requirements", a glossary of term mappings, or a note about chunked translation, you have started copying this prompt into the document -- stop and return to translating the source.
+
+## Completeness comes first
+
+Your output must contain everything the source contains, in the same order and at the same structural level: every heading, paragraph, list item, table row, fenced code block, admonition, blockquote and footnote.
+
+Never summarise, merge, abbreviate, or skip a passage, however repetitive or boilerplate it looks. Never stop before the end of the input. A clumsy sentence can be fixed later; a section you silently dropped cannot, because nobody will know it is missing.
+
+## What must survive unchanged
+
+- Link destinations. Translate the visible text of a link; reproduce the destination exactly as written, character for character, including any anchor fragment or query string. This applies to inline links, reference definitions, bare URLs, and href or src attributes in HTML and JSX.
+- Anchor placeholders. Tokens of the form __ANCHOR_ followed by a number are heading identifiers that the document cross-references. Reproduce every one of them, exactly as written, in the same position. Dropping one silently breaks navigation.
+- The contents of fenced code blocks and inline code spans: field names, CLI flags, resource kinds, expressions and regular expressions are code, not prose.
+- JSX and MDX component names and their attribute keys; only the content between component tags is translated.
+- Escape characters already present in the source, such as backslashes and angle brackets. Do not add escapes that the source does not have -- brackets and parentheses in ordinary prose stay as they are.
+- Technical terms and proper nouns that are conventionally left untranslated: product names, Kubernetes and cloud-native project names, language and format names, and API object names.
+
+## Frontmatter and comments
+
+- In frontmatter, translate the title and description fields only; leave every other field exactly as it is.
+- Preserve these comments and their contents, in both MDX and HTML comment syntax: release-notes-for-bugs.
+- Remove these comments entirely, in both MDX and HTML comment syntax: reference-start and reference-end.
+
+## Language
+
+Sentences should read naturally to a native <%= targetLang %> speaker and follow the conventions of technical documentation in that language. Keep the register of the source: if it is dense and exact, stay dense and exact rather than smoothing it out.
+<% if (titleTranslationPrompt) { %>
+<%- titleTranslationPrompt %>
+<% } %>
+<% if (terms) { %>
+<%- terms %>
+<% } %>
+<% if (isChunk) { %>
+## This is one chunk of a longer document
+
+The text below is a consecutive slice of a larger document, cut at a heading boundary. Translate the whole slice as a continuous part of that document, keeping the style consistent with it.
+
+Being handed a fragment changes nothing about the rules above. Translate from its first line to its last. Do not introduce it, do not summarise it, do not comment on the fact that it is a fragment, and do not write anything about the chunking itself.
+<% } %>
+<% if (userPrompt || additionalPrompts) { %>
+## Additional requirements
+
+These apply in addition to everything above; where they conflict with it, everything above wins.
+
+"""
+<% if (userPrompt) { %>
+<%- userPrompt %>
+<% } %>
+<% if (additionalPrompts) { %>
+<%- additionalPrompts %>
+<% } %>
+"""
+<% } %>
+`.trim()
+
 export default defineConfig({
   title: "Alauda Knowledge",
-  base: "/knowledge/",
-  description:
-    "Welcome to Alauda's Knowledgebase information center. Find resources for resolving problems and troubleshooting.",
-  logo: "/logo.svg",
-  logoText: "Alauda Knowledge",
-  globalStyles: join(__dirname, "styles/index.css"),
-  plugins: [
-    blogPostResolver({
-      postsDir: join(__dirname, "docs"),
-    }),
-  ],
-  themeConfig: {
-    darkMode: false,
-    lastUpdated: true,
-    footer: {
-      message: "© 2025 Alauda Inc. All Rights Reserved.",
-    },
-  },
-});
+  base: "/knowledge/",
+  description:
+    "Welcome to Alauda's Knowledgebase information center. Find resources for resolving problems and troubleshooting.",
+  logo: "/logo.svg",
+  logoText: "Alauda Knowledge",
+  globalStyles: join(__dirname, "styles/index.css"),
+  plugins: [
+    blogPostResolver({
+      postsDir: join(__dirname, "docs"),
+    }),
+  ],
+  translate: {
+    systemPrompt: TRANSLATE_SYSTEM_PROMPT,
+  },
+  themeConfig: {
+    darkMode: false,
+    lastUpdated: true,
+    footer: {
+      message: "© 2025 Alauda Inc. All Rights Reserved.",
+    },
+  },
+});

package.json

@@ -20,6 +20,8 @@
     "new": "doom new",
     "serve": "doom serve",
     "translate": "doom translate",
+    "check:translation": "node scripts/check-translation-integrity.mjs",
+    "test:translation": "node scripts/check-translation-integrity.test.mjs",
     "export": "doom export"
   }
 }