azerbaijan-website-build

アゼルバイジャンのウェブサイト構築

アゼルバイジャンの企業向けに、ゼロから75,000ドル以上のエージェンシー品質を備えた魅力的なウェブサイトを構築します。すべてのサイトはアゼルバイジャン語、ロシア語、英語の3言語に対応し、言語切り替え機能を備えています。Astro 5.x + Tailwind CSS v4 で構築し、Vercel にデプロイします。

クイックリファレンス

項目	値
技術スタック	Astro 5.x、Tailwind CSS v4（Vite プラグイン）、npm
言語	アゼルバイジャン語（メイン）、ロシア語、英語
i18n の方式	ディレクトリベース：/az/、/ru/、/en/
画像	Unsplash（ローカル）、スクレイピングした素材、NanoBanana 2
フォント	@fontsource、Latin Extended とキリル文字に対応していること
デプロイ	GitHub リポジトリ → Vercel
プロジェクトの場所	~/Azerbaijan/projects/<slug>/
品質基準	Apple／Stripe／Linear レベル。AI Slop Test に合格すること。

参照ファイル

構築前にこれらを読んでください。必須ルールと技術仕様が記載されています。

• references/design-rules.md — ビジュアルデザインのルール、使用禁止のフォント／色／レイアウト、コンポーネントアーキテクチャ
• references/accessibility-spec.md — WCAG AA の要件、コントラストの最低基準、キーボードナビゲーション
• references/i18n-spec.md — Astro の i18n ルーティング、LanguageSwitcher コンポーネント、hreflang、JSON 文字列
• references/interview-questionnaire.md — オンライン上に情報がない企業向けの構造化されたヒアリング
• references/azerbaijani-design-guide.md — 文化的なデザイン上の配慮、フォントの文字カバー範囲、画像選定
• references/nano-banana-logo.md — NanoBanana 2／Gemini API を使ったロゴ生成

プロジェクト構成

~/Azerbaijan/projects/<slug>/
├── BUSINESS_PROFILE.md         # Phase 1 output
├── BRAND_BRIEF.md              # Phase 2 output
├── SITE_PLAN.md                # Phase 3 output
├── COPY_CHANGES.md             # Phase 6 output
├── QA_REPORT.md                # Phase 7 output
├── scraped/
│   ├── website/                # Crawled website content (markdown)
│   ├── instagram/              # Instagram data
│   ├── facebook/               # Facebook data
│   └── assets/                 # Downloaded images, logos
│       ├── logos/
│       ├── photos/
│       └── gallery/
└── site/                       # Astro project
    ├── src/
    │   ├── layouts/
    │   │   └── BaseLayout.astro
    │   ├── pages/
    │   │   ├── index.astro     # Redirects to /az/
    │   │   ├── az/             # Azerbaijani pages
    │   │   ├── ru/             # Russian pages
    │   │   └── en/             # English pages
    │   ├── components/
    │   │   ├── Header.astro
    │   │   ├── LanguageSwitcher.astro
    │   │   ├── Footer.astro
    │   │   ├── Hero.astro
    │   │   └── ...sections
    │   ├── content/
    │   │   └── i18n/
    │   │       ├── az.json
    │   │       ├── ru.json
    │   │       └── en.json
    │   ├── utils/
    │   │   └── i18n.ts
    │   ├── styles/
    │   │   └── global.css
    │   └── assets/
    │       └── images/
    ├── public/
    │   ├── images/
    │   ├── favicon.svg
    │   └── robots.txt
    ├── astro.config.mjs
    └── package.json

---

フェーズ 1：データ収集

出力： ~/Azerbaijan/projects/<slug>/BUSINESS_PROFILE.md

該当する入力パスを判断し、その手順に従ってください。どのパスでも、同じ標準化された出力を作成します。

パス A — ウェブサイトあり（ソーシャルメディアもある場合があります）

1. ウェブサイトをスクレイピングする：Apify RAG Web Browser（apify/rag-web-browser）を使用します。

   Query: the business website URL
   maxResults: 1
   outputFormats: ["markdown"]
   

   Markdown の出力を scraped/website/ に保存します。

2. JavaScript を多用するサイト（Wix、Squarespace など）の代替手段： Chrome 自動化（mcp__Claude_in_Chrome）を使用して、次の操作を行います。

   • 各ページに移動する
   • スクリーンショットを撮る
   • get_page_text を使って表示テキストを抽出する
   • 画像をダウンロードする

