From 80b8acd78fd1b9602eca6f08adc1a8adc04f46e8 Mon Sep 17 00:00:00 2001
From: Jacob Pierce <w.jacobpierce@gmail.com>
Date: Wed, 6 May 2026 09:32:38 -0700
Subject: [PATCH] Fix ht channel_id and document chef behavior

Restore the legacy `ht` source_id override
(`channel_PhET_Interactive_Simulations_TEST-ht`) so the chef updates the
existing Haitian Creole channel on Studio instead of creating a new one
under the default-derived id `phet-html5-simulations-ht`. Add two missing
Haitian category labels and drop the now-redundant hardcoded `ht`
channel-title fallback in `_localized_channel_title`. Annotate the chef
with inline comments covering locale handling, source_id stability, the
PhET-API/Kolibri metadata mapping, and the offline-mode HTML patches.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 phet/chef.py | 145 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 138 insertions(+), 7 deletions(-)

diff --git a/phet/chef.py b/phet/chef.py
index ee544d2c..f2d1e9cc 100755
--- a/phet/chef.py
+++ b/phet/chef.py
@@ -39,6 +39,9 @@
 from metadata_tags import METADATA_BY_CAT
 from ricecooker.config import MAX_CHAR_LIMITS
 
+# Manually-curated localized channel metadata keyed by locale code (row[1] in the CSV).
+# The CSV holds human-translated title, tagline, and description for each locale and
+# takes priority over the machine-translated fallbacks defined later in this file.
 CHANNEL_METADATA = {}
 
 # see https://docs.google.com/spreadsheets/d/1M5NQLtXUrGymxlvb4reqJmtUGLPCoXYvVB2P8vBVz_k/edit?gid=1471576465#gid=1471576465
@@ -50,6 +53,7 @@
     line_count = 0
     for row in csv_reader:
         if line_count == 0:
+            # Skip the header row.
             line_count += 1
             continue
         else:
@@ -59,12 +63,21 @@
                 "description": row[4],
             }
 
+# Raise Ricecooker's description char limit so our longer localized descriptions aren't truncated.
 MAX_CHAR_LIMITS.update({"description": {"max": 4096}})
 
+# "en" is the baseline locale: all sims exist in English, so non-English locales
+# fall back to the English metadata whenever localized data is missing.
 DEFAULT_LANG = "en"
 BASE_TITLE = "PhET Interactive Simulations"
+# Channel source_ids for locales without a special override are derived as f"{BASE_SOURCE_ID}-{locale}".
+# Studio derives a deterministic channel_id from (source_domain, source_id), so changing this value
+# would silently redirect every non-overridden locale to a brand-new channel on Studio.
 BASE_SOURCE_ID = "phet-html5-simulations"
 
+# Shared HTTP session with retries + on-disk HTTP-cache. The cache lives in `.webcache/` and
+# re-uses the Cache-Control headers from PhET's API so repeated chef runs don't re-fetch
+# everything from the network.
 retry_strategy = Retry(total=5, backoff_factor=1)
 # adapter = HTTPAdapter(max_retries=retry_strategy)
 
@@ -73,6 +86,10 @@
 sess = requests.Session()
 sess.mount("http://", adapter)
 sess.mount("https://", adapter)
