fix: make docs i18n frontmatter translation resilient

clawsweeper[bot] · clawsweeper[bot] · commit efd98bba14fd · 2026-06-09T03:34:05.000Z
diff --git a/scripts/docs-i18n/main_test.go b/scripts/docs-i18n/main_test.go
@@ -278,6 +278,31 @@ func TestTranslateSnippetFallsBackWhenFrontmatterTranslatorFails(t *testing.T) {
 	}
 }
 
+func TestTranslateSnippetCachesDocumentSourcePath(t *testing.T) {
+	t.Parallel()
+
+	tm := &TranslationMemory{entries: map[string]TMEntry{}}
+	source := "Gateway"
+	segmentID := "gateway/index.md:frontmatter:title"
+
+	translated, err := translateSnippet(context.Background(), fakeDocsTranslator{}, tm, segmentID, source, "en", "zh-CN")
+	if err != nil {
+		t.Fatalf("translateSnippet returned error: %v", err)
+	}
+	if translated != source {
+		t.Fatalf("unexpected translation %q", translated)
+	}
+
+	cacheKey := cacheKey(cacheNamespace(), "en", "zh-CN", segmentID, hashText(source))
+	entry, ok := tm.Get(cacheKey)
+	if !ok {
+		t.Fatal("expected successful frontmatter translation to be cached")
+	}
+	if entry.SourcePath != "gateway/index.md" {
+		t.Fatalf("expected document source path, got %q", entry.SourcePath)
+	}
+}
+
 func TestValidateNoTranslationTranscriptArtifacts(t *testing.T) {
 	t.Parallel()
 
diff --git a/scripts/docs-i18n/process.go b/scripts/docs-i18n/process.go
@@ -223,10 +223,14 @@ func translateSnippet(ctx context.Context, translator docsTranslator, tm *Transl
 		translated = textValue
 		shouldCache = false
 	}
+	sourcePath := segmentID
+	if path, _, ok := strings.Cut(segmentID, ":frontmatter:"); ok {
+		sourcePath = path
+	}
 	entry := TMEntry{
 		CacheKey:   ck,
 		SegmentID:  segmentID,
-		SourcePath: segmentID,
+		SourcePath: sourcePath,
 		TextHash:   textHash,
 		Text:       textValue,
 		Translated: translated,