3. 利用可能なソーシャルメディアをスクレイピングする：

   • Instagram： Apify Instagram スクレイパーを使って、プロフィール文、最近の投稿（直近20件）、すべての投稿画像、フォロワー数を抽出します。scraped/instagram/ に保存します。
   • Facebook： Apify Facebook スクレイパーまたは Chrome 自動化を使って、ページ情報、概要セクション、サービス、レビュー、写真を抽出します。scraped/facebook/ に保存します。
   • Twitter/X： アカウントの有無を確認します。存在する場合は、Chrome を使ってプロフィール文と最近の投稿を抽出します。

4. 使用可能な画像をすべて scraped/assets/ にダウンロードします：

   • ロゴ（入手できる中で最高解像度のもの）
   • チーム／スタッフの写真
   • 商品／サービスの写真
   • 内装／外観の写真
   • ギャラリー画像
   • 検証：ファイルサイズが1KBを超えていること（HTML のエラーページは除外します）

5. スクレイピングしたすべてのデータから BUSINESS_PROFILE.md を作成します。

パス B — ソーシャルメディアのみ（ウェブサイトなし）

1. 主な情報源は Instagram です：

   • プロフィール全体をスクレイピングします。プロフィール文、ハイライト、すべての投稿（最大50件）、すべての画像が対象です。
   • 企業名、カテゴリ、連絡先情報（プロフィール文に記載されていることがよくあります）、所在地を抽出します。
   • 品質の高い画像をすべて scraped/assets/ にダウンロードします。

2. Facebook ページ：

   • 概要セクション、サービス一覧、レビュー／推薦文、写真アルバムを抽出します。
   • 写真をダウンロードします。

3. Twitter/X： アカウントの有無を確認し、存在する場合はプロフィール文と最近のコンテンツを抽出します。

4. 不足情報を特定します — ソーシャルメディアだけでは、次の情報が不足していることがよくあります。

   • 詳細なサービスの説明
   • 料金情報
   • チーム情報
   • 企業の沿革
   • 営業時間

   これらを BUSINESS_PROFILE.md の「補完が必要な情報」に記載し、ユーザーに情報を尋ねます。

5. BUSINESS_PROFILE.md を作成します。

パス C — オンライン上の情報がない場合（インタビュー）

1. 質問の全リストは references/interview-questionnaire.md を読んで確認します。
2. 質問は一度にまとめて提示せず、数回に分けてユーザーに提示します。
   • まずは事業の基本情報（名前、業種、所在地、連絡先）から始めます
   • 次にサービスと製品について質問します
   • 続いてブランドとビジュアルアイデンティティについて質問します
   • 最後にコンテンツと機能について質問します
3. ユーザーが提供した情報はそのまま受け入れます。 最低限必要な情報は、事業名、説明、都市名、電話番号、3つ以上のサービスです。
4. 素材を依頼します。 ロゴファイル、写真、マーケティング資料などを依頼します。
5. BUSINESS_PROFILE.md を作成します。推測した項目には [INFERRED]、不足している項目には [NEEDED] を付けます。

BUSINESS_PROFILE.md の形式

# Business Profile: [Business Name]

**Data Source:** Path A (website + social) | Path B (social only) | Path C (interview)
**Date Gathered:** YYYY-MM-DD
**Slug:** [url-safe-slug]

## Business Overview
- **Name:** [Azerbaijani name]
- **Name (English):** [transliteration]
- **Industry:** [category]
- **Year Established:** [year or "Unknown"]
- **Description:** [2-3 sentences about what they do]
- **Unique Selling Points:** [what makes them different]

## Services / Products
| Service | Description | Price (if known) |
|---------|-------------|-----------------|
| ... | ... | ... |

## Target Audience
- **Primary customers:** [description]
- **Language preference:** [AZ / RU / both]
- **Geographic reach:** [local / national / international]

## Brand Personality
- **Tone:** [luxury / professional / friendly / modern / traditional / etc.]
- **Color preferences:** [if expressed or extracted]
- **Inspiration:** [competitor or admired sites]

## Contact & Location
- **Address:** [full address in Azerbaijani]
- **Phone:** [+994 XX XXX XX XX]
- **Email:** [if available]
- **Hours:** [operating hours]
- **WhatsApp:** [if available — very common in Azerbaijan]
- **Social media:**
  - Instagram: [URL]
  - Facebook: [URL]
  - Twitter: [URL]

## Content Inventory
- **About text:** [available / needs writing]
- **Service descriptions:** [available / needs writing]
- **Testimonials:** [count, or "none available"]
- **Team info:** [available / none]

