feat(translate): add no-overwrite strategy for human-reviewed translations

.gitignore

@@ -113,3 +113,6 @@ telemetry-id
 *.log
 *.skill
 api-server/flaky-test-counts.txt
+
+# Automated translation output (never commit generated translations)
+automated-translations/

AGENTS.md

@@ -158,3 +158,13 @@ See `context/workflows/PRODUCTION_DEPLOYMENT.md` for complete workflow.
 - Architecture & Lessons: `./NOTION_FETCH_ARCHITECTURE.md`
 - Workflows: `./context/workflows/` (commands, lifecycle, translations, production deployment)
 - Quick Lookups: `./context/quick-ref/` (mappings, status, examples)
+
+## Approach
+- Think before acting. Read existing files before writing code.
+- Be concise in output but thorough in reasoning.
+- Prefer editing over rewriting whole files.
+- Do not re-read files you have already read unless the file may have changed.
+- Test your code before declaring done.
+- No sycophantic openers or closing fluff.
+- Keep solutions simple and direct.
+- User instructions always override this file.

package.json

@@ -28,6 +28,8 @@
     "notion:export": "bun scripts/notion-fetch/exportDatabase.ts",
     "notion:gen-placeholders": "bun scripts/notion-placeholders",
     "notion:fetch-all": "bun scripts/notion-fetch-all",
+    "notion:push-translation": "bun scripts/push-new-translation-to-notion.ts",
+    "notion:translate-test": "bun scripts/run-single-page-translation.ts",
     "api:server": "bun api-server",
     "api:server:dev": "bun --watch api-server",
     "clean:generated": "bun scripts/cleanup-generated-content.ts",

scripts/constants.ts

@@ -55,6 +55,39 @@ export const LANGUAGES: TranslationConfig[] = [
   },
 ];
 
+export const AUTOMATED_OUTPUT_DIRS: Record<string, string> = {
+  "pt-BR": "./automated-translations/pt",
+  es: "./automated-translations/es",
+};
+
+/** Maps base Notion language names to their automated select option values. */
+export const AUTOMATED_LANGUAGE_MAP: Record<string, string> = {
+  Portuguese: "PT - automated",
+  Spanish: "ES - automated",
+};
+
+export function isAutomatedLanguageCode(code: string): boolean {
+  return Object.values(AUTOMATED_LANGUAGE_MAP).includes(code);
+}
+
+export function getBaseLanguageCode(code: string): string {
+  for (const [base, automated] of Object.entries(AUTOMATED_LANGUAGE_MAP)) {
+    if (automated === code) return base;
+  }
+  return code;
+}
+
+export function getAutomatedLanguageCode(code: string): string {
+  if (isAutomatedLanguageCode(code)) return code; // already automated
+  // eslint-disable-next-line security/detect-object-injection -- code is a known language name from the AUTOMATED_LANGUAGE_MAP keys
+  return AUTOMATED_LANGUAGE_MAP[code] ?? `${code}-automated`;
+}
+
+export function getAutomatedOutputDir(language: string): string | undefined {
+  // eslint-disable-next-line security/detect-object-injection -- language is validated against known locale keys from AUTOMATED_OUTPUT_DIRS
+  return AUTOMATED_OUTPUT_DIRS[language];
+}
+
 // Maximum number of retries for API calls
 export const MAX_RETRIES = 3;
 

scripts/notion-fetch/generateBlocks.ts

@@ -132,6 +132,8 @@ const LANGUAGE_NAME_TO_LOCALE: Record<string, string> = {
   English: "en",
   Spanish: "es",
   Portuguese: "pt",
+  "PT - automated": "pt",
+  "ES - automated": "es",
 };
 
 const FALLBACK_TITLE_PREFIX = "untitled";

scripts/notion-fetch/pageGrouping.ts

@@ -10,6 +10,8 @@ const LANGUAGE_NAME_TO_LOCALE: Record<string, string> = {
   english: "en",
   spanish: "es",
   portuguese: "pt",
+  "pt - automated": "pt",
+  "es - automated": "es",
   en: "en",
   es: "es",
   pt: "pt",