adaptyteam
diff --git a/‎.claude/skills/localize/SKILL.md‎
Lines changed: 57 additions & 6 deletions b/‎.claude/skills/localize/SKILL.md‎
Lines changed: 57 additions & 6 deletions
diff --git a/‎.github/workflows/s3-deploy-development.yml‎
Lines changed: 12 additions & 3 deletions b/‎.github/workflows/s3-deploy-development.yml‎
Lines changed: 12 additions & 3 deletions
diff --git a/‎.github/workflows/s3-deploy-production.yml‎
Lines changed: 59 additions & 7 deletions b/‎.github/workflows/s3-deploy-production.yml‎
Lines changed: 59 additions & 7 deletions
@@ -220,9 +220,9 @@ The translation script creates `.mdx` files and `.hashes/` automatically. You on
 
 ## Step 6 — Translate content (phased, gated by native-speaker reviews)
 
-> **Flow overview:** (1) research dictionary terminology → (2) native speaker reviews word-pair list → (3) translate tutorial 7 articles → (4) deploy to develop → (5) native speaker reviews rendered pages → (6) translate the rest.
+> **Flow overview:** (1) research dictionary terminology → (2) native speaker reviews word-pair list → (3) translate tutorial 7 articles → (4) deploy to develop → (5) native speaker reviews rendered pages → (6) translate the rest → (7) on "we are done", run MDX lint + parse checks locally and auto-fix.
 >
-> **Note on `CustomDocCardList`:** This component is already locale-aware — it reads titles from `_sidebar-labels.json` and descriptions from the translated article frontmatter automatically. No extra step is needed; it works correctly once sidebar labels (Step 6g `--sidebars`) and article translations are done.
+> **Note on `CustomDocCardList`:** This component is already locale-aware — it reads titles from `_sidebar-labels.json` and descriptions from the translated article frontmatter automatically. No extra step is needed; it works correctly once sidebar labels (Step 6f `--sidebars`) and article translations are done.
 
 All `translate.mjs` commands require `ANTHROPIC_API_KEY` to be set.
 
@@ -327,7 +327,17 @@ node scripts/translate.mjs --lang {LOCALE} --sidebar capacitor
 node scripts/translate.mjs --lang {LOCALE} --sidebar api
 ```
 
-#### 6g. Translate platform article docs, one platform at a time
+#### 6g. Translate reusable snippets
+
+Reusable MDX snippets in `src/components/reusable/` are skipped by `--platform`, `--ids`, `--sidebar`, and `--sidebars` runs (to avoid re-translating them on every targeted run). They must be translated in their own pass:
+
+```bash
+node scripts/translate.mjs --lang {LOCALE} --reusables
+```
+
+Run this before the platform translations — platform articles import reusables, so the staging build will render mixed-language content until the snippets are translated.
+
+#### 6h. Translate platform article docs, one platform at a time
 
 ```bash
 node scripts/translate.mjs --lang {LOCALE} --platform tutorial
@@ -338,14 +348,53 @@ node scripts/translate.mjs --lang {LOCALE} --platform flutter
 node scripts/translate.mjs --lang {LOCALE} --platform unity
 node scripts/translate.mjs --lang {LOCALE} --platform kmp
 node scripts/translate.mjs --lang {LOCALE} --platform capacitor