## Image Inventory
| Type | Count | Quality | Notes |
|------|-------|---------|-------|
| Logo | ... | ... | ... |
| Team photos | ... | ... | ... |
| Product photos | ... | ... | ... |
| Interior/exterior | ... | ... | ... |
| Gallery | ... | ... | ... |

## Gaps to Fill
- [ ] [list anything missing that needs to be created, sourced, or asked about]

一時停止ポイント： 作業を続ける前に BUSINESS_PROFILE.md をユーザーに提示し、確認してもらいます。不足している情報について質問します。

---

フェーズ 2：ブランド開発

出力： ~/Azerbaijan/projects/<slug>/BRAND_BRIEF.md

開始前に references/design-rules.md と references/azerbaijani-design-guide.md を読んでください。

ステップ 1：ロゴ

事業にロゴがある場合：

• scraped/assets/logos/ にダウンロードまたはコピーします
• 色を抽出するために分析します
• ウェブでの使用に十分な解像度（幅 200px 以上）があることを確認します

事業にロゴがない場合：

• references/nano-banana-logo.md を読みます
• BUSINESS_PROFILE.md から、事業名、業種、ブランドパーソナリティなどの情報を集めます
• Gemini API 経由で NanoBanana 2 を使用して、ロゴのコンセプトを 3 種類生成します
• ユーザーに選択肢を提示します
• 3 回のラウンドを経ても満足できる案がない場合は、選定したディスプレイフォントを使用したタイポグラフィックロゴに切り替えます（CSS/SVG でスタイルを設定）
• 最終的なロゴを scraped/assets/logos/logo.png に保存します

ステップ 2：カラーパレット

1. ロゴがある場合：ロゴから主要な色を 2～3 色抽出します
2. ロゴがない場合：業種とブランドパーソナリティをもとにパレットを作成します
3. システム全体を定義します：
   • プライマリーカラー（支配色）
   • セカンダリーカラー
   • アクセントカラー（際立ち、注意を引く色）
   • 背景色（オフホワイト系の暖色。純白は使用しません）
   • テキスト色（黒に近い暖色。純黒は使用しません）
   • ニュートラルカラー（ブランドの色相に寄せます）
4. すべての組み合わせが WCAG AA に適合することを確認します：
   • 背景上のテキスト：最低 4.5:1
   • 大きなテキスト：最低 3:1
   • UI コンポーネント：最低 3:1 scripts/contrast-check.js を使って確認します。
5. コントラスト比をコメントとして添え、CSS カスタムプロパティで記述します。

ステップ 3：タイポグラフィ

1. references/design-rules.md の検証済み候補から、ディスプレイ／見出し用フォントと本文用フォントを選びます
2. 両方のフォントで、アゼルバイジャン語のテスト文字列とキリル文字が正しく表示されることを確認します
3. タイポグラフィのサイズ段階を定義します：ディスプレイ、h1、h2、h3、本文、小文字、キャプション
4. すべてのサイズに clamp() を使ったフルイドなサイズ指定を使用します
5. 正しいサブセット（latin、latin-ext、cyrillic、cyrillic-ext）を指定して @fontsource 経由でインストールします

ステップ 4：ブランドボイス

言語ごとのコミュニケーションのトーンを定義します：

• アゼルバイジャン語：［温かみのある／フォーマル／カジュアル］ — 主要なブランドボイスです
• ロシア語： 通常はややフォーマルにします
• 英語： 明快で、国際的かつプロフェッショナルなトーンにします

ステップ 5：ブランドカード

以下を含む HTML ブランドカード（単一の HTML ファイル）を作成します：

• ロゴ（またはプレースホルダー）
• HEX コードとコントラスト比を含むカラーパレット
• 3 言語すべてのタイポグラフィのサンプル
• ブランドボイスの概要
• アゼルバイジャン語のタグライン／見出しの候補

プロジェクトのルートに保存し、レビュー用に開きます。

Step 6: DESIGN.md を生成する

ブランドカードの作成後、design-system-generator スキルとアゼルバイジャン向け拡張機能を使用して、構造化された DESIGN.md を作成します。

