From f3ee755f47c83381dd79d6a43da8161d24dc61cf Mon Sep 17 00:00:00 2001
From: SeekingGamer <160568653+SeekingGamer@users.noreply.github.com>
Date: Thu, 21 May 2026 10:19:30 +0800
Subject: [PATCH] fix(docs): Update Readme.md

---
 README.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/README.md b/README.md
index fc66e00..09e2e53 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,41 @@ Figma assets are stored in `public/assets/`. To re-download them (valid for 7 da
 bash scripts/download-assets.sh
 ```
 
+## Cloudflare Cache & the `site-links-client.js` Version Flag
+
+The site is proxied through **Cloudflare**, which aggressively caches static files. Astro's built CSS/JS bundles are safe because they get **content-hashed filenames** on every build (e.g. `_astro/index.Bx3kF9.js`) — Cloudflare never has an old copy because the filename itself changes.
+
+`public/site-links-client.js` is the exception. It lives in `public/` so it always deploys to the same URL (`/site-links-client.js`). Cloudflare caches this URL and will keep serving the old version until either:
+
+- The Cloudflare cache is **purged** (Caching → Purge Everything in the dashboard), or
+- The script URL is **versioned** so Cloudflare treats it as a new file.
+
+The URL is versioned in `src/layouts/Base.astro`:
+
+```html
+<script src="/site-links-client.js?v=2" defer></script>
+```
+
+**Every time you change `site-links-client.js`**, bump this number (`?v=2` → `?v=3`, etc.) and redeploy. Cloudflare will fetch the latest file immediately without needing a cache purge.
+
+| Change type | Cache action needed |
+|---|---|
+| CSS / Astro component change | None — hashed filename handles it |
+| `site-links-client.js` change | Bump `?v=N` in `Base.astro` and redeploy |
+| Emergency full reset | Cloudflare dashboard → Caching → Purge Everything |
+
+## i18n — Adding or Updating Translations
+
+All page copy lives in `src/i18n/translations.ts`. The English (`en`) entry is the base — every other language only needs to override the keys it wants to change; missing keys fall back to English automatically.
+
+Supported languages: `en`, `zh-cn`, `zh-tw`, `es`, `vi`, `pt`, `de`, `fr`, `hi`, `ar`, `ru`, `id`, `ur`, `ja`, `ko`, `ms`.
+
+To add a new language:
+1. Add the locale code to the `languages` array at the top of `translations.ts`.
+2. Add its label to `languageLabels` and `languageNames`.
+3. Add a translation object under `translations` (only the keys you want to override are required).
+4. Create the page route: copy `src/pages/[lang]/index.astro` if it doesn't exist.
+
 ## Design Source
 
 Figma: [Talk Pro — Home Page Desktop](https://www.figma.com/design/Gb8WMJ2RLlcZ0bigoiOQx9/Talk-Pro?node-id=9505-537&m=dev)