Merge pull request #14 from flashcatcloud/doc-review/2026-03-17

feat: incremental Meilisearch upload with batch and deletion support

Author: ysyneu

.cursor/skills/translate-zh-to-en/SKILL.md

@@ -53,7 +53,16 @@ If no uncommitted changes:
 | MDX components | Keep tags unchanged, translate inner text |
 | Code blocks | Keep code unchanged, translate comments only |
 | Internal links | Update path prefix to `en/` |
-| Image paths | Keep unchanged |
+| Image paths | See **Image Handling** below |
+
+### Image Handling
+
+When translating, check whether the target `en/` file already exists:
+
+- **New translation** (no existing en/ file): Keep image paths from the zh/ source as-is.
+- **Retranslation** (en/ file already exists): Compare image paths between the zh/ source and the existing en/ file. Some docs use **language-specific screenshots** (English UI screenshots in en/, Chinese UI screenshots in zh/) with different CDN hashes. If the existing en/ file has a different image URL at the same position, **keep the en/ version** — it is likely an English screenshot that should not be replaced with the Chinese one. Only adopt the zh/ image path if it is a newly added image with no en/ counterpart.
+
+**How to check**: Before writing the translated file, read the existing en/ file and diff the image URLs. Images with identical URLs across both versions are language-neutral and safe to keep. Images with different URLs (different hash in the CDN path) are language-specific — preserve the en/ version.
 
 ## Example
 
@@ -115,5 +124,6 @@ Always read the full glossary before translating: [glossary.md](glossary.md)
 - [ ] Use correct terminology
 - [ ] Preserve MDX component structure
 - [ ] Update internal link paths
+- [ ] Check existing en/ file for language-specific images before overwriting
 - [ ] Apply Sentence case capitalization
 - [ ] Verify output path mirrors source path

.github/workflows/upload.yml

@@ -15,6 +15,10 @@ name: Upload docs to Meilisearch
 on:
   push:
     branches: [main, test]
+    paths:
+      - 'zh/**'
+      - 'en/**'
+      - 'docs.json'
   workflow_dispatch:
     inputs:
       environment:
@@ -25,6 +29,11 @@ on:
         options:
           - production
           - development
+      full_upload:
+        description: 'Re-upload all docs (use after clearing index or changing settings)'
+        required: false
+        default: false
+        type: boolean
 
 jobs:
   upload:
@@ -33,6 +42,9 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          # Need history for git diff in incremental mode
+          fetch-depth: 2
 
       - name: Install dependencies
         run: |
@@ -45,6 +57,7 @@ jobs:
           MEILI_ENDPOINT: ${{ secrets.MEILI_ENDPOINT }}
           MEILI_API_KEY: ${{ secrets.MEILI_API_KEY }}
           MEILI_INDEX: ${{ secrets.MEILI_INDEX }}
+          FULL_UPLOAD: ${{ github.event.inputs.full_upload || 'false' }}
         run: |
           chmod +x ./scripts/upload.sh
           bash ./scripts/upload.sh