1. 基本となる9セクション形式について、00-design-references/design-md-format.md を読みます。
2. ブランドの方向性に合う参考用の DESIGN.md ファイルを、00-design-references/references/by-aesthetic/ から1～2個選びます。
3. 次の内容を含む DESIGN.md を生成します。標準の9セクションすべてに加えて、セクション10：多言語への配慮を含めます。
   • フォントの検証用テスト文字列：「Əlaqə üçün bizə zəng edin. Ğəbul saatları: Ş. 09:00-18:00 | Связаться с нами」
   • ロシア語のテキストが約30％拡大することを想定した、レイアウト、ボタン、ナビゲーションの対応ルール
   • アゼルバイジャンの文化を踏まえた色の注意点（国旗の色は控えめに使用し、高級感にはゴールドを使用）
   • 言語ごとのコンテンツのトーン（AZ：親しみやすくフォーマル、RU：ややフォーマル、EN：洗練された国際的な表現）
4. BRAND_BRIEF.md の「カラーパレット」と「タイポグラフィ」セクションには「完全なデザインシステムについては DESIGN.md を参照」と記載します。BRAND_BRIEF.md にはブランドボイス、ロゴのメタデータ、デザイン以外の内容を残します。

出力： ~/Azerbaijan/projects/<slug>/DESIGN.md

BRAND_BRIEF.md の形式

# Brand Brief: [Business Name]

## Logo
- Source: [existing / generated / typographic]
- File: [path to logo file]

## Color Palette
| Token | Hex | Usage | Contrast vs bg |
|-------|-----|-------|----------------|
| --color-primary | #xxx | Headings, buttons | X.X:1 AA PASS |
| --color-secondary | #xxx | Accents | X.X:1 AA PASS |
| --color-accent | #xxx | CTAs, highlights | X.X:1 AA PASS |
| --color-bg | #xxx | Page background | — |
| --color-text | #xxx | Body text | X.X:1 AA PASS |

## Typography
- **Display:** [Font Name] — [weights]
- **Body:** [Font Name] — [weights]
- **Verified:** AZ characters ✓ | Cyrillic ✓

> **Note:** Complete design system specification (color tokens, typography hierarchy table, component stylings, shadow system, layout principles) is in `DESIGN.md`. The sections below are summaries — see DESIGN.md for exact values.

## Brand Voice
- **AZ:** [description]
- **RU:** [description]
- **EN:** [description]

## Aesthetic Direction
- **Tone:** [chosen aesthetic]
- **Differentiation:** [the unforgettable thing]

一時停止ポイント： BRAND_BRIEF.md とブランドカードをユーザーに提示し、承認を得てから次に進みます。

---

Phase 3: コンテンツ戦略とサイトアーキテクチャ

出力： ~/Azerbaijan/projects/<slug>/SITE_PLAN.md

Step 1: ページ構成

ビジネスの種類と利用可能なコンテンツに基づいて、サイトマップを定義します。一般的な構成は次のとおりです。

標準（ほとんどのビジネス）：

• ホーム（/az/、/ru/、/en/）
• 会社概要（/az/haqqimizda/、/ru/o-nas/、/en/about/）
• サービス（/az/xidmetler/、/ru/uslugi/、/en/services/）
• お問い合わせ（/az/elaqe/、/ru/kontakty/、/en/contact/）

拡張（コンテンツがある場合）：

• ギャラリー（/az/qalereya/、/ru/galereya/、/en/gallery/）
• ブログ（/az/bloq/、/ru/blog/、/en/blog/）
• 料金（/az/qiymetler/、/ru/tseny/、/en/pricing/）
• メニュー（レストランの場合：/az/menyu/、/ru/menyu/、/en/menu/）

Step 2: ページごとのコンテンツ計画

各ページについて、次の内容を定義します。

• セクション（ヒーロー、概要、サービス一覧、お客様の声、CTA など）
• アゼルバイジャン語のコピー方針（各セクションで伝える内容）
• セクションごとに必要な画像（既存のものと必要なもの）
• インタラクティブ要素（アコーディオン、ギャラリーのライトボックス、お問い合わせフォーム、地図）

Step 3: 画像戦略

必要な画像をすべて分類します。

セクション	必要な画像	入手元	状態
ヒーロー	ヒーロー背景	Unsplash / NanoBanana	[need]
概要	チーム／オフィスの写真	スクレイピング	[have]
サービス	サービスのイラスト	Unsplash	[need]
...	...	...	...

Unsplash の画像は今すぐすべてダウンロードします — ビルドフェーズの前に実施します。

1. 必要な画像ごとに Unsplash を検索します。
2. 文化的に適切であることを確認します（references/azerbaijani-design-guide.md を参照）。
3. Astro の最適化を使う場合は site/src/assets/images/ に、静的ファイルの場合は site/public/images/ にダウンロードします。
4. hero-restaurant-baku.jpg、team-working.jpg のように、内容がわかる名前を付けます。
5. 外部 URL へのホットリンクは絶対に行いません。