+
+# Per-locale list of PhET category `name`s to skip entirely while walking the category tree.
+# "html" / "by-device" / "new" / "quantum" / "general" are duplicates or non-content buckets,
+# and Arabic additionally excludes "by-level" because they don't want grade-level grouping.
 ID_BLACKLIST_BY_LANG = {
     "en": ["html", "by-device", "new", "quantum", "general"],
     "ar": ["html", "by-device", "new", "quantum", "general", "by-level"],
@@ -81,6 +98,9 @@
 BASE_URL = "https://phet-api.colorado.edu"
 BASE_URL_DOWNLOAD = "https://phet.colorado.edu"
 
+# Manual translations for category/sim titles where PhET's API either lacks a localized string
+# or where we want to override PhET's default. Used as a last-mile lookup right before the label
+# is rendered to a TopicNode/HTML5AppNode.
 ARABIC_NAME_CATEGORY = {
     "Physics": "الفيزياء",
     "Biology": "الأحياء",
@@ -103,6 +123,8 @@
 }
 
 HAITIAN_NAME_CATEGORY = {
+    "Math and Statistics": "Matematik ak Estatistik",
+    "Earth and Space": "Latè ak Lespas",
     "Elementary School": "Lekòl Elemantè",
     "By Level": "Pa Nivo",
     "Middle School": "Lekòl mwayen",
@@ -131,6 +153,8 @@
     "Quantum": "Quantum",
 }
 
+# Spelling corrections for Arabic sim titles returned by the PhET API.
+# These are applied only when building the Arabic channel.
 SIM_TYPO = {
     "أشكال الجزئ": "أشكال الجزيء",
     "مولارية": "المولارية",
@@ -143,6 +167,9 @@
     "رؤية اللّون": "رؤية الألوان",
 }
 
+# Hard-coded fallback channel descriptions. Only hit when `CHANNEL_METADATA` (from the CSV)
+# has no entry for a given locale; if that fallback is also missing we machine-translate
+# the English description in run_with_locale.
 CHANNEL_DESCRIPTIONS = {
     "en": "The PhET Interactive Simulations project created by the University of Colorado Boulder provides interactive math and science simulations that engage students with intuitive, game-like environments. Students can learn about math, physics, biology, and chemistry through hands-on exploration and discovery. The simulations are appropriate for all ages and include guiding teacher lesson plans.",
     "ar": "تزوّد هذه القناة والمعمول بمحتواها من قبل جامعة كونيتيكيت الأمريكية مجموعة من برمجيات المحاكاة التي يمكن للمتعلمين في المرحلة الإعدادية والثانوية التفاعل معها لفهم أكبر لما قد يدرسونه من قوانين وتجارب في الرياضيات والعلوم المختلفة وخاصة مادتي الكيمياء والفيزياء.",
@@ -165,7 +192,8 @@ def get_channel_description(lang):
     )
 
 
-# Maps of IDs to their metadata
+# Maps of IDs to their metadata. Fetched once at import time (module-level) and re-used
+# across every locale run. The cached HTTP session makes subsequent chef runs fast.
 """
 The structure / keys we care about:
 { "<cat_id>": { "strings": [ { "<locale>": "<label>" } ], "simulationIds": [ <sim_id>, ...], }
@@ -185,6 +213,8 @@ def get_channel_description(lang):
     sess.get(f"{BASE_URL}/partner-services/2.0/metadata/keywords").text
 )
 
+# Per-locale stats, populated as the chef runs. Used for post-run reporting
+# (counts of teacher-guide docs, coach videos, sims downloaded, sims skipped).
 STATS = {}
 STATS["en"] = {"docs": 0, "vids": 0, "sims_downloaded": [], "sims_skipped": []}
 
@@ -206,6 +236,8 @@ def __init__(self, *args, **kwargs):
         with open("all_locales_mapping.json", "r") as f:
             self.lang_map = json.load(f)
 
+        # Start configured for English. `run_with_locale` mutates these in-place
+        # for each subsequent locale (then calls `self.main()` again).
         self.channel_name = BASE_TITLE  # English to begin with
         self.channel_source_id = BASE_SOURCE_ID
         self.channel_domain = "https://phet.colorado.edu"
@@ -214,6 +246,7 @@ def __init__(self, *args, **kwargs):
         self.channel_description = get_channel_description(self.channel_language)
         self.teachers_guide = ""
 
+        # `bs` and `az` are intentionally skipped (no localized PhET content of value).
         self.queued_locales = [
             key for key in list(self.lang_map.keys()) if key not in ["bs", "az"]
         ]
@@ -222,6 +255,9 @@ def __init__(self, *args, **kwargs):
         super().__init__(PhET, *args, **kwargs)
 
     def _get_phet_lang_code(self, kolibri_lang_code):
+        # Kolibri and PhET use different locale codes in places (e.g. Kolibri `pt` == PhET `pt_BR`).
+        # Use this helper any time you're hitting the PhET API or looking up localized strings
+        # indexed by PhET's code.
         code = self.lang_map.get(kolibri_lang_code)
         if not code:
             raise ValueError(f"Lang code not mapped: {kolibri_lang_code}")
@@ -229,6 +265,8 @@ def _get_phet_lang_code(self, kolibri_lang_code):
             return code
 
     def _update_translators(self):
+        # `self.translator`: translates arbitrary source → channel language (used for sim titles/descriptions).
+        # `self.lang_en_translator`: only meaningful when DEFAULT_LANG != channel_language; see override in run_with_locale.
         self.translator = GoogleTranslator(source="auto", target=self.channel_language)
         self.lang_en_translator = GoogleTranslator(
             source=self.channel_language, target=self.channel_language
@@ -239,9 +277,11 @@ def run_with_locale(self, locale):
         After the English chef completes, this method will be called to run another language.
         """
         # JP: Not sure why this is necessary but it was in the original code
+        # (Kolibri's "id" = Indonesian, but PhET historically expected "in".)
         if locale == "id":
             locale = "in"
 
+        # Fresh per-locale stats bucket so the run-summary later has a slot to write into.
         STATS[locale] = {
             "docs": 0,
             "vids": 0,
@@ -252,6 +292,12 @@ def run_with_locale(self, locale):
 
         self.channel_name = self._localized_channel_title(locale)
 
+        # --- Legacy source_id overrides ---
+        # Studio derives the deterministic channel_id from (source_domain, source_id).
+        # Each of these locales was originally published with a non-default source_id,
+        # so we MUST preserve those strings or the chef will push to a brand-new channel
+        # instead of updating the existing one. (This exact bug hit `ht` when its override
+        # was commented out — the "restore ht" change lives on this branch.)
         if locale == "uk":
             # idk why this is the case but... it is
             self.channel_source_id = "channel_PhET_Interactive_Simulations_TEST-uk"
@@ -261,25 +307,32 @@ def run_with_locale(self, locale):
         elif locale == "es":
             # idk why this is the case but... it is
             self.channel_source_id = "phet-html5-simulations-es--ACTUALLY-JUST-A-TEST"
+            # `es` also uses a schemeless domain, so both source_domain AND source_id must match.
             self.channel_domain = "phet.colorado.edu"
-        # elif locale == 'ht':
-        # self.channel_source_id = "channel_PhET_Interactive_Simulations_TEST-ht"
+        elif locale == "ht":
+            self.channel_source_id = "channel_PhET_Interactive_Simulations_TEST-ht"
         elif locale == "en":
+            # English channel uses the "clean" base id (no -locale suffix) since it was published first.
             self.channel_source_id = BASE_SOURCE_ID
             self.channel_domain = "phet.colorado.edu"
         else:
+            # Default path for every locale that doesn't have a legacy override.
             self.channel_source_id = BASE_SOURCE_ID + f"-{locale}"
         self.channel_language = locale
 
-        # Setup translators for new locale
+        # Setup translators for new locale. We instantiate a *new* GoogleTranslator so any
+        # leftover state from the previous locale doesn't leak into this one.
         self.translator = GoogleTranslator(source="auto", target=self.channel_language)
         if locale != "en":
             self.lang_en_translator = GoogleTranslator(
                 source=self.channel_language, target=DEFAULT_LANG
             )
 
+        # Pre-translate the UI strings we prepend to teacher-guide docs/videos so we only
+        # call the translator API once per locale.
         self.teachers_guide = self.translator.translate(text="Coach's Guide")
         self.teachers_video = self.translator.translate(text="Coach's Video")
+        # Description priority: CSV → hard-coded CHANNEL_DESCRIPTIONS → machine-translated English.
         self.channel_description = (
             get_channel_description(locale)
             or self.translator.translate(
@@ -289,10 +342,13 @@ def run_with_locale(self, locale):
         # print("\n\n")
         # print("\n\n")
 
-        # Run the chef again with the new locale
+        # Re-enter the SushiChef pipeline with the newly-configured state. This effectively
+        # runs the whole chef once per locale.
         self.main()
 
     def construct_channel(self, *args, **kwargs):
+        # Diagnostic print so when a run produces a wrong channel_id on Studio we can compare
+        # the (channel_domain, channel_source_id) pair that was used against the expected one.
         print(
             "Running Language: ",
             self.channel_language,
@@ -301,6 +357,8 @@ def construct_channel(self, *args, **kwargs):
             self.channel_source_id,
             self.channel_description,
         )
+        # (source_domain, source_id) are hashed together to form Studio's deterministic
+        # channel_id — so both must be stable across runs for the same channel.
         channel = ChannelNode(
             source_domain=self.channel_domain,
             source_id=self.channel_source_id,
@@ -311,6 +369,8 @@ def construct_channel(self, *args, **kwargs):
         )
         # print("Constructed channel: ", channel.__dict__)
 
+        # Fetch the locale-specific simulation list + localized keyword labels. Categories
+        # are the same shape for every locale (labels are inside `.strings[<locale>]`).
         r_sim = sess.get(
             f"{BASE_URL}/partner-services/2.0/metadata/simulations?locale={self._get_phet_lang_code(self.channel_language)}"
         )
@@ -323,8 +383,11 @@ def construct_channel(self, *args, **kwargs):
         cat_data = json.loads(r_cat.text)
         keyword_data = json.loads(r_keyword.text)
 
+        # Shared across a single locale's run. Avoids downloading+zipping the same sim twice
+        # when the same sim appears under multiple categories (the tree is a DAG, not a pure tree).
         dict_downloaded_paths = {}
 
+        # Start walking at root category "1"; this recursively fills out the full channel.
         self.download_category(
             parent=channel,
             cat_id="1",
@@ -353,6 +416,9 @@ def download_category(
         """
         # print("Processing category:", cat_id)
         cat = categories[str(cat_id)]
+        # Resolve the localized display name with an English fallback. (`cat_name` is not
+        # actually used downstream, but the language resolution pattern is preserved
+        # intentionally — a debugging aid while verifying locale coverage.)
         cat_name = None
         dict_cat_name = cat["strings"]
         if dict_cat_name.get(self.channel_language):
@@ -365,18 +431,24 @@ def download_category(
             # look up the child category by ID
             subcat = categories[str(child_id)]
             # skip it if it's in our blacklist
+            # Blacklist is per-language with English as default (see ID_BLACKLIST_BY_LANG above).
             if subcat["name"] in ID_BLACKLIST_BY_LANG.get(
                 language, ID_BLACKLIST_BY_LANG.get(DEFAULT_LANG, [])
             ):
                 continue
             # make the title human-readable, and clean it up
 
+            # Prefer PhET's localized label, otherwise reconstruct one from the slug-like `name`
+            # (e.g. "math-concepts" → "Math Concepts") and patch a couple of well-known
+            # concatenation glitches from PhET's own labels.
             title = subcat["strings"].get(language)
             if not title:
                 title = subcat["name"].replace("-", " ").title()
                 title = title.replace(" And ", " and ")
                 title = title.replace("Mathconcepts", "Concepts")
                 title = title.replace("Mathapplications", "Applications")
+            # Last-mile manual override for locales whose PhET labels we consider wrong
+            # or missing (see ARABIC_NAME_CATEGORY / HAITIAN_NAME_CATEGORY at the top).
             if language == DEFAULT_LANG:
                 pass
             elif language == "ar":
@@ -384,6 +456,8 @@ def download_category(
             elif language == "ht":
                 title = HAITIAN_NAME_CATEGORY.get(title, title)
 
+            # source_id for a topic is the PhET category `name` — stable across locales
+            # so that the same topic's channel-tree position is stable on Studio.
             subtopic = TopicNode(
                 source_id=subcat["name"], title=title, derive_thumbnail=True
             )
@@ -400,6 +474,7 @@ def download_category(
             )
 
         # loop through all sims in this topic and add them, but only if we're at a leaf topic
+        # (non-leaf categories are shown in Kolibri as a folder of subfolders with no direct sims).
         if len(parent.children) == 0:
             for sim_id in list(set(cat["simulationIds"])):
                 # print("SIM ID: {}".format(sim_id))
@@ -417,6 +492,7 @@ def download_category(
                     )
                     STATS[language]["sims_downloaded"].append(sim_id)
                 except Exception as e:
+                    # Isolate failures per-sim so one bad sim doesn't tank the whole locale run.
                     STATS[language]["sims_skipped"].append(sim_id)
                     print(f"Error downloading sim: {sim_id}", e)
 
@@ -426,11 +502,14 @@ def download_sim(
         """
         Download, zip, and add a node for a sim, as well as any associated video.
         """
+        # Per-sim metadata fetch (one HTTP hit per sim per locale; cached by our session).
         sim_detail_res = sess.get(
             f"https://phet-api.colorado.edu/partner-services/2.0/metadata/simulations/{sim_id}?locale={self._get_phet_lang_code(language)}"
         )
         sim_detail_data = json.loads(sim_detail_res.text)
 
+        # Skip any sim that simply doesn't exist in this locale. English always has all
+        # sims, so we never hit this branch for DEFAULT_LANG.
         if (
             self._get_phet_lang_code(self.channel_language)
             not in sim_detail_data.get("localizedData")
@@ -439,6 +518,9 @@ def download_sim(
             print("No sim for #{} in {}".format(sim_id, language))
             return
 
+        # --- Map PhET metadata → Kolibri metadata (categories + grade levels + a11y) ---
+        # `METADATA_BY_CAT` (imported from metadata_tags.py) translates PhET's numeric
+        # subject/grade/a11y IDs into the constants Kolibri expects.
         subject_ids = sim_detail_data.get("subjectIds", [])  # metadata label-mapped
         metadata = {"categories": [], "grade_levels": [], "accessibility_labels": []}
         for subject_id in subject_ids:
@@ -446,6 +528,8 @@ def download_sim(
             if new_metadata:
                 metadata["categories"] += new_metadata
 
+        # Expand the [low, high] grade-level range into individual Kolibri grade tags.
+        # If PhET only gives a `low`, assume the sim spans exactly one grade.
         low_grade_level_id = sim_detail_data.get("lowGradeLevel", {}).get("id", None)
         high_grade_level_id = sim_detail_data.get("highGradeLevel", {}).get("id", None)
         if low_grade_level_id is not None and high_grade_level_id is None:
@@ -464,6 +548,8 @@ def download_sim(
                 METADATA_BY_CAT.get(high_grade_level_id, [])
             )
 
+        # Build localized tags from PhET's keyword IDs. Skip anything over 30 chars because
+        # Kolibri rejects long tags.
         keyword_ids = sim_detail_data.get("keywordIds", [])  # tags
         tags = []
         for keyword_id in keyword_ids:
@@ -477,6 +563,9 @@ def download_sim(
                 if word and len(word) <= 30:  ## max 30 chars on tags
                     tags.append(word)
 
+        # Accessibility: PhET a11y feature IDs 3 and 4 correspond to "has alt text".
+        # The only Kolibri a11y label we currently support mapping from PhET is alt-text,
+        # so that's the only label we set here.
         a11y_features = list(
             map(lambda f: f["id"], sim_detail_data.get("a11yFeatures", []))
         )  # accessibility features IDs
@@ -485,6 +574,8 @@ def download_sim(
                 # see https://docs.google.com/spreadsheets/d/1M5NQLtXUrGymxlvb4reqJmtUGLPCoXYvVB2P8vBVz_k/edit?gid=1471576465#gid=1471576465
                 metadata.update({"accessibility_labels": [ALT_TEXT_KOLIBRI_ID]})
 
+        # --- Resolve title / description / runUrl ---
+        # Priority is (1) localized fields, then (2) defaultData (English), then (3) machine translation.
         # localized data may or may not have anything, but when it does, we'll use it first
         localized_data = sim_detail_data.get("localizedData", {}).get(
             self._get_phet_lang_code(language), {}
@@ -495,6 +586,9 @@ def download_sim(
 
         run_url = default_data.get("runUrl")
         # Ensure we're downloading the localized sim
+        # PhET's API sometimes returns the English URL inside `defaultData` even when the
+        # sim exists in the target locale, so we swap the `_en.html` suffix for `_<locale>.html`
+        # if we don't explicitly get a localized runUrl.
         if run_url.endswith("_en.html") and language != DEFAULT_LANG:
             run_url = localized_data.get(
                 "runUrl",
@@ -510,6 +604,8 @@ def download_sim(
         document_url = None
 
         if localized_data:
+            # Override every field that the localized blob provides. Anything missing falls
+            # through to the already-assigned default_data values.
             if localized_data.get("runUrl"):
                 run_url = localized_data.get("runUrl")
             if localized_data.get("title"):
@@ -520,6 +616,7 @@ def download_sim(
                 # if there is a `teachersGuide` field in `localizedData`, add it as a document node
                 document_url = localized_data.get("teachersGuide")
         elif self.channel_language != DEFAULT_LANG:
+            # No localized blob at all → translate the English fields into the channel locale.
             if self.translator:
                 title = self.translator.translate(text=title)
             if description and description != localized_data.get("description"):
@@ -529,6 +626,8 @@ def download_sim(
                 # otherwise see if we have a defaultData one (this is really only for english)
                 document_url = default_data.get("teachersGuide")
 
+        # Zip cache: if we've already downloaded+zipped this sim in this run, re-use the zip.
+        # (The same sim can appear under multiple categories, and the zip process is expensive.)
         download_url = f"{BASE_URL_DOWNLOAD}{run_url}?download"
         ##print("\tProcessing sim:", title)
         dst = None
@@ -536,6 +635,7 @@ def download_sim(
             dst = tempfile.mkdtemp()
             dict_downloaded_paths[download_url] = {"dst": dst}
         if dst:
+            # `process_sim_html` strips online-only behavior from the sim so it runs fully offline.
             download_file(
                 download_url,
                 dst,
@@ -548,11 +648,17 @@ def download_sim(
             zippath = create_predictable_zip(dst)
             dict_downloaded_paths.get(download_url).update({"zippath": zippath})
 
+        # PhET's `thanksTo` is human-written HTML-ish prose; strip parenthetical roles and <br>s
+        # to produce a clean comma-separated author string for Kolibri's author field.
         authors = None
         if sim_detail_data.get("thanksTo"):
             authors = re.sub(" \(.*?\)", "", sim_detail_data["thanksTo"])
             authors = re.sub("<br\/?>", ", ", authors)
 
+        # Locale-specific last-mile title overrides.
+        #  - Arabic: category-name lookup, then a typo fix pass.
+        #  - Haitian: category-name lookup only (we trust PhET's title otherwise).
+        #  - All other non-English: fall back to Google Translate.
         if language == "ar":
             if title in ARABIC_NAME_CATEGORY:
                 title = ARABIC_NAME_CATEGORY[title]
@@ -565,6 +671,8 @@ def download_sim(
             if self.translator:
                 title = self.translator.translate(text=title)
         # get thumbnail image
+        # Prefer the 128x128 variant (matches Kolibri's thumbnail expectations); fall back
+        # to whatever is first in the list.
         lst_sim_images = default_data.get("simImages")
         sim_image = lst_sim_images[0].get("url")
         for dict_image in lst_sim_images:
@@ -573,6 +681,7 @@ def download_sim(
                 break
 
         # create a node for the sim
+        # source_id `sim-<numeric id>` is stable across locales so updates replace the same node.
         zippath = dict_downloaded_paths.get(download_url).get("zippath")
         simnode = HTML5AppNode(
             source_id="sim-%d" % sim["id"],
@@ -591,9 +700,12 @@ def download_sim(
             **metadata,
         )
 
+        # DocumentNode / VideoNode don't accept `accessibility_labels`, so strip it from the
+        # metadata dict before reusing it for the document + video below.
         del metadata["accessibility_labels"]
 
         if document_url:
+            # Teacher guide is attached as a Coach-role document right before the sim inside the topic.
             documentnode = DocumentNode(
                 source_id="document-%d" % sim["id"],
                 files=[DocumentFile(document_url)],
@@ -612,6 +724,7 @@ def download_sim(
             topic.add_child(documentnode)
         # if there's a video, extract it and put it in the topic right before the sim
 
+        # --- Primer video handling (two completely different paths for English vs non-English) ---
         # videos = default_data.get('simPrimerVimeoData', {}).get("files", None)
         if self.channel_language == DEFAULT_LANG:
             # we don't use primer_video_url because the english primer video links are inaccessible private
@@ -622,6 +735,7 @@ def download_sim(
             if default_data.get("simPrimerVimeoData"):
                 videos = sim_detail_data["defaultData"]["simPrimerVimeoData"]["files"]
                 if videos:
+                    # Pick the 540p encoding for a reasonable size/quality tradeoff.
                     video_url = [v for v in videos if v.get("height") == 540][0]["link"]
 
                     videonode = VideoNode(
@@ -638,10 +752,15 @@ def download_sim(
 
                     topic.add_child(videonode)
         else:
+            # Non-English: PhET only exposes a single `simPrimerUrl` (usually a YouTube link,
+            # sometimes a Vimeo page URL). No encoded-file variants are available.
             primer_video_url = localized_data.get("simPrimerUrl", None)
 
         # Only for non-English
         if primer_video_url:
+            # YouTube links are resolved through ytdl by yt_id; any other URL goes through
+            # the generic WebVideoFile downloader, which needs the sim's runUrl as Referer
+            # to pass PhET's hotlink checks.
             if "youtube" in primer_video_url:
                 youtube_id = primer_video_url.split("/")[-1]
                 file = YouTubeVideoFile(
@@ -677,8 +796,8 @@ def download_sim(
         topic.add_child(simnode)
 
     def _localized_channel_title(self, locale):
-        if locale == "ht":
-            return "PhET (Kreyòl ayisyen)"
+        # Prefer the manually-curated title from the CSV; otherwise generate a predictable
+        # fallback like "PhET Interactive Simulations (Français)".
         title = get_channel_title(locale)
         if title:
             # print("RETURNING TITLE: ", title)
@@ -692,16 +811,22 @@ def process_sim_html(content, destpath, **kwargs):
     """Remove various pieces of the code that make requests to online resources, to avoid using
     bandwidth for users expecting a fully offline or zero-rated website."""
 
+    # Short-circuit PhET's network connectivity probe so the sim doesn't stall offline
+    # trying to reach phet.colorado.edu.
     # remove "are we online" check
     content = content.replace(
         "check:function(){var t=this", "check:function(){return;var t=this"
     )
 
+    # Kill the list of links the "About" modal would show so no "Visit PhET website" entries appear.
     # remove online links from "about" modal
     content = content.replace(
         "getLinks:function(", "getLinks:function(){return [];},doNothing:function("
     )
 
+    # Inject query params (`allowLinks=false&disableFullscreen`) only when the user hasn't
+    # provided any, so we suppress external-link buttons and fullscreen (which can break
+    # inside Kolibri's iframe) without clobbering a user-supplied query string.
     # setting up the query parameters for cases in which it works
     regex = r"(this\.getAllForString\([^,]+,[^w]*)(window\.location\.search)(\s*\))"
     replacement = r"\1window.location.search === '' ? '?allowLinks=false&disableFullscreen' : window.location.search\3"
@@ -716,6 +841,8 @@ def process_sim_html(content, destpath, **kwargs):
         if "phetWebsite" in str(script):
             # remove menu options that link to online resources
             # fallbacks in case the above regex work fails
+            # Belt-and-suspenders: even if the injected query-string trick above doesn't land
+            # (e.g. PhET changes its source), we still strip the offending menu items directly.
             script.string = re.compile(
                 'tandem: e.createTandem\("screenshotMenuItem"\),'
             ).sub("", script.string)
@@ -755,6 +882,8 @@ def process_sim_html(content, destpath, **kwargs):
 if __name__ == "__main__":
     import argparse
 
+    # --lang lets you run a subset during dev (e.g. `--lang=ar,ht`). Omitting it runs
+    # every locale from `all_locales_mapping.json`.
     parser = argparse.ArgumentParser(description="PhET Chef tool", allow_abbrev=False)
     parser.add_argument(
         "--lang",
@@ -772,6 +901,8 @@ def process_sim_html(content, destpath, **kwargs):
 
     failed_locales = []
 
+    # Per-locale driver loop. A failure in one locale is caught and logged, so one bad
+    # locale (API quirks, translator rate-limits, etc.) doesn't prevent the others from running.
     for locale in locale_keys:
         print("Running locale: {}".format(locale))
         try: