Isolate localization generation and publishing

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: justinyoo

.github/workflows/localization-sync.yml

@@ -13,20 +13,23 @@ on:
       - 'workshop/**/*.md'
   workflow_dispatch:
 
-permissions:
-  contents: write
-  pull-requests: write
-  copilot-requests: write
+permissions: {}
 
 concurrency:
   group: localization-sync-main
   cancel-in-progress: false
 
 jobs:
-  localize:
-    name: Update localized documentation
+  generate:
+    name: Generate localized documentation
     runs-on: ubuntu-latest
     timeout-minutes: 45
+    permissions:
+      contents: read
+      copilot-requests: write
+    outputs:
+      changed: ${{ steps.detect.outputs.changed }}
+      changed_files: ${{ steps.detect.outputs.changed_files }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
@@ -110,8 +113,56 @@ jobs:
 
           rm .localization-changed-files.txt
 
-      - name: Guard generated changes
+      - name: Upload generated localization tree
         if: steps.detect.outputs.changed == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: localization-output
+          path: |
+            localizations
+            docs/locale-registry.js
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+
+  validate:
+    name: Validate generated localization
+    needs: generate
+    if: needs.generate.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    outputs:
+      changed: ${{ steps.generated.outputs.changed }}
+    steps:
+      - name: Checkout trusted repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Download generated localization tree
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: localization-output
+          path: ${{ runner.temp }}/localization-output
+
+      - name: Materialize generated localization tree
+        run: |
+          python3 scripts/materialize_localization_artifact.py \
+            "${{ runner.temp }}/localization-output"
+
+      - name: Guard generated changes
         id: generated
         run: |
           python3 scripts/check_localization_updates.py \
@@ -129,15 +180,47 @@ jobs:
 
       - name: Validate localized site
         if: steps.generated.outputs.changed == 'true'
+        run: bash scripts/validate-workshop.sh content
+
+  publish:
+    name: Publish localization pull request
+    needs: [generate, validate]
+    if: needs.validate.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout trusted repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Download validated localization tree
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: localization-output
+          path: ${{ runner.temp }}/localization-output
+
+      - name: Materialize validated localization tree
         run: |
-          node docs/tests/workshop-site.test.js
-          python3 scripts/validate_workshop.py
+          python3 scripts/materialize_localization_artifact.py \
+            "${{ runner.temp }}/localization-output"
 
       - name: Create localization review pull request
-        if: steps.generated.outputs.changed == 'true'
         uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
         with:
           token: ${{ github.token }}
+          add-paths: |
+            localizations
+            docs/locale-registry.js
           branch: automation/localization-sync
           base: main
           delete-branch: true
@@ -147,7 +230,7 @@ jobs:
             GitHub Copilot CLI ran the repository-local localization skill for these English sources requiring synchronization:
 
             ```
-            ${{ steps.detect.outputs.changed_files }}
+            ${{ needs.generate.outputs.changed_files }}
             ```
 
             This pull request updates only existing locales. Please review translation quality and the localization baselines before merging.

scripts/materialize_localization_artifact.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Safely copy generated localization outputs into a trusted checkout."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+REGISTRY_PATH = Path("docs/locale-registry.js")
+
+
+def validate_artifact(artifact_root: Path) -> None:
+    localization_root = artifact_root / "localizations"
+    registry_path = artifact_root / REGISTRY_PATH
+
+    if not localization_root.is_dir() or localization_root.is_symlink():
+        raise RuntimeError("Artifact must contain a regular localizations directory.")
+    if not registry_path.is_file() or registry_path.is_symlink():
+        raise RuntimeError(f"Artifact must contain a regular {REGISTRY_PATH} file.")
+
+    for directory, directory_names, file_names in os.walk(
+        artifact_root,
+        followlinks=False,
+    ):
+        directory_path = Path(directory)
+        for name in directory_names:
+            path = directory_path / name
+            if path.is_symlink():
+                raise RuntimeError(f"Artifact contains a symbolic link: {path}")
+            relative_path = path.relative_to(artifact_root)
+            if (
+                relative_path != Path("docs")
+                and relative_path.parts[0] != "localizations"
+            ):
+                raise RuntimeError(f"Artifact contains an unexpected path: {relative_path}")
+        for name in file_names:
+            path = directory_path / name
+            if path.is_symlink() or not path.is_file():
+                raise RuntimeError(f"Artifact contains a non-regular file: {path}")
+
+            relative_path = path.relative_to(artifact_root)
+            if (
+                relative_path != REGISTRY_PATH
+                and relative_path.parts[0] != "localizations"
+            ):
+                raise RuntimeError(f"Artifact contains an unexpected path: {relative_path}")
+
+
+def materialize(artifact_root: Path, repository_root: Path = ROOT) -> None:
+    artifact_root = artifact_root.resolve()
+    repository_root = repository_root.resolve()
+    validate_artifact(artifact_root)
+
+    target_localizations = repository_root / "localizations"
+    if target_localizations.exists():
+        shutil.rmtree(target_localizations)
+    shutil.copytree(artifact_root / "localizations", target_localizations)
+
+    target_registry = repository_root / REGISTRY_PATH
+    target_registry.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(artifact_root / REGISTRY_PATH, target_registry)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "artifact_root",
+        type=Path,
+        help="Directory containing localizations/ and docs/locale-registry.js.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    materialize(args.artifact_root)
+    print("Materialized trusted localization output paths.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/test_materialize_localization_artifact.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).with_name("materialize_localization_artifact.py")
+SPEC = importlib.util.spec_from_file_location("materialize_localization_artifact", SCRIPT)
+assert SPEC and SPEC.loader
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class MaterializeLocalizationArtifactTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp_dir.name)
+        self.artifact = self.root / "artifact"
+        self.repository = self.root / "repository"
+        (self.artifact / "localizations" / "ko-kr").mkdir(parents=True)
+        (self.artifact / "docs").mkdir()
+        self.repository.mkdir()
+
+        (self.artifact / "localizations" / "ko-kr" / ".localization-state.json").write_text(
+            '{"version": 1, "files": {}}\n',
+            encoding="utf-8",
+        )
+        (self.artifact / "localizations" / "ko-kr" / "README.md").write_text(
+            "새 문서\n",
+            encoding="utf-8",
+        )
+        (self.artifact / "docs" / "locale-registry.js").write_text(
+            "const locale = 'ko-kr';\n",
+            encoding="utf-8",
+        )
+
+    def tearDown(self) -> None:
+        self.temp_dir.cleanup()
+
+    def test_materializes_only_expected_outputs(self) -> None:
+        (self.repository / "localizations" / "old").mkdir(parents=True)
+        (self.repository / "localizations" / "old" / "README.md").write_text(
+            "obsolete\n",
+            encoding="utf-8",
+        )
+
+        MODULE.materialize(self.artifact, self.repository)
+
+        self.assertFalse((self.repository / "localizations" / "old").exists())
+        self.assertEqual(
+            (self.repository / "localizations" / "ko-kr" / "README.md").read_text(
+                encoding="utf-8"
+            ),
+            "새 문서\n",
+        )
+        self.assertEqual(
+            (self.repository / "docs" / "locale-registry.js").read_text(
+                encoding="utf-8"
+            ),
+            "const locale = 'ko-kr';\n",
+        )
+
+    def test_rejects_unexpected_files_before_modifying_checkout(self) -> None:
+        unexpected = self.artifact / "scripts" / "validate_workshop.py"
+        unexpected.parent.mkdir()
+        unexpected.write_text("malicious\n", encoding="utf-8")
+        existing = self.repository / "localizations" / "ko-kr" / "README.md"
+        existing.parent.mkdir(parents=True)
+        existing.write_text("keep\n", encoding="utf-8")
+
+        with self.assertRaisesRegex(RuntimeError, "unexpected path"):
+            MODULE.materialize(self.artifact, self.repository)
+
+        self.assertEqual(existing.read_text(encoding="utf-8"), "keep\n")
+
+    def test_rejects_symbolic_links(self) -> None:
+        link = self.artifact / "localizations" / "ko-kr" / "linked.md"
+        try:
+            link.symlink_to(self.artifact / "docs" / "locale-registry.js")
+        except OSError as error:
+            self.skipTest(f"Symbolic links are unavailable: {error}")
+
+        with self.assertRaisesRegex(RuntimeError, "symbolic link|non-regular file"):
+            MODULE.materialize(self.artifact, self.repository)
+
+
+if __name__ == "__main__":
+    unittest.main()

scripts/validate-workshop.sh

@@ -36,7 +36,7 @@ run_system_python() {
 
 validate_content() {
     run_system_python scripts/validate_workshop.py
-    run_system_python -m unittest scripts/test_check_localization_updates.py
+    run_system_python -m unittest discover -s scripts -p 'test_*.py'
     node docs/tests/markdown-language-preprocessor.test.js
     node docs/tests/workshop-site.test.js
     node --test docs/tests/workshop-completion.test.js