Step 4: SEO 計画

• アゼルバイジャン語（優先）、ロシア語、英語のターゲットキーワード
• JSON-LD のスキーマタイプ（LocalBusiness、Restaurant など）
• ページごと、言語ごとのメタタイトル／説明文のテンプレート
• hreflang の代替ページを含むサイトマップ戦略

SITE_PLAN.md の形式

上記のすべてを文書にまとめます。これはビルドフェーズの設計図です。

一時停止ポイント： SITE_PLAN.md をユーザーに提示します。これがビルド前の最後のチェックポイントです。

---

フェーズ 4：画像の選定

成果物： すべての画像を Astro プロジェクト内に整理します

1. スクレイピングした画像を処理します：

   • 使用可能な画像を scraped/assets/ から site/src/assets/images/ にコピーします
   • サイズの大きすぎる画像をリサイズします（幅は最大 2000px）
   • ウェブで使用するのに十分な品質であることを確認します

2. Unsplash の画像をダウンロードします（SITE_PLAN.md の画像戦略に従います）：

   • Unsplash API を使用するか、ウェブで検索して適切な画像を見つけます
   • 各画像を site/src/assets/images/ または site/public/images/ にダウンロードします
   • アゼルバイジャンの文化に関する画像ガイドラインに従います
   • 本番コードでは外部の Unsplash URL を絶対に使用しないでください

3. 必要に応じて NanoBanana 2 で画像を生成します：

   • ヒーローの背景
   • オリジナル画像がない場合の商品・サービス画像
   • API の使用方法については references/nano-banana-logo.md を参照してください

4. すべての画像を確認します：

   • 色温度はブランドパレットに合っていますか？
   • アゼルバイジャンの文化に適していますか？
   • 実際の顧客層に適した属性の人物が写っていますか？
   • 漠然と関連しているだけでなく、セクションの文章に合っていますか？

5. フォルダーに整理します：

   site/src/assets/images/
   ├── hero/
   ├── about/
   ├── services/
   ├── gallery/
   ├── team/
   └── general/
   

---

フェーズ 5：ウェブサイトの構築

構築を始める前に、すべての参考ファイルを読んでください：

• references/design-rules.md — デザインルール（必ず遵守してください）
• references/accessibility-spec.md — WCAG AA の要件
• references/i18n-spec.md — i18n ルーティング、LanguageSwitcher、hreflang

ステップ 1：Astro プロジェクトを初期化します

cd ~/Azerbaijan/projects/<slug>
npm create astro@latest site -- --template minimal --no-install
cd site
npm install
npx astro add tailwind --yes
npx astro add sitemap --yes
npm install -D prettier

フォントをインストールします（例）：

npm install @fontsource/dm-sans @fontsource/playfair-display

ステップ 2：Astro を設定します

astro.config.mjs で：

• site に想定される Vercel URL を設定します
• i18n を含むサイトマップを設定します（references/i18n-spec.md を参照）
• デフォルトロケールを az として i18n ルーティングを設定します

ステップ 3：デザインシステムを構築します

デザインシステムの構築前に、プロジェクトの DESIGN.md を読んでください。 すべての CSS カスタムプロパティ、フォントのインポート、タイポグラフィのスケール、コンポーネント仕様、シャドウトークンの信頼できる情報源として使用します。作業を進める前に、DESIGN.md のフォントが AZ/RU 文字の検証テストに合格することを確認してください。

src/styles/global.css を作成します：

• フォントパッケージをインポートします
• BRAND_BRIEF.md にあるすべての CSS カスタムプロパティを定義します
• コントラスト比をコメントとして記載します
• clamp() でタイポグラフィのスケールを定義します
• 基本スタイル（body、見出し、リンク）を設定します

ステップ 4：i18n の基盤を構築します

references/i18n-spec.md に従って：

• getLang()、getStrings()、switchLang()、getAlternateLinks() を含む src/utils/i18n.ts を作成します
• UI 文字列を含む src/content/i18n/az.json、ru.json、en.json を作成します
• /az/ にリダイレクトするルート src/pages/index.astro を作成します

ステップ 5：レイアウトと共有コンポーネントを構築します