+node scripts/translate.mjs --lang {LOCALE} --platform api
 ```
 
-#### 6h. Translate API docs
+`--platform api` translates the MDX articles referenced from `src/data/sidebars/api.json` (e.g. developer CLI guides, server-side API intro/auth pages). This is separate from the OpenAPI YAML specs themselves — those are translated by `--api-specs` below.
+
+#### 6i. Translate API OpenAPI specs
 
 ```bash
 node scripts/translate.mjs --lang {LOCALE} --api-specs
 ```
 
+This translates the YAML specs in `src/api-reference/specs/` (e.g. `adapty-api.yaml` → `adapty-api.{LOCALE}.yaml`) — the source for the rendered API reference pages. Distinct from `--platform api`, which translates the surrounding MDX articles.
+
+#### 6j. Validate MDX parses cleanly before deploy (BLOCKING — triggers on "we are done")
+
+**Trigger:** the user says "we're done", "that's it", "everything is translated", or otherwise signals end of translation work. Do not run this earlier — broken intermediate state is normal during translation.
+
+Two CI checks must pass before merging to `main` (and they're enforced in `s3-deploy-production.yml` via `lint-mdx` and `check-mdx-parse` jobs). Run them locally and resolve issues before the user pushes:
+
+**1. Run the lint check with auto-fix:**
+
+```bash
+node scripts/lint-mdx.mjs --fix
+```
+
+This auto-corrects the `blank-line` rule (missing blank line after the last `import` — Acorn's most common crash). Other rules (e.g. `missing-import` for `client:load` components like `CompoundCalculator`, `SimpleCalculator`) are reported but not auto-fixed; you must add the missing import line at the top of each flagged file.
+
+**2. Run the parse check:**
+
+```bash
+node scripts/check-mdx-parse.mjs
+```
+
+This compiles every `.mdx` under `src/content/docs/`, `src/locales/`, and `src/components/reusable/` using the same MDX plugins Astro uses. It reports every parse error at once (Astro's locale build halts at the first, so this surfaces hidden failures stacked behind it).
+
+**3. Auto-fix the remainder:**
+
+For every remaining issue from either script, read the file at the reported line, identify the cause, and edit it directly. Common causes after translation:
+
+- **JSX comments** (`{/* ... */}`) inside MDX — crash the content collection. Replace with `:::note` callouts.
+- **Inline callout syntax** — `:::note text :::` on one line. Split into three lines: `:::note`, content, `:::`.
+- **Mismatched JSX tags** — usually a `</Tag>` introduced or dropped by the translator. Compare the locale file to the English source and restore the original tag balance.
+- **Smart-quote contamination** in attribute values (e.g. `title=" "`) — replace with straight ASCII quotes.
+- **Stray backslashes** in heading anchors — `\{#id\}` must keep its backslash escapes exactly.
+
+After each edit pass, re-run both scripts. Loop until both exit clean. Only then tell the user the locale is ready to deploy.
+
 ---
 
 ## Step 7 — Algolia: update English crawler + create new locale crawler
@@ -461,8 +510,10 @@ strategy:
 | 6d | Deploy tutorial translations to develop via `sync-branch-to-develop` skill | `sync-branch-to-develop` |
 | 6e | **BLOCKING:** Wait for native speaker to review rendered tutorial pages on staging | — |
 | 6f | Output command to translate sidebar labels | `--sidebars` |
-| 6g | Output commands to translate platform article docs | `--platform` per sidebar |
-| 6h | Output command to translate API specs | `--api-specs` |
+| 6g | Output command to translate reusable snippets (skipped by targeted runs) | `--reusables` |
+| 6h | Output commands to translate platform article docs | `--platform` per sidebar |
+| 6i | Output command to translate API specs | `--api-specs` |
+| 6j | **BLOCKING on "we are done":** Run lint-mdx --fix + check-mdx-parse; auto-fix remaining issues | `scripts/lint-mdx.mjs`, `scripts/check-mdx-parse.mjs` |
 | 7a | Update English crawler exclusion | Algolia dashboard |
 | 7b | Create new locale crawler | Algolia dashboard |
 | 7c | Create new Algolia index | Algolia dashboard |
 
@@ -61,12 +61,12 @@ jobs:
 
       - name: Build English only
         env:
-          NODE_OPTIONS: --max-old-space-size=6144
+          NODE_OPTIONS: --max-old-space-size=8192
         run: npm run prebuild && ASTRO_TELEMETRY_DISABLED=1 BUILD_LOCALES=none npx astro build
 
       - name: Generate markdown exports
         env:
-          NODE_OPTIONS: --max-old-space-size=6144
+          NODE_OPTIONS: --max-old-space-size=8192
         run: npm run build:md:prod
 
       - uses: actions/upload-artifact@v4
@@ -105,9 +105,18 @@ jobs:
 
       - name: Build locale ${{ matrix.locale }}
         env:
-          NODE_OPTIONS: --max-old-space-size=6144
+          NODE_OPTIONS: --max-old-space-size=8192
         run: npm run prebuild && ASTRO_TELEMETRY_DISABLED=1 BUILD_LOCALES=${{ matrix.locale }} npx astro build
 
+      # Generate locale .md / llms.txt / llms-full.txt exports into
+      # build/${{ matrix.locale }}/ so they land in the artifact alongside
+      # the Astro HTML pages.
+      - name: Generate locale markdown exports
+        env:
+          NODE_OPTIONS: --max-old-space-size=8192
+          BUILD_LOCALES: ${{ matrix.locale }}
+        run: npm run build:md:prod
+
       - uses: actions/upload-artifact@v4
         with:
           name: build-${{ matrix.locale }}
 
@@ -55,11 +55,42 @@ jobs:
       - run: npm install github-slugger
       - run: node scripts/check-links/index.mjs --diff --base=last-production-deploy --internal-only
 
+  # Fast-fail static checks for translator-introduced regressions
+  # (missing blank line after imports, missing client:load imports).
+  # Gates both content and translation-only deploy paths.
+  lint-mdx:
+    name: Lint MDX
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: node scripts/lint-mdx.mjs
+
+  # MDX parse sweep: compiles every .mdx file with the same remark plugins
+  # Astro uses, surfaces every parse error in one pass. Astro's locale
+  # builds halt at the first error, so without this gate broken files
+  # stay hidden behind whichever one CI happens to hit first.
+  check-mdx-parse:
+    name: Check MDX parse
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      - run: npm ci
+        env:
+          PUPPETEER_SKIP_DOWNLOAD: '1'
+      - run: node scripts/check-mdx-parse.mjs
+
   # ──────────────────────────────────────────────────────────────
   # Full deploy: English + all locales (on content pushes)
   # ──────────────────────────────────────────────────────────────
   build-en:
-    needs: check-internal-links
+    needs: [check-internal-links, lint-mdx, check-mdx-parse]
     runs-on: ubuntu-latest
     concurrency:
       group: build-en-${{ github.workflow }}-${{ github.ref }}
@@ -85,12 +116,12 @@ jobs:
 
       - name: Build English only
         env:
-          NODE_OPTIONS: --max-old-space-size=6144
+          NODE_OPTIONS: --max-old-space-size=8192
         run: npm run prebuild && ASTRO_TELEMETRY_DISABLED=1 BUILD_LOCALES=none npx astro build
 
       - name: Generate markdown exports
         env:
-          NODE_OPTIONS: --max-old-space-size=6144
+          NODE_OPTIONS: --max-old-space-size=8192
         run: npm run build:md:prod
 
       - uses: actions/upload-artifact@v4
@@ -100,7 +131,7 @@ jobs:
           retention-days: 1
 
   build-locale-full:
-    needs: check-internal-links
+    needs: [check-internal-links, lint-mdx, check-mdx-parse]
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -129,9 +160,19 @@ jobs:
 
       - name: Build locale ${{ matrix.locale }}
         env:
-          NODE_OPTIONS: --max-old-space-size=6144
+          NODE_OPTIONS: --max-old-space-size=8192
         run: npm run prebuild && ASTRO_TELEMETRY_DISABLED=1 BUILD_LOCALES=${{ matrix.locale }} npx astro build
 
+      # Generate locale .md / llms.txt / llms-full.txt exports into
+      # build/${{ matrix.locale }}/ so they're included in the artifact.
+      # Without this, the translation-only deploy (aws s3 sync --delete)
+      # wipes them from S3 on every translator commit.
+      - name: Generate locale markdown exports
+        env:
+          NODE_OPTIONS: --max-old-space-size=8192
+          BUILD_LOCALES: ${{ matrix.locale }}
+        run: npm run build:md:prod
+
       - uses: actions/upload-artifact@v4
         with:
           name: build-${{ matrix.locale }}
@@ -198,7 +239,7 @@ jobs:
   # Translation-only deploy: build + upload only locale dirs
   # ──────────────────────────────────────────────────────────────
   build-locale-only:
-    needs: classify
+    needs: [classify, lint-mdx, check-mdx-parse]
     if: needs.classify.outputs.translation_only == 'true'
     runs-on: ubuntu-latest
     strategy:
@@ -228,9 +269,20 @@ jobs:
 
       - name: Build locale ${{ matrix.locale }}
         env:
-          NODE_OPTIONS: --max-old-space-size=6144
+          NODE_OPTIONS: --max-old-space-size=8192
         run: npm run prebuild && ASTRO_TELEMETRY_DISABLED=1 BUILD_LOCALES=${{ matrix.locale }} npx astro build
 
+      # Generate locale .md / llms.txt / llms-full.txt exports into
+      # build/${{ matrix.locale }}/ so they land in the artifact. Required
+      # because the deploy uses `aws s3 sync --delete`, which would
+      # otherwise remove these files from S3 on every translation-only
+      # update.
+      - name: Generate locale markdown exports
+        env:
+          NODE_OPTIONS: --max-old-space-size=8192
+          BUILD_LOCALES: ${{ matrix.locale }}
+        run: npm run build:md:prod
+
       - uses: actions/upload-artifact@v4
         with:
           name: build-tr-only-${{ matrix.locale }}