From b3069f537459bcbc130c4de1f27db76bb200160a Mon Sep 17 00:00:00 2001
From: emil <emil28092005@gmail.com>
Date: Sat, 9 May 2026 17:00:13 +0300
Subject: [PATCH] Update CLAUDE.md to reflect current bilingual architecture

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 45 +++++++++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a2e2dce..495fa0b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this is
 
-Randify is a static site (Astro 4 + Tailwind CSS 4) that hosts random-value generators. Only the number generator is live; the rest are catalogued in `src/data/generators.ts` with `status: 'coming-soon'`.
+Randify is a bilingual (EN/RU) static site (Astro 4 + Tailwind CSS 4) hosting random-value generators. All 10 generators are live. Deployed to randify.pro on reg.ru via GitHub Actions + rsync on push to `main`.
 
 ## Commands
 
@@ -14,24 +14,45 @@ npm run build     # Static build → dist/
 npm run preview   # Serve the built dist/ locally
 ```
 
-**Docker (production):** multi-stage build compiles with Node 20 then serves via `nginx:alpine`. The nginx config handles pretty URLs via `try_files $uri $uri/index.html`.
+**Docker (production):** multi-stage build with Node 20, served via `nginx:alpine` with pretty URLs.
 
 ```bash
 docker build -t randify .
 docker run -p 8080:80 randify
 ```
 
-## Architecture
+No test runner or linter is configured.
 
-**Adding a new generator** involves three steps:
+## Adding a new generator
 
-1. Add an entry to `src/data/generators.ts` (set `status: 'live'` when ready).
-2. Create `src/components/generators/<Name>Generator.astro` — interactive logic goes in an inline `<script>` tag (no framework, plain TypeScript compiled by Vite).
-3. Create `src/pages/generators/<slug>.astro` — follows the same layout pattern as `numbers.astro`.
+Every new generator must be created in **both English and Russian simultaneously**.
 
-**Key conventions:**
-- Accent color is `#534AB7` (also exposed as `--accent` CSS custom property in `BaseLayout.astro`).
-- All SVG icons are inlined strings inside `GeneratorCard.astro`; add new ones to the `icons` map there.
-- `AdBanner.astro` is a placeholder component with three size variants (`leaderboard`, `rectangle`, `tile`) — not wired to any ad network yet.
+1. **`src/data/generators.ts`** — add an entry with all fields: `slug`, `title`, `description`, `icon`, `status: 'live'`, `seoTitle`, `seoDescription`, `ruTitle`, `ruDescription`, `ruSeoTitle`, `ruSeoDescription`.
+
+2. **`src/components/generators/<Name>Generator.astro`** — the interactive component. Language detection pattern:
+   - Frontmatter: `const isRu = Astro.url.pathname.startsWith('/ru'); const T = useT(isRu ? 'ru' : 'en');`
+   - Client script: `const isRu = document.documentElement.lang === 'ru';`
+   - Use `T.*` keys for all user-visible strings in the template; use `isRu` ternaries in the `<script>` block.
+
+3. **`src/pages/generators/<slug>.astro`** — English page with `<BaseLayout lang="en">`.
+
+4. **`src/pages/ru/generators/<slug>.astro`** — Russian page with `<BaseLayout lang="ru">`, `ruSeoTitle`/`ruSeoDescription`, breadcrumb back to `/ru/`, Russian `<SeoBlock>` content.
+
+**Critical:** Never use a shared dynamic `[slug].astro` for Russian pages. Astro bundles scripts from all imported components — using a single file that imports all 10 generators causes every Russian page to run all 10 scripts, breaking them. Each page must be its own file importing only its generator.
+
+## i18n system
+
+- **`src/i18n/translations.ts`** — central `en`/`ru` translation objects. All UI strings (labels, buttons, errors, copy/copied feedback) live here. `useT(lang)` returns the typed translation object.
+- **`src/components/LanguageSwitcher.astro`** — fixed top-right EN/RU toggle; persists choice in `localStorage('lang-pref')`.
+- **`src/layouts/BaseLayout.astro`** — accepts `lang` prop (`'en' | 'ru'`), sets `<html lang>`, injects `hreflang` alternates, and includes auto-redirect script (first visit, Russian browser → `/ru/`).
+- English pages: `/generators/<slug>/` — Russian pages: `/ru/generators/<slug>/`
+
+## Key conventions
+
+- Accent color: `#534AB7` (CSS var `--accent` in BaseLayout).
+- All SVG icons are inlined strings in the `icons` map inside `GeneratorCard.astro`; add new ones there.
+- `GeneratorCard.astro` accepts `lang` prop — pass `lang="ru"` on Russian pages to get `ruTitle`/`ruDescription` and `/ru/` links.
+- `SeoBlock.astro` accepts `lang` prop for translated "How to use" / "When to use" headers.
+- `AdBanner.astro` randomises between two Yandex referral links; three size variants: `leaderboard`, `rectangle`, `tile`.
+- Yandex Metrika counter (ID 109130319) is in `BaseLayout.astro`.
 - No client-side router — each generator is a separate static HTML page.
-- No test runner or linter is configured.