1. BaseLayout.astro：

   • i18n ユーティリティから取得した <html lang> 属性
   • 3 言語すべての hreflang リンクと x-default を含む <head>
   • 言語ごとの Open Graph / Twitter Card メタデータ
   • フォントのインポート
   • グローバル CSS のインポート
   • View Transitions
   • コンテンツへのスキップリンク

2. Header.astro：

   • ナビゲーションリンク（i18n 文字列を使って翻訳）
   • LanguageSwitcher コンポーネント
   • モバイル用ハンバーガーメニュー
   • スティッキー／固定位置

3. LanguageSwitcher.astro：

   • 国旗インジケーター付きの AZ | RU | EN
   • 現在のページパスを保持します
   • アクティブな言語に aria-current を設定します
   • 実装の詳細については references/i18n-spec.md を参照してください

4. Footer.astro：

   • BUSINESS_PROFILE.md の連絡先情報
   • ソーシャルメディアへのリンク
   • 現在の年を含む著作権表示
   • すべてのテキストを i18n 文字列から取得します

ステップ 6：ページのセクションをコンポーネントとして構築します

視覚的に区別されるセクションは、それぞれ独立した .astro コンポーネントにします：

• Hero.astro — 画像／オーバーレイ、見出し、CTA を含む全幅のヒーロー
• About.astro — 事業のストーリー／説明
• Services.astro — サービスのグリッド／カード
• Testimonials.astro — 顧客の引用／レビュー
• CTA.astro — 行動喚起バナー
• Gallery.astro — 写真のグリッド／ライトボックス（該当する場合）
• Contact.astro — お問い合わせフォーム、地図、情報
• 必要に応じて追加のセクション

各コンポーネントには、言語別のコンテンツを props として渡します。 言語ごとのページファイルから、共有コンポーネントに適切なコンテンツを渡します。

ステップ 7：アゼルバイジャン語のページを先に作成する

src/pages/az/ 配下のすべてのページを作成します：

• az/index.astro — ホームページ
• az/haqqimizda.astro — 概要
• az/xidmetler.astro — サービス
• az/elaqe.astro — お問い合わせ
• SITE_PLAN.md に基づく追加ページ

すべてのコンテンツをネイティブのアゼルバイジャン語で書きます。アゼルバイジャン語が主要言語です。翻訳調ではなく、自然な文章にする必要があります。

ステップ 8：デザインルールを適用する

references/design-rules.md のチェックリストを確認します：

• 4種類以上の異なるレイアウトパターンを使用している
• 連続するセクションで同じカラム構成を使用していない
• 使用禁止フォントを使っていない
• カラーシステムに CSS カスタムプロパティを使用している
• すべてのコントラスト比が WCAG AA を満たしている
• 3種類以上の異なるアニメーションを使用している
• 2つ以上のセクションでスクロールに応じた表示効果を使用している
• 視覚的な奥行きがある（ノイズ、グラデーション、SVG シェイプ、シャドウ）
• コンポーネントアーキテクチャを採用している（モノリシックなページにしない）
• AI スロップテスト：AI が作ったと思われるか？ そうなら、デザインを見直す

ステップ 9：レスポンシブデザイン

• モバイルファースト：320px 以上を対象とする基本スタイル
• ブレークポイント：640px（sm）、768px（md）、1024px（lg）、1280px（xl）、1536px（2xl）
• max-width ではなく min-width メディアクエリを使用する
• タッチターゲット：高さを最低 44px にする
• すべてのブレークポイントで確認し、横スクロールバーが表示されないようにする

ステップ 10：SEO の実装

ページごと、言語ごとに、以下を設定します：

• 固有の <title> と <meta name="description">
• JSON-LD スキーマ（LocalBusiness または適切なタイプ）
• hreflang <link> タグ（i18n-spec.md を参照）
• i18n の代替ページに対応した @astrojs/sitemap によるサイトマップ
• public/ 内の robots.txt
• セマンティック HTML（<main>、<nav>、<article>、<section>）
• すべての画像にページの言語で説明的な alt テキストを設定する

ステップ 11：ファビコン

• ロゴから生成する
• 最低限、public/favicon.svg を用意する
• BaseLayout の <head> に追加する

---

フェーズ 6：コピーと翻訳

ステップ 1：アゼルバイジャン語のコピー（主要言語）

アゼルバイジャン語のページコンテンツをすべて確認します：

• 5秒以内に価値提案が明確に伝わるか？
• すべてのページに、目に見えるメリット重視の CTA があるか？
• コピーは機能ではなく、メリットを先に伝えているか？
• 顧客の懸念に早い段階で対応しているか？
• 可能な場合は具体的な数値を使っているか？
• 印象を強める短い文になっているか？
• 読解レベルが中学2年生相当か？

改善内容を COPY_CHANGES.md に記録します。

ステップ 2：ロシア語への翻訳

src/pages/ru/ 配下のすべてのページを作成します：

• 逐語訳ではなく、表現を調整します。 ロシア語では文の構造や丁寧さの基準が異なります。
• ロシア語のテキストは英語より約30％長くなります。レイアウトが崩れないか確認します
• ロシア語の適切な慣習を使います（ビジネスサイトでは丁寧な「вы」を使用）
• URL スラッグはロシア語のローマ字表記にします：/ru/o-nas/、/ru/uslugi/、/ru/kontakty/

ステップ 3：英語への翻訳

src/pages/en/ 配下のすべてのページを作成します：

• 明快でプロフェッショナルな国際英語を使用します
• 標準的な URL スラッグを使います：/en/about/、/en/services/、/en/contact/
• このバージョンは、旅行者、海外在住者、海外の連絡先向けです

ステップ 4：UI 文字列

3つの JSON ファイル（az.json、ru.json、en.json）をすべて更新します：

• ナビゲーションのラベル
• ボタンのテキスト（CTA、フォーム）
• フッターのコンテンツ
• フォームのラベルとプレースホルダー
• エラーメッセージ
• メタディスクリプション

ステップ 5：完成度を確認する

すべてのページとすべての言語の組み合わせを確認します：

• プレースホルダーテキストが残っていない
• 翻訳されていない文字列がない
• i18n の参照がすべて正しく機能する
• すべての JSON 文字列キーが一貫して使用されている

---

フェーズ 7：QA（統合ラウンド）

出力： ~/Azerbaijan/projects/<slug>/QA_REPORT.md

開発サーバーを起動し、すべてを体系的に確認します：

cd ~/Azerbaijan/projects/<slug>/site
npm run dev

7.1 機能 QA（3言語すべて）

• すべてのナビゲーションリンクが機能する
• すべてのページから言語切り替えが機能する（現在のページを維持する）
• ルート / が /az/ にリダイレクトする
• すべての画像が読み込まれる（画像切れがない）
• お問い合わせフォームが機能する（該当する場合）
• ソーシャルメディアのリンクが正しく開く
• 電話番号／メールアドレスのリンクが機能する（tel:、mailto:）
• WhatsApp のリンクが機能する（該当する場合）
• 地図の埋め込みが機能する（該当する場合）
• すべての言語プレフィックスで 404 ページが機能する

7.2 ビジュアル QA

• デザインルールのチェックリストに合格している（4 種類以上のレイアウト、禁止要素なし）
• アニメーションが滑らかで、カクつきがない
• すべてのページでブランディングに一貫性がある
• 画像の品質が高く、サイズが適切である
• 「AI が作ったような粗雑さ」がない — 人間のデザイナーが承認できる仕上がりか？
• 画像上にテキストを配置したセクションに暗いオーバーレイがある
• すべてのページで視覚的な階層が明確である

7.3 レスポンシブ QA（各ビューポートで 3 言語すべてをテスト）

• 320px（モバイル） — すべての言語
• 768px（タブレット） — すべての言語
• 1024px（小型デスクトップ） — すべての言語
• 1280px（デスクトップ） — すべての言語
• 1536px 以上（大型） — すべての言語
• どのビューポートでも横スクロールバーが表示されない
• 最も長いロシア語のテキストでもレイアウトが崩れない
• モバイルのタッチターゲットが 44px 以上である
• モバイルナビゲーションが正しく動作する

7.4 アクセシビリティ QA

• すべてのページで axe-core を実行する（重大／深刻な問題をすべて修正）
• すべての色の組み合わせのコントラストを確認する（scripts/contrast-check.js）
• キーボードで操作できる（すべてのインタラクティブ要素を Tab キーで移動できる）
• コンテンツへのスキップリンクがあり、機能する
• すべての画像に代替テキストがある（適切な言語で記述）
• prefers-reduced-motion によりアニメーションが無効になる
• フォーカスインジケーターが見える

7.5 SEO QA

• すべてのページで hreflang タグが正しい（AZ、RU、EN、x-default）
• JSON-LD スキーマが各言語で有効である
• サイトマップにすべてのページと言語の組み合わせが含まれている
• robots.txt があり、内容が正しい
• ページごと、言語ごとに固有のタイトルとメタディスクリプションがある
• セマンティック HTML が正しく使用されている
• カノニカル URL が正しい

7.6 コンテンツ QA

• 3 言語すべてのコンテンツが完成しており、プレースホルダーがない
• アゼルバイジャン語が自然で、翻訳調になっていない
• ロシア語が自然で、適切な丁寧さになっている
• 英語が明瞭でプロフェッショナルである
• 未翻訳の UI 文字列がない
• ビジネス情報が正確である（名称、住所、電話番号、営業時間）

7.7 画像 QA

画像の破損チェックを実行します：

Array.from(document.querySelectorAll('img')).filter(img => !img.complete || img.naturalWidth === 0).map(img => img.src)

• どのページにも破損した画像がない
• 外部画像 URL やホットリンクされた画像 URL がない
• すべての画像が最適化されている（Astro <Image> または適切なサイズ）

修正と再確認

見つかった問題をすべて修正します。修正した項目を再確認します。すべての内容を QA_REPORT.md に記録します。

---

フェーズ 8：デプロイ

ステップ 1：ビルドテスト

cd ~/Azerbaijan/projects/<slug>/site
npm run build

ビルドエラーがあれば修正します。ビルドがエラーなく成功する必要があります。

ステップ 2：Git の設定

cd ~/Azerbaijan/projects/<slug>/site
git init
# Ensure .gitignore exists (Astro generates one)
# Verify .env.local is in .gitignore
git add .
git commit -m "Initial build: [business name] - tri-lingual website (AZ/RU/EN)"

ステップ 3：GitHub

新しい GitHub リポジトリを作成します：<slug>-az

gh repo create <slug>-az --public --source=. --push

ステップ 4：Vercel

Vercel にデプロイします：

npx vercel --yes
npx vercel --prod

または、Vercel ダッシュボードから接続して、プッシュ時に自動デプロイするように設定します。

ステップ 5：公開後の確認

公開中の Vercel URL を開き、次の項目を確認します：

• 3 言語すべてのバージョンが読み込まれる
• 言語切り替えが機能する
• すべての画像が読み込まれる
• フォームが機能する
• SSL 証明書が有効である（https）
• パフォーマンスに問題がない（Lighthouse で確認）

ステップ 6：アクセシビリティの最終スキャン

最終確認として、公開中の URL に対して axe-core を実行します。

ステップ 7：納品

次の情報をユーザーに提供します：

• 公開 URL
• GitHub リポジトリ URL
• 構築した内容の概要（ページ、機能、言語）

---

ルールと基準

妥協不可

1. 3 言語対応は必須です。 すべてのページを AZ、RU、EN で用意する必要があります。すべての UI 文字列を翻訳する必要があります。
2. 主言語はアゼルバイジャン語です。 アゼルバイジャン語のコンテンツを最初に作成します。翻訳のようではなく、自然な文章でなければなりません。
3. WCAG AA に準拠します。 コントラスト比を検証し、キーボード操作が機能し、代替テキストがあることを確認します。
4. 画像はすべてローカルに配置します。 外部 URL のホットリンクは使用しません。すべてダウンロードします。
5. フォントは両方の文字体系をサポートする必要があります。 ラテン文字拡張（AZ）とキリル文字（RU）に対応していることを、使用前に確認します。
6. デザインルールを適用します。 references/design-rules.md を参照してください。禁止されているフォント、色、レイアウトは使用しません。
7. AI っぽさのチェック。 AI が作ったように見える場合は、デザインをやり直します。
8. 文化的な適切さ。 画像、トーン、デザインは、ありきたりなアメリカ風ではなく、アゼルバイジャンらしさを感じさせる必要があります。

技術標準

• Tailwind CSS v4（Vite プラグイン）を使用した Astro 5.x
• npm のみ（pnpm、yarn は不可）
• セルフホスト可能なフォントには @fontsource
• 画像の最適化には Astro <Image> コンポーネント
• CSS のみのアニメーション（JavaScript のアニメーションライブラリは使用しない）
• ページナビゲーションには View Transitions
• 全体を通して セマンティック HTML
• モバイルファーストのレスポンシブデザイン
• パフォーマンス目標は Lighthouse 95+

コピーの基準

• フック → 問題 → 解決策 → 証拠 → 行動（すべてのページ）
• 価値提案が 5 秒以内に明確に伝わること
• 機能ではなくメリットを先に伝えること
• あいまいな主張より具体的な数値を使うこと
• 8 年生相当の読みやすさ
• 印象に残る短い文
• CTA や意思決定のポイントの近くに推薦文を配置すること