diff --git a/.claude/skills/i18n/SKILL.md b/.claude/skills/i18n/SKILL.md index 220d6a0..69d2260 100644 --- a/.claude/skills/i18n/SKILL.md +++ b/.claude/skills/i18n/SKILL.md @@ -24,23 +24,60 @@ translations/ │ ├── articles.json │ ├── curated-collections.json │ ├── stacks.json -│ └── comparison.json +│ ├── comparison.json +│ ├── landscape.json +│ ├── open-source-rank.json +│ └── search.json ├── de/ # German +├── es/ # Spanish +├── fr/ # French +├── id/ # Indonesian +├── ja/ # Japanese +├── ko/ # Korean +├── pt/ # Portuguese +├── ru/ # Russian +├── tr/ # Turkish ├── zh-Hans/ # Simplified Chinese -└── ko/ # Korean +└── zh-Hant/ # Traditional Chinese ``` **Important:** Each locale must maintain the exact same file structure and JSON key order as `en/`. +## I18n Architecture + +The project has **two separate internationalization systems** that share the same 12 locale configuration: + +### 1. UI Translation System (next-intl) +- **Purpose:** Translates static UI strings (buttons, labels, page content, etc.) +- **Location:** `translations/{locale}/*.json` +- **Usage:** Via `useTranslations()` hook or `getTranslations()` server function +- **Managed by:** This skill's sync and translate commands + +### 2. Manifest Translation System +- **Purpose:** Translates manifest data (IDEs, CLIs, models, providers, etc.) +- **Location:** `manifests/**/*.json` (in each manifest file's `translations` field) +- **Usage:** Via `localizeManifestItem()` and `localizeManifestItems()` functions +- **Managed by:** Manual editing of manifest files or manifest automation tools + +**This skill manages only the UI Translation System.** For manifest translations, edit the manifest JSON files directly or use the manifest-automation skill. + ## Enabled Locales Currently enabled locales in `src/i18n/config.ts`: - `en` - English (source of truth) - `de` - Deutsch (German) -- `zh-Hans` - 简体中文 (Simplified Chinese) +- `es` - Español (Spanish) +- `fr` - Français (French) +- `id` - Bahasa Indonesia (Indonesian) +- `ja` - 日本語 (Japanese) - `ko` - 한국어 (Korean) +- `pt` - Português (Portuguese) +- `ru` - Русский (Russian) +- `tr` - Türkçe (Turkish) +- `zh-Hans` - 简体中文 (Simplified Chinese) +- `zh-Hant` - 繁體中文 (Traditional Chinese) -Additional locale directories may exist but are not enabled in the config. +All 12 locales are fully enabled and must be maintained in sync. ## Subcommands @@ -117,13 +154,13 @@ Generate translation tasks for Claude Code to translate missing content. When you need to translate content, use this command in Claude Code: ``` -Please run the i18n translate command for zh-Hans +Please run the i18n translate command for ja ``` Claude Code will execute: ```bash -node .claude/skills/i18n/scripts/translate.mjs zh-Hans +node .claude/skills/i18n/scripts/translate.mjs ja ``` **Workflow:** @@ -145,13 +182,13 @@ node .claude/skills/i18n/scripts/translate.mjs zh-Hans **Output Example:** ``` -🌐 Translation Assistant for zh-Hans +🌐 Translation Assistant for ja ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📝 Translation Task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Target Language: 简体中文 (Simplified Chinese) +Target Language: 日本語 (Japanese) Entries to translate: 15 Files affected: @@ -168,6 +205,7 @@ Files affected: Content to translate: +```json { "components.languageSwitcher.english": "English", "pages.home.hero.title": "Welcome to AI Coding Stack", @@ -175,6 +213,7 @@ Content to translate: ... } ``` +``` --- @@ -205,7 +244,16 @@ Each locale has: // translations/en/index.ts import components from './components.json' import articles from './pages/articles.json' -// ... other imports +import comparison from './pages/comparison.json' +import curatedCollections from './pages/curated-collections.json' +import docs from './pages/docs.json' +import home from './pages/home.json' +import landscape from './pages/landscape.json' +import manifesto from './pages/manifesto.json' +import openSourceRank from './pages/open-source-rank.json' +import search from './pages/search.json' +import stacks from './pages/stacks.json' +import shared from './shared.json' const messages = { shared, @@ -216,8 +264,11 @@ const messages = { docs, articles, curatedCollections, - ...stacks, + stacks, comparison, + landscape, + openSourceRank, + search, }, } @@ -244,45 +295,59 @@ Becomes: `pages.home.hero.title = "Welcome"` ### Adding a New Language +**Note:** The project currently supports 12 locales. To add a new locale (e.g., Italian 'it'): + 1. Add the locale to `src/i18n/config.ts`: ```typescript -export const locales = ['en', 'de', 'zh-Hans', 'ko', 'ja'] as const; // Add 'ja' +export const locales = [ + 'en', 'de', 'es', 'fr', 'id', 'ja', 'ko', 'pt', 'ru', 'tr', 'zh-Hans', 'zh-Hant', + 'it' // Add new locale +] as const; ``` 2. Update locale names: ```typescript export const localeNames: Record = { - // ... - ja: '日本語', + // ... existing locales + it: 'Italiano', } export const localeToOgLocale: Record = { - // ... - ja: 'ja_JP', + // ... existing locales + it: 'it_IT', +} +``` + +3. Add to translate.mjs LOCALE_NAMES (`.claude/skills/i18n/scripts/translate.mjs`): + +```javascript +const LOCALE_NAMES = { + // ... existing locales + it: 'Italiano (Italian)', } ``` -3. Create the locale directory structure: +4. Create the locale directory structure: ```bash -mkdir -p translations/ja/pages -cp translations/en/index.ts translations/ja/index.ts -cp translations/en/*.json translations/ja/ -cp translations/en/pages/*.json translations/ja/pages/ +mkdir -p translations/it/pages +cp translations/en/index.ts translations/it/index.ts +cp translations/en/*.json translations/it/ +cp translations/en/pages/*.json translations/it/pages/ ``` -4. Run sync to ensure structure matches: +5. Run sync to ensure structure matches: ``` Please run the i18n sync command ``` -5. Run translate to generate translation tasks: +6. Run translate to generate translation tasks: ``` -Please run the i18n translate command for ja +Please run the i18n translate command for it ``` ## Best Practices @@ -329,7 +394,45 @@ const rawMessages = (await import(`../../translations/${locale}/index.ts`)).defa const messages = resolveReferences(rawMessages) ``` -The JSON files are loaded through the index.ts for each locale, and the `resolveReferences` function handles `@:path` reference syntax. +The JSON files are loaded through the index.ts for each locale, and the `resolveReferences` function handles reference syntax. + +### Reference Resolution + +The project supports **reference syntax** for reusing translations: + +**Basic Reference:** `@:path.to.key` +```json +{ + "shared": { + "appName": "AI Coding Stack", + "welcome": "Welcome to @:shared.appName" + } +} +// Result: "Welcome to AI Coding Stack" +``` + +**Reference with Modifiers:** `@.modifier:path.to.key` + +Supported modifiers: +- `@.upper:path` - Convert to UPPERCASE +- `@.lower:path` - Convert to lowercase +- `@.capitalize:path` - Capitalize first letter + +```json +{ + "terms": { + "documentation": "documentation", + "title": "@.capitalize:terms.documentation Guide" + } +} +// Result: "Documentation Guide" +``` + +**Important:** +- References are resolved at runtime by `src/i18n/lib-core.ts` +- Circular references are detected and will throw an error +- References can be nested (references within references) +- Keep reference syntax intact during translation ## License diff --git a/.gitignore b/.gitignore index 2f7be8d..04693f5 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,8 @@ .DS_Store *.pem +/tmp + # debug npm-debug.log* yarn-debug.log* diff --git a/CLAUDE.md b/CLAUDE.md index 0591384..945161e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Internationalization (i18n) When creating or modifying any page, module, or data: -- **MUST support at least 4 languages:** English, Simplified Chinese (zh-Hans), German (de), and Korean (ko), NEVER hardcode `'en' | 'zh-Hans'` +- **MUST support all configured languages (18 total):** + - English (en) + - German (de) + - Spanish (es) + - French (fr) + - Indonesian (id) + - Japanese (ja) + - Korean (ko) + - Portuguese (pt) + - Russian (ru) + - Turkish (tr) + - Simplified Chinese (zh-Hans) + - Traditional Chinese (zh-Hant) + +- **NEVER hardcode** a subset of locales like `'en' | 'zh-Hans'` - **MUST use the localized Link component:** Always import and use `import { Link } from '@/i18n/navigation'` instead of Next.js default Link ### Localization Best Practices @@ -14,6 +28,35 @@ When creating or modifying any page, module, or data: - **DRY principle for translations:** Before creating new translation keys, search existing translation modules thoroughly to reuse existing terms and phrases - **Consistency:** Use the same translation keys across similar contexts +### Translation File Organization + +Follow the detailed architecture rules in [docs/I18N-ARCHITECTURE-RULES.md](docs/I18N-ARCHITECTURE-RULES.md) for organizing translation resources. + +**Core Principles:** +1. **Page translations**: Each page or page group should have its own JSON file (e.g., `ides.json`, `ide-detail.json`) +2. **Component translations**: Organize by component directory: + - `components/common.json` - Root-level components (Header, Footer, etc.) + - `components/navigation.json` - All navigation/* components + - `components/controls.json` - All controls/* components + - `components/sidebar.json` - All sidebar/* components + - `components/product.json` - All product/* components +3. **Minimize `@:` references**: Use `tPage + tShared` or `tComponent + tShared` patterns in code instead of cross-namespace references in JSON +4. **Metadata placement**: Co-locate page metadata (title, description, etc.) with page translations under a `meta` object +5. **Multi-language workflow**: New translation keys should initially use English placeholders across all locales, with proper translation in a separate batch step + +**Usage Pattern:** +```tsx +// Pages +const tPage = useTranslations('pages.modelDetail') +const tShared = useTranslations('shared') + +// Components (root-level) +const tComponent = useTranslations('components.common.header') + +// Components (subdirectories) +const tComponent = useTranslations('components.navigation.breadcrumb') +``` + ## Design System **Global Design Principles:** diff --git a/README.md b/README.md index 3a0cf77..b2d105e 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ > Your AI Coding Ecosystem Hub - Discover, Compare, Build Faster -[Live Site: https://aicodingstack.io](https://aicodingstack.io) | [Contributing](CONTRIBUTING.md) | [Discussions](https://github.com/aicodingstack/aicodingstack.io/discussions) +Live Site: [https://aicodingstack.io](https://aicodingstack.io) | [Contributing](CONTRIBUTING.md) | [Discussions](https://github.com/aicodingstack/aicodingstack.io/discussions) AI Coding Stack is a comprehensive directory and community-maintained metadata repository for AI-powered coding tools, models, and platforms. @@ -28,7 +28,7 @@ AI Coding Stack is a comprehensive directory and community-maintained metadata r - **Curated Collections**: Hand-picked tool collections for specific use cases - **Community-Driven**: Open-source metadata maintained by the developer community - **Always Updated**: Latest version tracking and up-to-date information -- **Multilingual**: Support for English, German, Simplified Chinese, and Korean (more coming soon) +- **Multilingual**: Support for 12 languages including English, German, Simplified & Traditional Chinese, Korean, Spanish, French, Indonesian, Japanese, Portuguese, Russian, and Turkish ## Data Structure @@ -126,7 +126,7 @@ All manifest files are automatically validated against JSON schemas. Make sure y - **Styling**: Tailwind CSS 4 - **Internationalization**: next-intl - **Content**: MDX for documentation -- **Deployment**: Cloudflare Workers +- **Deployment**: Cloudflare Workers (via OpenNext for Cloudflare) ## Contributing diff --git a/content/articles/de/getting-started-with-ai-coding.mdx b/content/articles/de/getting-started-with-ai-coding.mdx index 16bacf4..0a611fa 100644 --- a/content/articles/de/getting-started-with-ai-coding.mdx +++ b/content/articles/de/getting-started-with-ai-coding.mdx @@ -1,69 +1,51 @@ --- -title: 'Erste Schritte mit KI-Coding' -description: 'Ein umfassender Leitfaden für den Einstieg in die KI-gestützte Softwareentwicklung. Lernen Sie die wichtigsten Tools, Best Practices und wie Sie KI-Coding-Assistenten effektiv nutzen.' -date: '2025-01-15' -author: 'AI Coding Stack Team' +title: "Erste Schritte mit AI-Coding: Ein umfassender Leitfaden" +description: "Erfahren Sie, wie Sie Ihre erste KI-gestützte Entwicklungsumgebung mit IDEs, CLIs und den wichtigen Tools einrichten, die Sie zur Steigerung Ihrer Codierungsproduktivität benötigen." +date: "2025-01-15" --- -# Erste Schritte mit KI-Coding +Der Aufstieg von KI-gestützten Coding-Tools hat grundlegend verändert, wie Entwickler Code schreiben, debuggen und warten. Ob Sie ein erfahrener Ingenieur sind oder gerade erst Ihre Codierungsreise beginnen, die Integration von KI in Ihren Entwicklungsworkflow kann Ihre Produktivität und Codequalität dramatisch steigern. -KI-gestütztes Coding hat die Softwareentwicklung revolutioniert. Dieser Leitfaden hilft Ihnen, mit den wichtigsten Tools und Best Practices zu beginnen. +## Warum AI-Coding wichtig ist -## Was ist KI-Coding? +Traditionelles Coding beinhaltet das manuelle Schreiben jeder Zeile, das Nachschlagen von Dokumentation und das Debuggen durch Ausprobieren. AI-Coding-Assistenten verändern dieses Paradigma durch: -KI-Coding bezieht sich auf die Verwendung künstlicher Intelligenz zur Unterstützung, Beschleunigung und Verbesserung des Softwareentwicklungsprozesses. Von intelligenter Code-Vervollständigung bis hin zur vollständigen Code-Generierung transformieren KI-Tools die Art und Weise, wie wir programmieren. +- Bereitstellung von intelligenter automatischer Vervollständigung, die Kontext versteht +- Generierung von Boilerplate-Code aus natürlichsprachlichen Beschreibungen +- Erkennen von Fehlern, bevor sie in die Produktion gelangen +- Erklärung von komplexem Code in einfacher Sprache +- Vorschlag von Optimierungen und Best Practices -## Wesentliche KI-Coding-Tools +## Auswahl Ihrer IDE -### 1. KI-gestützte IDEs +Ihre Wahl der IDE ist entscheidend für das AI-Coding. Die zwei beliebtesten Optionen sind: -Integrierte Entwicklungsumgebungen mit KI-Integration bieten: -- Intelligente Code-Vervollständigung -- Kontextbewusste Vorschläge -- Automatisches Refactoring -- Fehlerkennung und -behebung +### Cursor -Beliebte Optionen: VS Code mit KI-Erweiterungen, Cursor, TRAE +Von Grund auf fürKI-Paarprogrammierung entwickelt. Cursor bietet nativen KI-Chat, Inline-Bearbeitung und Verständnis der gesamten Codebase. Am besten für Entwickler, die KI tief in jeden Aspekt ihres Workflows integrieren möchten. -### 2. Kommandozeilen-Assistenten +### VS Code + Erweiterungen -KI-CLIs bringen Intelligenz direkt in Ihr Terminal: -- Natürlichsprachliche Befehlsgenerierung -- Codebase-Analyse -- Automatisierte Aufgaben -- Interaktive Problemlösung +Kombinieren Sie die vertraute VS Code-Oberfläche mitKI-Erweiterungen wie GitHub Copilot, Codeium oder Tabnine. Am besten für Entwickler, die ihre bestehende Einrichtung behalten undKI-Fähigkeiten hinzufügen möchten. -Beliebte Optionen: Claude Code, Codex +## Einrichtung Ihrer ersten AI-Coding-Umgebung -### 3. KI-Modelle +Hier ist eine Schritt-für-Schritt-Anleitung: -Große Sprachmodelle optimiert für Coding: -- DeepSeek V3.1 -- Kimi K2 -- GLM 4.5 -- Claude Sonnet -- GPT-4 +### 1. Wählen Sie Ihre IDE -## Best Practices +Laden Sie Cursor herunter und installieren Sie es oder VS Code mit Ihrer bevorzugtenKI-Erweiterung. -1. **Verstehen Sie die Vorschläge**: Akzeptieren Sie nicht blind KI-generierten Code -2. **Iterieren Sie**: Nutzen Sie KI als kollaborativen Partner -3. **Lernen Sie weiter**: KI-Tools sollten Ihr Wissen ergänzen, nicht ersetzen -4. **Überprüfen Sie die Sicherheit**: Prüfen Sie generierten Code auf Sicherheitslücken -5. **Optimieren Sie Ihren Workflow**: Finden Sie die richtige Balance zwischen KI-Unterstützung und manueller Kontrolle +### 2. Konfigurieren Sie API-Schlüssel -## Erste Schritte +Die meistenAI-Coding-Tools erfordernAPI-Schlüssel von Anbietern wie OpenAI, Anthropic oder DeepSeek. Melden Sie sich für ein Konto an und generieren Sie Ihre Schlüssel. -1. Wählen Sie eine KI-gestützte IDE -2. Installieren Sie relevante KI-Erweiterungen -3. Erkunden Sie verfügbare Modelle und Anbieter -4. Beginnen Sie mit einfachen Aufgaben -5. Erweitern Sie Ihre Nutzung schrittweise +### 3. Üben Sie mit einfachen Aufgaben -## Ressourcen +Beginnen Sie, indem Sie IhrenKI-Agenten bitten, einfache Funktionen zu generieren, Code-Snippets zu erklären oder Verbesserungen für vorhandenen Code vorzuschlagen. -- [AI Coding Stack](/de/ai-coding-stack) - Entdecken Sie Tools -- [Dokumentation](/de/docs) - Detaillierte Anleitungen -- [Vergleiche](/de/comparison) - Tool-Vergleiche +## Nächste Schritte -Die Zukunft des Codings ist KI-gestützt. Beginnen Sie noch heute Ihre Reise! +Sobald Sie sich mit grundlegendemAI-Coding wohlfühlen, erkunden Sie fortgeschrittene Themen wie Prompt Engineering für bessere Code-Generierung und die Integration vonKI in Ihre CI/CD-Pipeline. + +DasAI-Coding-Ökosystem entwickelt sich rasant. Bleiben Sie mit den neuesten Tools und Best Practices über die [AI Coding Stack](/ai-coding-stack) Dokumentation auf dem Laufenden. diff --git a/content/articles/de/mcp-servers-explained.mdx b/content/articles/de/mcp-servers-explained.mdx index 79f38ea..acafbcf 100644 --- a/content/articles/de/mcp-servers-explained.mdx +++ b/content/articles/de/mcp-servers-explained.mdx @@ -1,16 +1,16 @@ --- -title: 'MCP-Server verstehen: Die Zukunft des KI-Kontexts' -description: 'Tiefgreifender Einblick in Model Context Protocol-Server, wie sie funktionieren und warum sie entscheidend für den Aufbau intelligenter KI-Coding-Assistenten sind, die Ihr Projekt wirklich verstehen.' -date: '2025-01-10' +title: "MCP-Server verstehen: Die Zukunft des AI-Kontexts" +description: "Tiefgreifender Einblick in Model Context Protocol-Server, wie sie funktionieren und warum sie entscheidend für den Aufbau intelligenter AI-Coding-Assistenten sind, die Ihr Projekt wirklich verstehen." +date: "2025-01-10" --- -Model Context Protocol (MCP)-Server stellen einen Paradigmenwechsel dar, wie KI-Agenten mit externen Tools, Datenquellen und APIs interagieren. Sie sind das Bindeglied, das isolierte KI-Modelle in kontextbewusste Coding-Partner transformiert, die Ihr Projekt wirklich verstehen. +Model Context Protocol (MCP)-Server stellen einen Paradigmenwechsel dar, wie AI-Agenten mit externen Tools, Datenquellen und APIs interagieren. Sie sind das Bindeglied, das isolierte AI-Modelle in kontextbewusste Coding-Partner transformiert, die Ihr Projekt wirklich verstehen. ## Was ist MCP? -Das Model Context Protocol ist ein offener Standard, der von Anthropic entwickelt wurde und es KI-Agenten ermöglicht, sicher mit externen Datenquellen und Tools zu verbinden. Stellen Sie sich MCP-Server als spezialisierte Adapter vor, die Ihrem KI-Agenten Superkräfte verleihen—ob das Lesen aus Datenbanken, Websuche, Interaktion mit APIs oder Zugriff auf Ihr Dateisystem ist. +Das Model Context Protocol ist ein offener Standard, der von Anthropic entwickelt wurde und es AI-Agenten ermöglicht, sicher mit externen Datenquellen und Tools zu verbinden. Stellen Sie sich MCP-Server als spezialisierte Adapter vor, die Ihrem AI-Agenten Superkräfte verleihen—ob das Lesen aus Datenbanken, Websuche, Interaktion mit APIs oder Zugriff auf Ihr Dateisystem ist. -Im Gegensatz zu traditionellen API-Integrationen, die für jedes Tool benutzerdefinierten Code erfordern, bietet MCP eine standardisierte Schnittstelle. Das bedeutet, dass jeder MCP-kompatible KI-Agent jeden MCP-Server ohne benutzerdefinierte Integrationsarbeit verwenden kann. +Im Gegensatz zu traditionellen API-Integrationen, die für jedes Tool benutzerdefinierten Code erfordern, bietet MCP eine standardisierte Schnittstelle. Das bedeutet, dass jeder MCP-kompatible AI-Agent jeden MCP-Server ohne benutzerdefinierte Integrationsarbeit verwenden kann. ## Wie MCP-Server funktionieren @@ -18,15 +18,15 @@ Ein MCP-Server ist ein leichtgewichtiger Prozess, der drei Kernprimitive bereits ### Ressourcen -Kontext und Daten, die die KI lesen kann. Ein Dateisystem-MCP-Server stellt beispielsweise Ihre Projektdateien als Ressourcen bereit. +Kontext und Daten, die die AI lesen kann. Ein Dateisystem-MCP-Server stellt beispielsweise Ihre Projektdateien als Ressourcen bereit. ### Tools -Aktionen, die die KI ausführen kann. Ein Web-Such-MCP könnte ein Such-Tool bereitstellen, während ein Datenbank-MCP Abfrageausführungs-Tools bereitstellen könnte. +Aktionen, die die AI ausführen kann. Ein Web-Such-MCP könnte ein Such-Tool bereitstellen, während ein Datenbank-MCP Abfrageausführungs-Tools bereitstellen könnte. ### Prompts -Vorlagenbasierte Interaktionen, die die KI leiten. Diese können Best Practices oder gängige Workflows enthalten, die spezifisch für das Tool sind. +Vorlagenbasierte Interaktionen, die die AI leiten. Diese können Best Practices oder gängige Workflows enthalten, die spezifisch für das Tool sind. ## Beliebte MCP-Server @@ -39,11 +39,11 @@ Das MCP-Ökosystem wächst rapide. Hier sind einige wesentliche Server: - **GitHub** - Repository-Verwaltung und Code-Suche - **Brave Search** - Echtzeit-Websuchfunktionen -## Warum MCP für KI-Coding wichtig ist +## Warum MCP für AI-Coding wichtig ist -Vor MCP waren KI-Coding-Assistenten im Wesentlichen blind für Ihre Entwicklungsumgebung. Sie konnten Code basierend auf Trainingsdaten generieren, konnten aber nicht auf Ihre tatsächliche Projektstruktur zugreifen, Ihre Konfigurationsdateien lesen oder mit Ihren Entwicklungstools interagieren. +Vor MCP waren AI-Coding-Assistenten im Wesentlichen blind für Ihre Entwicklungsumgebung. Sie konnten Code basierend auf Trainingsdaten generieren, konnten aber nicht auf Ihre tatsächliche Projektstruktur zugreifen, Ihre Konfigurationsdateien lesen oder mit Ihren Entwicklungstools interagieren. -MCP ändert dies grundlegend. Mit MCP-Servern kann Ihr KI-Agent: +MCP ändert dies grundlegend. Mit MCP-Servern kann Ihr AI-Agent: - Ihre gesamte Codebasis-Struktur durch Dateisystemzugriff verstehen - Aktuelle Dokumentation für Bibliotheken nachschlagen, die Sie verwenden @@ -53,7 +53,7 @@ MCP ändert dies grundlegend. Mit MCP-Servern kann Ihr KI-Agent: ## Erste Schritte mit MCP -Die meisten modernen KI-Coding-Tools unterstützen jetzt MCP. Die Einrichtung Ihres ersten MCP-Servers umfasst typischerweise: +Die meisten modernen AI-Coding-Tools unterstützen jetzt MCP. Die Einrichtung Ihres ersten MCP-Servers umfasst typischerweise: ### 1. Wählen Sie einen MCP-Server @@ -89,13 +89,13 @@ Hier ist ein Beispiel für die Konfiguration von Claude Code: ### 4. Testen Sie die Integration -Bitten Sie Ihren KI-Agenten, die neu verbundenen Tools zu verwenden. Wenn Sie beispielsweise einen Dateisystem-MCP installiert haben, versuchen Sie, ihn zu bitten, eine bestimmte Datei aus Ihrem Projekt zu lesen. +Bitten Sie Ihren AI-Agenten, die neu verbundenen Tools zu verwenden. Wenn Sie beispielsweise einen Dateisystem-MCP installiert haben, versuchen Sie, ihn zu bitten, eine bestimmte Datei aus Ihrem Projekt zu lesen. ## Die Zukunft von MCP -Das MCP-Ökosystem befindet sich noch in einem frühen Stadium, aber das Potenzial ist enorm. Während mehr Entwickler MCP-Server für spezialisierte Tools und Dienste erstellen, werden KI-Agenten zunehmend leistungsfähiger und kontextbewusster. +Das MCP-Ökosystem befindet sich noch in einem frühen Stadium, aber das Potenzial ist enorm. Während mehr Entwickler MCP-Server für spezialisierte Tools und Dienste erstellen, werden AI-Agenten zunehmend leistungsfähiger und kontextbewusster. -Wir bewegen uns auf eine Zukunft zu, in der Ihr KI-Coding-Assistent nahtlosen Zugriff auf jedes Tool in Ihrem Entwicklungs-Workflow hat—von Ihrer IDE bis zu Ihrer Cloud-Infrastruktur. MCP ist das Protokoll, das diese Vision möglich macht. +Wir bewegen uns auf eine Zukunft zu, in der Ihr AI-Coding-Assistent nahtlosen Zugriff auf jedes Tool in Ihrem Entwicklungs-Workflow hat—von Ihrer IDE bis zu Ihrer Cloud-Infrastruktur. MCP ist das Protokoll, das diese Vision möglich macht. Erkunden Sie den vollständigen Katalog verfügbarer MCP-Server in unserem [MCP-Server-Verzeichnis](/de/ai-coding-stack/mcp-servers), um die richtigen Integrationen für Ihren Workflow zu finden. diff --git a/content/articles/en/getting-started-with-ai-coding.mdx b/content/articles/en/getting-started-with-ai-coding.mdx index 135c215..7d5163a 100644 --- a/content/articles/en/getting-started-with-ai-coding.mdx +++ b/content/articles/en/getting-started-with-ai-coding.mdx @@ -1,7 +1,7 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "Getting Started with AI Coding: A Comprehensive Guide" +description: "Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity." +date: "2025-01-15" --- The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. diff --git a/content/articles/en/mcp-servers-explained.mdx b/content/articles/en/mcp-servers-explained.mdx index 0488888..25370b4 100644 --- a/content/articles/en/mcp-servers-explained.mdx +++ b/content/articles/en/mcp-servers-explained.mdx @@ -1,7 +1,7 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "Understanding MCP Servers: The Future of AI Context" +description: "Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project." +date: "2025-01-10" --- Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. @@ -41,7 +41,7 @@ The MCP ecosystem is rapidly growing. Here are some essential servers: ## Why MCP Matters for AI Coding -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +Before MCP, AI coding assistants were essentially blind to your development environment. They could generate codebased on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. MCP changes this fundamentally. With MCP servers, your AI agent can: diff --git a/content/articles/es/getting-started-with-ai-coding.mdx b/content/articles/es/getting-started-with-ai-coding.mdx index 135c215..b06110c 100644 --- a/content/articles/es/getting-started-with-ai-coding.mdx +++ b/content/articles/es/getting-started-with-ai-coding.mdx @@ -1,51 +1,51 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "Comenzando con AI Coding: Una Guía Completa" +description: "Aprende cómo configurar tu primer entorno de desarrollo impulsado por IA con IDEs, CLIs y las herramientas esenciales que necesitas para impulsar tu productividad de programación." +date: "2025-01-15" --- -The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. +El auge de las herramientas de programación impulsadas por IA ha transformado fundamentalmente cómo los desarrolladores escriben, depuran y mantienen código. Ya seas un ingeniero experimentado o estés comenzando tu viaje de programación, integrar la IA en tu flujo de trabajo de desarrollo puede aumentar dramatically tu productividad y calidad de código. -## Why AI Coding Matters +## Por qué es importante AI Coding -Traditional coding involves writing every line manually, looking up documentation, and debugging through trial and error. AI coding assistants change this paradigm by: +La programación tradicional implica escribir cada línea manualmente, buscar documentación y depurar mediante ensayo y error. Los asistentes de programación con IA cambian este paradigma al: -- Providing intelligent autocomplete that understands context -- Generating boilerplate code from natural language descriptions -- Catching bugs before they make it to production -- Explaining complex code in plain English -- Suggesting optimizations and best practices +- Proporcionar autocompletado inteligente que entiende el contexto +- Generar código repetitivo a partir de descripciones en lenguaje natural +- Detectar errores antes de que lleguen a producción +- Explicar código complejo en español sencillo +- Sugerir optimizaciones y mejores prácticas -## Choosing Your IDE +## Elegir tu IDE -Your choice of IDE is crucial for AI coding. The two most popular options are: +La elección de tu IDE es crucial para AI Coding. Las dos opciones más populares son: ### Cursor -Built from the ground up for AI pair programming. Cursor offers native AI chat, inline editing, and codebase-wide understanding. Best for developers who want AI deeply integrated into every aspect of their workflow. +Construido desde cero para programación en pareja con IA. Cursor ofrece chat de IA nativo, edición en línea y comprensión de toda la base de código. Ideal para desarrolladores que desean la IA profundamente integrada en cada aspecto de su flujo de trabajo. -### VS Code + Extensions +### VS Code + Extensiones -Combine the familiar VS Code interface with AI extensions like GitHub Copilot, Codeium, or Tabnine. Best for developers who want to keep their existing setup while adding AI capabilities. +Combina la interfaz familiar de VS Code con extensiones de IA como GitHub Copilot, Codeium o Tabnine. Ideal para desarrolladores que desean mantener su configuración existente mientras añaden capacidades de IA. -## Setting Up Your First AI Coding Environment +## Configurando tu Primer Entorno de AI Coding -Here's a step-by-step guide to get started: +Aquí tienes una guía paso a paso para comenzar: -### 1. Choose Your IDE +### 1. Elige tu IDE -Download and install either Cursor or VS Code with your preferred AI extension. +Descarga e instala Cursor o VS Code con tu extensión de IA preferida. -### 2. Configure API Keys +### 2. Configura Claves API -Most AI coding tools require API keys from providers like OpenAI, Anthropic, or DeepSeek. Sign up for an account and generate your keys. +La mayoría de las herramientas de programación con IA requieren claves API de proveedores como OpenAI, Anthropic o DeepSeek. Regístrate en una cuenta y genera tus claves. -### 3. Practice with Simple Tasks +### 3. Practica con Tareas Simples -Start by asking your AI agent to generate simple functions, explain code snippets, or suggest improvements to existing code. +Comienza pidiendo a tu agente de IA que genere funciones simples, explique fragmentos de código o sugiera mejoras a código existente. -## Next Steps +## Próximos Pasos -Once you're comfortable with basic AI coding, explore advanced topics like prompt engineering for better code generation and integrating AI into your CI/CD pipeline. +Una vez que te sientas cómodo con AI Coding básico, explora temas avanzados como ingeniería de prompts para mejor generación de código e integración de IA en tu pipeline CI/CD. -The AI coding ecosystem is evolving rapidly. Stay updated with the latest tools and best practices through the [AI Coding Stack](/ai-coding-stack) documentation. +El ecosistema de AI Coding está evolucionando rápidamente. Mantente actualizado con las últimas herramientas y mejores prácticas a través de la documentación de [AI Coding Stack](/ai-coding-stack). diff --git a/content/articles/es/mcp-servers-explained.mdx b/content/articles/es/mcp-servers-explained.mdx index 0488888..7a369c0 100644 --- a/content/articles/es/mcp-servers-explained.mdx +++ b/content/articles/es/mcp-servers-explained.mdx @@ -1,100 +1,100 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "Entendiendo los Servidores MCP: El Futuro del Contexto de IA" +description: "Un análisis profundo de los servidores del Protocolo de Contexto de Modelo, cómo funcionan y por qué son cruciales para construir asistentes de programación con IA que realmente entiendan tu proyecto." +date: "2025-01-10" --- -Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. +Los servidores del Protocolo de Contexto de Modelo (MCP) representan un cambio de paradigma en cómo los agentes de IA interactúan con herramientas externas, fuentes de datos y APIs. Son el tejido conectivo que transforma modelos de IA aislados en compañeros de programación conscientes del contexto que realmente entienden tu proyecto. -## What is MCP? +## ¿Qué es MCP? -The Model Context Protocol is an open standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. Think of MCP servers as specialized adapters that give your AI agent superpowers—whether that's reading from databases, searching the web, interacting with APIs, or accessing your filesystem. +El Protocolo de Contexto de Modelo es un estándar abierto desarrollado por Anthropic que permite a los agentes de IA conectarse de forma segura a fuentes de datos externas y herramientas. Piensa en los servidores MCP como adaptadores especializados que otorgan superpoderes a tu agente de IA, ya sea leyendo de bases de datos, buscando en la web, interactuando con APIs o accediendo a tu sistema de archivos. -Unlike traditional API integrations that require custom code for each tool, MCP provides a standardized interface. This means any MCP-compatible AI agent can use any MCP server without custom integration work. +A diferencia de las integraciones de API tradicionales que requieren código personalizado para cada herramienta, MCP proporciona una interfaz estandarizada. Esto significa que cualquier agente de IA compatible con MCP puede usar cualquier servidor MCP sin trabajo de integración personalizado. -## How MCP Servers Work +## Cómo Funcionan los Servidores MCP -An MCP server is a lightweight process that exposes three core primitives: +Un servidor MCP es un proceso ligero que expone tres primitivos principales: -### Resources +### Recursos -Context and data that the AI can read. For example, a filesystem MCP server exposes your project files as resources. +Contexto y datos que la IA puede leer. Por ejemplo, un servidor MCP de sistema de archivos expone tus archivos de proyecto como recursos. -### Tools +### Herramientas -Actions the AI can perform. A web search MCP might expose a search tool, while a database MCP could provide query execution tools. +Acciones que la IA puede realizar. Un servidor MCP de búsqueda web podría exponer una herramienta de búsqueda, mientras que un servidor MCP de base de datos podría proporcionar herramientas de ejecución de consultas. ### Prompts -Templated interactions that guide the AI. These can include best practices or common workflows specific to the tool. +Interacciones con plantillas que guían a la IA. Estas pueden incluir mejores prácticas o flujos de trabajo comunes específicos para la herramienta. -## Popular MCP Servers +## Servidores MCP Populares -The MCP ecosystem is rapidly growing. Here are some essential servers: +El ecosistema MCP está creciendo rápidamente. Aquí hay algunos servidores esenciales: -- **Filesystem** - Access local files and directories -- **Playwright** - Browser automation and web scraping -- **Context7** - Up-to-date library documentation -- **PostgreSQL** - Database queries and schema inspection -- **GitHub** - Repository management and code search -- **Brave Search** - Real-time web search capabilities +- **Filesystem** - Acceder a archivos y directorios locales +- **Playwright** - Automatización de navegador y web scraping +- **Context7** - Documentación actualizada de bibliotecas +- **PostgreSQL** - Consultas de base de datos e inspección de esquemas +- **GitHub** - Gestión de repositorios y búsqueda de código +- **Brave Search** - Capacidades de búsqueda web en tiempo real -## Why MCP Matters for AI Coding +## Por qué MCP es Importante para AI Coding -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +Antes de MCP, los asistentes de programación con IA eran esencialmente ciegos a tu entorno de desarrollo. Podían generar código basándose en datos de entrenamiento, pero no podían acceder a la estructura real de tu proyecto, leer tus archivos de configuración o interactuar con tus herramientas de desarrollo. -MCP changes this fundamentally. With MCP servers, your AI agent can: +MCP cambia esto fundamentalmente. Con servidores MCP, tu agente de IA puede: -- Understand your entire codebase structure through filesystem access -- Look up current documentation for libraries you're using -- Execute database queries to understand your data model -- Search the web for the latest solutions to your specific problem -- Interact with your Git repository to understand commit history +- Entender toda la estructura de tu base de código a través del acceso al sistema de archivos +- Buscar documentación actualizada para las bibliotecas que estás usando +- Ejecutar consultas de base de datos para entender tu modelo de datos +- Buscar en la web las últimas soluciones para tu problema específico +- Interactuar con tu repositorio Git para entender el historial de commits -## Getting Started with MCP +## Comenzando con MCP -Most modern AI coding tools now support MCP. Setting up your first MCP server typically involves: +La mayoría de las herramientas modernas de programación con IA ahora admiten MCP. Configurar tu primer servidor MCP típicamente implica: -### 1. Choose an MCP Server +### 1. Elige un Servidor MCP -Start with something simple like the filesystem or web search MCP server. +Comienza con algo simple como el servidor MCP de sistema de archivos o búsqueda web. -### 2. Install the Server +### 2. Instala el Servidor -Most MCP servers are distributed as npm packages or Python modules. Follow the installation instructions for your chosen server. +La mayoría de los servidores MCP se distribuyen como paquetes npm o módulos de Python. Sigue las instrucciones de instalación para tu servidor elegido. -### 3. Configure Your IDE +### 3. Configura tu IDE -Add the MCP server configuration to your IDE's settings. The exact format varies by tool, but typically involves specifying the server's command and any required arguments. +Agrega la configuración del servidor MCP a la configuración de tu IDE. El formato exacto varía según la herramienta, pero típicamente implica especificar el comando del servidor y los argumentos requeridos. -Here's an example configuration for Claude Code: +Aquí tienes un ejemplo de configuración para Claude Code: ```json { "mcpServers": { "filesystem": { "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"] + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ruta/a/tu/proyecto"] }, "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { - "BRAVE_API_KEY": "your-api-key-here" + "BRAVE_API_KEY": "tu-api-key-aqui" } } } } ``` -### 4. Test the Integration +### 4. Prueba la Integración -Ask your AI agent to use the newly connected tools. For example, if you installed a filesystem MCP, try asking it to read a specific file from your project. +Pide a tu agente de IA que use las herramientas recién conectadas. Por ejemplo, si instalaste un servidor MCP de sistema de archivos, intenta pedirle que lea un archivo específico de tu proyecto. -## The Future of MCP +## El Futuro de MCP -The MCP ecosystem is still in its early stages, but the potential is enormous. As more developers build MCP servers for specialized tools and services, AI agents will become increasingly powerful and context-aware. +El ecosistema MCP todavía está en sus primeras etapas, pero el potencial es enorme. A medida que más desarrolladores construyan servidores MCP para herramientas y servicios especializados, los agentes de IA se volverán cada vez más poderosos y conscientes del contexto. -We're moving toward a future where your AI coding assistant has seamless access to every tool in your development workflow—from your IDE to your cloud infrastructure. MCP is the protocol that makes this vision possible. +Nos estamos moviendo hacia un futuro donde tu asistente de programación con IA tiene acceso fluido a cada herramienta en tu flujo de trabajo de desarrollo, desde tu IDE hasta tu infraestructura en la nube. MCP es el protocolo que hace posible esta visión. -Explore the full catalog of available MCP servers in our [MCP Servers directory](/ai-coding-stack/mcp-servers) to find the right integrations for your workflow. +Explora el catálogo completo de servidores MCP disponibles en nuestro [directorio de servidores MCP](/ai-coding-stack/mcp-servers) para encontrar las integraciones adecuadas para tu flujo de trabajo. diff --git a/content/articles/fr/getting-started-with-ai-coding.mdx b/content/articles/fr/getting-started-with-ai-coding.mdx index 135c215..925a509 100644 --- a/content/articles/fr/getting-started-with-ai-coding.mdx +++ b/content/articles/fr/getting-started-with-ai-coding.mdx @@ -1,51 +1,51 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "Commencer avec AI Coding : Un Guide Complet" +description: "Apprenez comment configurer votre premier environnement de développement propulsé par l'IA avec des IDE, des CLI et les outils essentiels dont vous avez besoin pour stimuler votre productivité de programmation." +date: "2025-01-15" --- -The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. +L'essor des outils de programmation propulsés par l'IA a fondamentalement transformé la façon dont les développeurs écrivent, débogent et maintiennent le code. Que vous soyez un ingénieur expérimenté ou que vous commenciez tout juste votre parcours de programmation, l'intégration de l'IA dans votre flux de travail de développement peut considérablement augmenter votre productivité et la qualité de votre code. -## Why AI Coding Matters +## Pourquoi AI Coding est Important -Traditional coding involves writing every line manually, looking up documentation, and debugging through trial and error. AI coding assistants change this paradigm by: +La programmation traditionnelle implique d'écrire chaque ligne manuellement, de rechercher de la documentation et de déboguer par essais et erreurs. Les assistants de programmation IA changent ce paradigme en : -- Providing intelligent autocomplete that understands context -- Generating boilerplate code from natural language descriptions -- Catching bugs before they make it to production -- Explaining complex code in plain English -- Suggesting optimizations and best practices +- Fournissant une autocomplétion intelligente qui comprend le contexte +- Générant du code passe-partout à partir de descriptions en langage naturel +- Détectant les bugs avant qu'ils n'arrivent en production +- Expliquant un code complexe en français clair +- Suggérant des optimisations et des meilleures pratiques -## Choosing Your IDE +## Choisir votre IDE -Your choice of IDE is crucial for AI coding. The two most popular options are: +Le choix de votre IDE est crucial pour AI Coding. Les deux options les plus populaires sont : ### Cursor -Built from the ground up for AI pair programming. Cursor offers native AI chat, inline editing, and codebase-wide understanding. Best for developers who want AI deeply integrated into every aspect of their workflow. +Conçu dès le départ pour la programmation en paire avec l'IA. Cursor offre un chat IA natif, l'édition en ligne et la compréhension de toute la base de code. Idéal pour les développeurs qui veulent l'IA profondément intégrée dans chaque aspect de leur flux de travail. ### VS Code + Extensions -Combine the familiar VS Code interface with AI extensions like GitHub Copilot, Codeium, or Tabnine. Best for developers who want to keep their existing setup while adding AI capabilities. +Combinez l'interface familière de VS Code avec des extensions IA comme GitHub Copilot, Codeium ou Tabnine. Idéal pour les développeurs qui veulent conserver leur configuration existante tout en ajoutant des capacités IA. -## Setting Up Your First AI Coding Environment +## Configuration de Votre Premier Environnement AI Coding -Here's a step-by-step guide to get started: +Voici un guide étape par étape pour commencer : -### 1. Choose Your IDE +### 1. Choisissez votre IDE -Download and install either Cursor or VS Code with your preferred AI extension. +Téléchargez et installez Cursor ou VS Code avec votre extension IA préférée. -### 2. Configure API Keys +### 2. Configurez les Clés API -Most AI coding tools require API keys from providers like OpenAI, Anthropic, or DeepSeek. Sign up for an account and generate your keys. +La plupart des outils de programmation IA nécessitent des clés API de fournisseurs comme OpenAI, Anthropic ou DeepSeek. Inscrivez-vous à un compte et générez vos clés. -### 3. Practice with Simple Tasks +### 3. Pratiquez avec des Tâches Simples -Start by asking your AI agent to generate simple functions, explain code snippets, or suggest improvements to existing code. +Commencez en demandant à votre agent IA de générer des fonctions simples, d'expliquer des extraits de code ou de suggérer des améliorations au code existant. -## Next Steps +## Prochaines Étapes -Once you're comfortable with basic AI coding, explore advanced topics like prompt engineering for better code generation and integrating AI into your CI/CD pipeline. +Une fois que vous êtes à l'aise avec AI Coding de base, explorez des sujets avancés comme l'ingénierie de prompts pour une meilleure génération de code et l'intégration de l'IA dans votre pipeline CI/CD. -The AI coding ecosystem is evolving rapidly. Stay updated with the latest tools and best practices through the [AI Coding Stack](/ai-coding-stack) documentation. +L'écosystème AI Coding évolue rapidement. Restez informé des derniers outils et meilleures pratiques à travers la documentation [AI Coding Stack](/ai-coding-stack). diff --git a/content/articles/fr/mcp-servers-explained.mdx b/content/articles/fr/mcp-servers-explained.mdx index 0488888..4897575 100644 --- a/content/articles/fr/mcp-servers-explained.mdx +++ b/content/articles/fr/mcp-servers-explained.mdx @@ -1,100 +1,100 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "Comprendre les Serveurs MCP : L'Avenir du Contexte IA" +description: "Un approfondissement des serveurs du Protocole de Contexte de Modèle, comment ils fonctionnent et pourquoi ils sont cruciaux pour construire des assistants de programmation IA intelligents qui comprennent vraiment votre projet." +date: "2025-01-10" --- -Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. +Les serveurs du Protocole de Contexte de Modèle (MCP) représentent un changement de paradigme dans la façon dont les agents IA interagissent avec des outils externes, des sources de données et des API. Ils constituent le tissu connectif qui transforme des modèles IA isolés en compagnons de programmation conscients du contexte qui comprennent vraiment votre projet. -## What is MCP? +## Qu'est-ce que MCP ? -The Model Context Protocol is an open standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. Think of MCP servers as specialized adapters that give your AI agent superpowers—whether that's reading from databases, searching the web, interacting with APIs, or accessing your filesystem. +Le Protocole de Contexte de Modèle est un standard ouvert développé par Anthropic qui permet aux agents IA de se connecter en toute sécurité à des sources de données externes et à des outils. Voyez les serveurs MCP comme des adaptateurs spécialisés qui donnent des super-pouvoirs à votre agent IA, qu'il s'agisse de lire dans des bases de données, de rechercher sur le web, d'interagir avec des API ou d'accéder à votre système de fichiers. -Unlike traditional API integrations that require custom code for each tool, MCP provides a standardized interface. This means any MCP-compatible AI agent can use any MCP server without custom integration work. +Contrairement aux intégrations d'API traditionnelles qui nécessitent du code personnalisé pour chaque outil, MCP fournit une interface standardisée. Cela signifie que tout agent IA compatible MCP peut utiliser n'importe quel serveur MCP sans travail d'intégration personnalisé. -## How MCP Servers Work +## Comment les Serveurs MCP Fonctionnent -An MCP server is a lightweight process that exposes three core primitives: +Un serveur MCP est un processus léger qui expose trois primitives principales : -### Resources +### Ressources -Context and data that the AI can read. For example, a filesystem MCP server exposes your project files as resources. +Contexte et données que l'IA peut lire. Par exemple, un serveur MCP de système de fichiers expose vos fichiers de projet comme ressources. -### Tools +### Outils -Actions the AI can perform. A web search MCP might expose a search tool, while a database MCP could provide query execution tools. +Actions que l'IA peut effectuer. Un serveur MCP de recherche web pourrait exposer un outil de recherche, tandis qu'un serveur MCP de base de données pourrait fournir des outils d'exécution de requêtes. ### Prompts -Templated interactions that guide the AI. These can include best practices or common workflows specific to the tool. +Interactions avec modèles qui guident l'IA. Ceux-ci peuvent inclure des meilleures pratiques ou des flux de travail courants spécifiques à l'outil. -## Popular MCP Servers +## Serveurs MCP Populaires -The MCP ecosystem is rapidly growing. Here are some essential servers: +L'écosystème MCP croît rapidement. Voici quelques serveurs essentiels : -- **Filesystem** - Access local files and directories -- **Playwright** - Browser automation and web scraping -- **Context7** - Up-to-date library documentation -- **PostgreSQL** - Database queries and schema inspection -- **GitHub** - Repository management and code search -- **Brave Search** - Real-time web search capabilities +- **Filesystem** - Accéder aux fichiers et répertoires locaux +- **Playwright** - Automatisation du navigateur et web scraping +- **Context7** - Documentation de bibliothèque à jour +- **PostgreSQL** - Requêtes de base de données et inspection de schéma +- **GitHub** - Gestion de dépôt et recherche de code +- **Brave Search** - Capacités de recherche web en temps réel -## Why MCP Matters for AI Coding +## Pourquoi MCP est Important pour AI Coding -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +Avant MCP, les assistants de programmation IA étaient essentiellement aveugles à votre environnement de développement. Ils pouvaient générer du code basé sur des données d'entraînement, mais ne pouvaient pas accéder à la structure réelle de votre projet, lire vos fichiers de configuration ou interagir avec vos outils de développement. -MCP changes this fundamentally. With MCP servers, your AI agent can: +MCP change fondamentalement cela. Avec les serveurs MCP, votre agent IA peut : -- Understand your entire codebase structure through filesystem access -- Look up current documentation for libraries you're using -- Execute database queries to understand your data model -- Search the web for the latest solutions to your specific problem -- Interact with your Git repository to understand commit history +- Comprendre toute la structure de votre base de code via l'accès au système de fichiers +- Rechercher la documentation actuelle pour les bibliothèques que vous utilisez +- Exécuter des requêtes de base de données pour comprendre votre modèle de données +- Rechercher sur le web les dernières solutions pour votre problème spécifique +- Interagir avec votre dépôt Git pour comprendre l'historique des commits -## Getting Started with MCP +## Commencer avec MCP -Most modern AI coding tools now support MCP. Setting up your first MCP server typically involves: +La plupart des outils modernes de programmation IA prennent désormais en charge MCP. La configuration de votre premier serveur MCP implique généralement : -### 1. Choose an MCP Server +### 1. Choisissez un Serveur MCP -Start with something simple like the filesystem or web search MCP server. +Commencez avec quelque chose de simple comme le serveur MCP de système de fichiers ou de recherche web. -### 2. Install the Server +### 2. Installez le Serveur -Most MCP servers are distributed as npm packages or Python modules. Follow the installation instructions for your chosen server. +La plupart des serveurs MCP sont distribués sous forme de packages npm ou de modules Python. Suivez les instructions d'installation pour votre serveur choisi. -### 3. Configure Your IDE +### 3. Configurez votre IDE -Add the MCP server configuration to your IDE's settings. The exact format varies by tool, but typically involves specifying the server's command and any required arguments. +Ajoutez la configuration du serveur MCP aux paramètres de votre IDE. Le format exact varie selon l'outil, mais implique généralement de spécifier la commande du serveur et les arguments requis. -Here's an example configuration for Claude Code: +Voici un exemple de configuration pour Claude Code : ```json { "mcpServers": { "filesystem": { "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"] + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/chemin/vers/votre/projet"] }, "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { - "BRAVE_API_KEY": "your-api-key-here" + "BRAVE_API_KEY": "votre-clé-api-ici" } } } } ``` -### 4. Test the Integration +### 4. Testez l'Intégration -Ask your AI agent to use the newly connected tools. For example, if you installed a filesystem MCP, try asking it to read a specific file from your project. +Demandez à votre agent IA d'utiliser les outils nouvellement connectés. Par exemple, si vous avez installé un serveur MCP de système de fichiers, essayez de lui demander de lire un fichier spécifique de votre projet. -## The Future of MCP +## L'Avenir de MCP -The MCP ecosystem is still in its early stages, but the potential is enormous. As more developers build MCP servers for specialized tools and services, AI agents will become increasingly powerful and context-aware. +L'écosystème MCP est encore à ses débuts, mais le potentiel est énorme. À mesure que plus de développeurs construiront des serveurs MCP pour des outils et services spécialisés, les agents IA deviendront de plus en plus puissants et conscients du contexte. -We're moving toward a future where your AI coding assistant has seamless access to every tool in your development workflow—from your IDE to your cloud infrastructure. MCP is the protocol that makes this vision possible. +Nous nous déplaçons vers un avenir où votre assistant de programmation IA a un accès fluide à chaque outil de votre flux de travail de développement, depuis votre IDE jusqu'à votre infrastructure cloud. MCP est le protocole qui rend cette vision possible. -Explore the full catalog of available MCP servers in our [MCP Servers directory](/ai-coding-stack/mcp-servers) to find the right integrations for your workflow. +Explorez le catalogue complet des serveurs MCP disponibles dans notre [répertoire de serveurs MCP](/ai-coding-stack/mcp-servers) pour trouver les intégrations appropriées pour votre flux de travail. diff --git a/content/articles/id/getting-started-with-ai-coding.mdx b/content/articles/id/getting-started-with-ai-coding.mdx index 135c215..f7a7bf4 100644 --- a/content/articles/id/getting-started-with-ai-coding.mdx +++ b/content/articles/id/getting-started-with-ai-coding.mdx @@ -1,51 +1,51 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "Memulai AI Coding: Panduan Lengkap" +description: "Pelajari cara menyiapkan lingkungan pengembangan bertenaga AI pertama Anda dengan IDE, CLI, dan alat penting yang Anda butuhkan untuk meningkatkan produktivitas pemrograman Anda." +date: "2025-01-15" --- -The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. +Munculnya alat pemrograman bertenaga AI telah mengubah secara fundamental cara pengembang menulis, mengdebug, dan memelihara kode. Baik Anda seorang engineer berpengalaman atau baru memulai perjalanan pemrograman Anda, mengintegrasikan AI ke dalam workflow pengembangan Anda dapat meningkatkan secara dramatis produktivitas dan kualitas kode Anda. -## Why AI Coding Matters +## Mengapa AI Coding Penting -Traditional coding involves writing every line manually, looking up documentation, and debugging through trial and error. AI coding assistants change this paradigm by: +Pemrograman tradisional melibatkan penulisan setiap baris secara manual, mencari dokumentasi, dan debugging melalui trial and error. Asisten pemrograman AI mengubah paradigma ini dengan: -- Providing intelligent autocomplete that understands context -- Generating boilerplate code from natural language descriptions -- Catching bugs before they make it to production -- Explaining complex code in plain English -- Suggesting optimizations and best practices +- Menyediakan autocomplete cerdas yang memahami konteks +- Menghasilkan kode boilerplate dari deskripsi bahasa alami +- Menangkap bug sebelum masuk ke produksi +- Menjelaskan kode kompleks dalam bahasa yang sederhana +- Menyarankan optimasi dan best practices -## Choosing Your IDE +## Memilih IDE Anda -Your choice of IDE is crucial for AI coding. The two most popular options are: +Pilihan IDE Anda sangat penting untuk AI Coding. Dua opsi paling populer adalah: ### Cursor -Built from the ground up for AI pair programming. Cursor offers native AI chat, inline editing, and codebase-wide understanding. Best for developers who want AI deeply integrated into every aspect of their workflow. +Dibangun dari dasar untuk pemrograman berpasangan dengan AI. Cursor menyediakan chat AI asli, pengeditan inline, dan pemahaman seluruh codebase. Terbaik untuk pengembang yang menginginkan AI terintegrasi secara mendalam ke dalam setiap aspek workflow mereka. ### VS Code + Extensions -Combine the familiar VS Code interface with AI extensions like GitHub Copilot, Codeium, or Tabnine. Best for developers who want to keep their existing setup while adding AI capabilities. +Gabungkan antarmuka VS Code yang familiar dengan ekstensi AI seperti GitHub Copilot, Codeium, atau Tabnine. Terbaik untuk pengembang yang ingin mempertahankan pengaturan mereka yang ada sambil menambahkan kemampuan AI. -## Setting Up Your First AI Coding Environment +## Menyiapkan Lingkungan AI Coding Pertama Anda -Here's a step-by-step guide to get started: +Berikut adalah panduan langkah demi langkah untuk memulai: -### 1. Choose Your IDE +### 1. Pilih IDE Anda -Download and install either Cursor or VS Code with your preferred AI extension. +Unduh dan instal Cursor atau VS Code dengan ekstensi AI pilihan Anda. -### 2. Configure API Keys +### 2. Konfigurasi API Keys -Most AI coding tools require API keys from providers like OpenAI, Anthropic, or DeepSeek. Sign up for an account and generate your keys. +Kebanyakan alat pemrograman AI memerlukan kunci API dari penyedia seperti OpenAI, Anthropic, atau DeepSeek. Daftar akun dan buat kunci Anda. -### 3. Practice with Simple Tasks +### 3. Berlatih dengan Tugas Sederhana -Start by asking your AI agent to generate simple functions, explain code snippets, or suggest improvements to existing code. +Mulai dengan meminta agen AI Anda untuk menghasilkan fungsi sederhana, menjelaskan cuplikan kode, atau menyarankan perbaikan pada kode yang ada. -## Next Steps +## Langkah Selanjutnya -Once you're comfortable with basic AI coding, explore advanced topics like prompt engineering for better code generation and integrating AI into your CI/CD pipeline. +Setelah Anda nyaman dengan AI coding dasar, jelajahi topik lanjutan seperti prompt engineering untuk generasi kode yang lebih baik dan integrasi AI ke dalam pipeline CI/CD Anda. -The AI coding ecosystem is evolving rapidly. Stay updated with the latest tools and best practices through the [AI Coding Stack](/ai-coding-stack) documentation. +Ekosistem AI coding berkembang dengan cepat. Tetap terkini dengan alat dan best practices terbaru melalui dokumentasi [AI Coding Stack](/ai-coding-stack). diff --git a/content/articles/id/mcp-servers-explained.mdx b/content/articles/id/mcp-servers-explained.mdx index 0488888..1cef019 100644 --- a/content/articles/id/mcp-servers-explained.mdx +++ b/content/articles/id/mcp-servers-explained.mdx @@ -1,73 +1,73 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "Memahami Server MCP: Masa Depan Konteks AI" +description: "Eksplorasi mendalam tentang server Model Context Protocol, cara kerjanya, dan mengapa mereka penting untuk membangun asisten pemrograman AI cerdas yang benar-benar memahami proyek Anda." +date: "2025-01-10" --- -Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. +Server Model Context Protocol (MCP) mewakili perubahan paradigma dalam cara agen AI berinteraksi dengan alat eksternal, sumber data, dan API. Mereka adalah jaringan ikat yang mengubah model AI terisolasi menjadi companion pemrograman sadar konteks yang benar-benar memahami proyek Anda. -## What is MCP? +## Apa itu MCP? -The Model Context Protocol is an open standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. Think of MCP servers as specialized adapters that give your AI agent superpowers—whether that's reading from databases, searching the web, interacting with APIs, or accessing your filesystem. +Model Context Protocol adalah standar terbuka yang dikembangkan oleh Anthropic yang memungkinkan agen AI terhubung dengan aman ke sumber data eksternal dan alat. Bayangkan server MCP sebagai adaptor khusus yang memberikan superpower pada agen AI Anda—baik itu membaca dari database, mencari di web, berinteraksi dengan API, atau mengakses sistem file Anda. -Unlike traditional API integrations that require custom code for each tool, MCP provides a standardized interface. This means any MCP-compatible AI agent can use any MCP server without custom integration work. +Berbeda dengan integrasi API tradisional yang memerlukan kode kustom untuk setiap alat, MCP menyediakan antarmuka standar. Ini berarti agen AI yang kompatibel MCP dapat menggunakan server MCP apa pun tanpa pekerjaan integrasi kustom. -## How MCP Servers Work +## Cara Kerja Server MCP -An MCP server is a lightweight process that exposes three core primitives: +Server MCP adalah proses ringan yang mengekspos tiga primitif utama: ### Resources -Context and data that the AI can read. For example, a filesystem MCP server exposes your project files as resources. +Konteks dan data yang dapat dibaca oleh AI. Sebagai contoh, server MCP sistem file mengekspos file proyek Anda sebagai resources. ### Tools -Actions the AI can perform. A web search MCP might expose a search tool, while a database MCP could provide query execution tools. +Tindakan yang dapat dilakukan AI. Server MCP pencarian web mungkin mengekspos alat pencarian, sementara server MCP database dapat menyediakan alat eksekusi query. ### Prompts -Templated interactions that guide the AI. These can include best practices or common workflows specific to the tool. +Interaksi berbasis template yang memandu AI. Ini dapat mencakup best practices atau workflow umum yang spesifik untuk alat tersebut. -## Popular MCP Servers +## Server MCP Populer -The MCP ecosystem is rapidly growing. Here are some essential servers: +Ekosistem MCP berkembang dengan cepat. Berikut adalah beberapa server penting: -- **Filesystem** - Access local files and directories -- **Playwright** - Browser automation and web scraping -- **Context7** - Up-to-date library documentation -- **PostgreSQL** - Database queries and schema inspection -- **GitHub** - Repository management and code search -- **Brave Search** - Real-time web search capabilities +- **Filesystem** - Mengakses file dan direktori lokal +- **Playwright** - Otomatisasi browser dan web scraping +- **Context7** - Dokumentasi perpustakaan terkini +- **PostgreSQL** - Query database dan inspeksi skema +- **GitHub** - Manajemen repositori dan pencarian kode +- **Brave Search** - Kemampuan pencarian web real-time -## Why MCP Matters for AI Coding +## Mengapa MCP Penting untuk AI Coding -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +Sebelum MCP, asisten pemrograman AI pada dasarnya buta terhadap lingkungan pengembangan Anda. Mereka dapat menghasilkan kode berdasarkan data pelatihan, tetapi tidak dapat mengakses struktur proyek Anda yang sebenarnya, membaca file konfigurasi, atau berinteraksi dengan alat pengembangan Anda. -MCP changes this fundamentally. With MCP servers, your AI agent can: +MCP mengubah hal ini secara fundamental. Dengan server MCP, agen AI Anda dapat: -- Understand your entire codebase structure through filesystem access -- Look up current documentation for libraries you're using -- Execute database queries to understand your data model -- Search the web for the latest solutions to your specific problem -- Interact with your Git repository to understand commit history +- Memahami seluruh struktur codebase Anda melalui akses sistem file +- Mencari dokumentasi terkini untuk perpustakaan yang Anda gunakan +- Menjalankan query database untuk memahami model data Anda +- Mencari di web solusi terbaru untuk masalah spesifik Anda +- Berinteraksi dengan repositori Git Anda untuk memahami riwayat commit -## Getting Started with MCP +## Memulai dengan MCP -Most modern AI coding tools now support MCP. Setting up your first MCP server typically involves: +Sebagian besar alat pemrograman AI modern sekarang mendukung MCP. Menyiapkan server MCP pertama Anda biasanya melibatkan: -### 1. Choose an MCP Server +### 1. Pilih Server MCP -Start with something simple like the filesystem or web search MCP server. +Mulai dengan sesuatu yang sederhana seperti server MCP sistem file atau pencarian web. -### 2. Install the Server +### 2. Instal Server -Most MCP servers are distributed as npm packages or Python modules. Follow the installation instructions for your chosen server. +Kebanyakan server MCP didistribusikan sebagai paket npm atau modul Python. Ikuti instruksi instalasi untuk server pilihan Anda. -### 3. Configure Your IDE +### 3. Konfigurasi IDE Anda -Add the MCP server configuration to your IDE's settings. The exact format varies by tool, but typically involves specifying the server's command and any required arguments. +Tambahkan konfigurasi server MCP ke pengaturan IDE Anda. Format yang tepat bervariasi menurut alat, tetapi biasanya melibatkan penentuan perintah server dan argumen yang diperlukan. -Here's an example configuration for Claude Code: +Berikut adalah contoh konfigurasi untuk Claude Code: ```json { @@ -87,14 +87,14 @@ Here's an example configuration for Claude Code: } ``` -### 4. Test the Integration +### 4. Tes Integrasi -Ask your AI agent to use the newly connected tools. For example, if you installed a filesystem MCP, try asking it to read a specific file from your project. +Minta agen AI Anda menggunakan alat yang baru terhubung. Sebagai contoh, jika Anda menginstal server MCP sistem file, coba minta untuk membaca file tertentu dari proyek Anda. -## The Future of MCP +## Masa Depan MCP -The MCP ecosystem is still in its early stages, but the potential is enormous. As more developers build MCP servers for specialized tools and services, AI agents will become increasingly powerful and context-aware. +Ekosistem MCP masih pada tahap awal, tetapi potensinya sangat besar. Saat lebih banyak pengembang membangun server MCP untuk alat dan layanan khusus, agen AI akan menjadi semakin kuat dan sadar konteks. -We're moving toward a future where your AI coding assistant has seamless access to every tool in your development workflow—from your IDE to your cloud infrastructure. MCP is the protocol that makes this vision possible. +Kami bergerak menuju masa depan di mana asisten pemrograman AI memiliki akses mulus ke setiap alat dalam workflow pengembangan Anda—dari IDE hingga infrastruktur cloud Anda. MCP adalah protokol yang membuat visi ini menjadi mungkin. -Explore the full catalog of available MCP servers in our [MCP Servers directory](/ai-coding-stack/mcp-servers) to find the right integrations for your workflow. +Jelajahi katalog lengkap server MCP yang tersedia di [direktori server MCP](/ai-coding-stack/mcp-servers) kami untuk menemukan integrasi yang tepat untuk workflow Anda. diff --git a/content/articles/ja/getting-started-with-ai-coding.mdx b/content/articles/ja/getting-started-with-ai-coding.mdx index 135c215..6e27504 100644 --- a/content/articles/ja/getting-started-with-ai-coding.mdx +++ b/content/articles/ja/getting-started-with-ai-coding.mdx @@ -1,51 +1,51 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "AIコーディングの始め方：包括ガイド" +description: "IDE、CLI、コーディング生産性を向上させる必須ツールを使って、初めてのAI搭載開発環境を設定する方法を学びます。" +date: "2025-01-15" --- -The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. +AI搭載コーディングツールの台頭は、開発者がコードを書き、デバッグし、保守する方法を根本的に変革しました。経験豊富なエンジニアでも、コーディングの旅を始めたばかりでも、開発ワークフローにAIを統合することで、生産性とコード品質を劇的に向上させることができます。 -## Why AI Coding Matters +## AIコーディングが重要な理由 -Traditional coding involves writing every line manually, looking up documentation, and debugging through trial and error. AI coding assistants change this paradigm by: +従来のコーディングでは、すべての行を手書きし、ドキュメントを調べ、試行錯誤でデバッグする必要がありました。AIコーディングアシスタントは、このパラダイムを次のように変えます： -- Providing intelligent autocomplete that understands context -- Generating boilerplate code from natural language descriptions -- Catching bugs before they make it to production -- Explaining complex code in plain English -- Suggesting optimizations and best practices +- コンテキストを理解するインテリジェントな自動補完を提供 +- 自然言語の説明からボイラープレートコードを生成 +- 本番環境に到達する前にバグを検出 +- 平易な日本語で複雑なコードを説明 +- 最適化とベストプラクティスを提案 -## Choosing Your IDE +## IDEの選択 -Your choice of IDE is crucial for AI coding. The two most popular options are: +AIコーディングにとってIDEの選択は重要です。最も人気のある2つのオプションは以下の通りです： ### Cursor -Built from the ground up for AI pair programming. Cursor offers native AI chat, inline editing, and codebase-wide understanding. Best for developers who want AI deeply integrated into every aspect of their workflow. +AIペアプログラミングのためにゼロから構築されました。CursorはネイティブAIチャット、インライン編集、コードベース全体の理解を提供します。AIがワークフローのあらゆる側面に深く統合されていることを望む開発者に最適です。 -### VS Code + Extensions +### VS Code + 拡張機能 -Combine the familiar VS Code interface with AI extensions like GitHub Copilot, Codeium, or Tabnine. Best for developers who want to keep their existing setup while adding AI capabilities. +GitHub Copilot、Codeium、TabnineなどのAI拡張機能と、慣れ親しんだVS Codeインターフェースを組み合わせます。既存の設定を維持しながらAI機能を追加したい開発者に最適です。 -## Setting Up Your First AI Coding Environment +## 初めてのAIコーディング環境の設定 -Here's a step-by-step guide to get started: +始めるためのステップバイステップガイドは以下の通りです： -### 1. Choose Your IDE +### 1. IDEを選択する -Download and install either Cursor or VS Code with your preferred AI extension. +Cursorまたは好みのAI拡張機能付きのVS Codeをダウンロードしてインストールします。 -### 2. Configure API Keys +### 2. APIキーを設定する -Most AI coding tools require API keys from providers like OpenAI, Anthropic, or DeepSeek. Sign up for an account and generate your keys. +ほとんどのAIコーディングツールは、OpenAI、Anthropic、DeepSeekなどのプロバイダーからAPIキーを必要とします。アカウントに登録してキーを生成します。 -### 3. Practice with Simple Tasks +### 3. 簡単なタスクで練習する -Start by asking your AI agent to generate simple functions, explain code snippets, or suggest improvements to existing code. +AIエージェントにシンプルな関数を生成したり、コードスニペットを説明したり、既存のコードの改善を提案したりしてもらうことから始めます。 -## Next Steps +## 次のステップ -Once you're comfortable with basic AI coding, explore advanced topics like prompt engineering for better code generation and integrating AI into your CI/CD pipeline. +基本的なAIコーディングに慣れたら、より良いコード生成のためのプロンプトエンジニアリングやCI/CDパイプラインへのAI統合などの高度なトピックを探索します。 -The AI coding ecosystem is evolving rapidly. Stay updated with the latest tools and best practices through the [AI Coding Stack](/ai-coding-stack) documentation. +AIコーディングエコシステムは急速に進化しています。[AI Coding Stack](/ai-coding-stack)ドキュメントを通じて、最新のツールとベストプラクティスを把握してください。 diff --git a/content/articles/ja/mcp-servers-explained.mdx b/content/articles/ja/mcp-servers-explained.mdx index 0488888..8479e5d 100644 --- a/content/articles/ja/mcp-servers-explained.mdx +++ b/content/articles/ja/mcp-servers-explained.mdx @@ -1,73 +1,73 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "MCPサーバーの理解：AIコンテキストの未来" +description: "モデルコンテキストプロトコルサーバーの詳細、その仕組み、およびプロジェクトを真に理解するインテリジェントなAIコーディングアシスタントを構築するために重要な理由について詳しく解説します。" +date: "2025-01-10" --- -Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. +モデルコンテキストプロトコル（MCP）サーバーは、AIエージェントが外部ツール、データソース、APIと対話する方法にパラダイムシフトをもたらしています。それらは、孤立したAIモデルをプロジェクトを真に理解するコンテキスト認識コーディングコンパニオンに変換する接続組織です。 -## What is MCP? +## MCPとは何ですか？ -The Model Context Protocol is an open standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. Think of MCP servers as specialized adapters that give your AI agent superpowers—whether that's reading from databases, searching the web, interacting with APIs, or accessing your filesystem. +モデルコンテキストプロトコルは、Anthropicが開発したオープンスタンダードであり、AIエージェントが外部データソースとツールに安全に接続できるようにします。MCPサーバーを、AIエージェントにスーパーパワーを与える専用アダプターと考えてください—データベースからの読み取り、Web検索、APIとの対話、ファイルシステムへのアクセスなどが可能です。 -Unlike traditional API integrations that require custom code for each tool, MCP provides a standardized interface. This means any MCP-compatible AI agent can use any MCP server without custom integration work. +各ツールにカスタムコードが必要な従来のAPI統合とは異なり、MCPは標準化されたインターフェースを提供します。这意味着、MCP互換のAIエージェントはカスタム統合作業なしで任意のMCPサーバーを使用できます。 -## How MCP Servers Work +## MCPサーバーの仕組み -An MCP server is a lightweight process that exposes three core primitives: +MCPサーバーは、3つのコアプリミティブを公開する軽量プロセスです： -### Resources +### リソース -Context and data that the AI can read. For example, a filesystem MCP server exposes your project files as resources. +AIが読み取れるコンテキストとデータ。たとえば、ファイルシステムMCPサーバーはプロジェクトファイルをリソースとして公開します。 -### Tools +### ツール -Actions the AI can perform. A web search MCP might expose a search tool, while a database MCP could provide query execution tools. +AIが実行できるアクション。Web検索MCPは検索ツールを公開し、データベースMCPはクエリ実行ツールを提供できます。 -### Prompts +### プロンプト -Templated interactions that guide the AI. These can include best practices or common workflows specific to the tool. +AIをガイドするテンプレート化された対話。これらには、ツールに固有のベストプラクティスや一般的なワークフローが含まれる場合があります。 -## Popular MCP Servers +## 人気のあるMCPサーバー -The MCP ecosystem is rapidly growing. Here are some essential servers: +MCPエコシステムは急速に成長しています。以下はいくつかの必須サーバーです： -- **Filesystem** - Access local files and directories -- **Playwright** - Browser automation and web scraping -- **Context7** - Up-to-date library documentation -- **PostgreSQL** - Database queries and schema inspection -- **GitHub** - Repository management and code search -- **Brave Search** - Real-time web search capabilities +- **Filesystem** - ローカルファイルとディレクトリへのアクセス +- **Playwright** - ブラウザ自動化とWebスクレイピング +- **Context7** - 最新のライブラリドキュメント +- **PostgreSQL** - データベースクエリとスキーマ検査 +- **GitHub** - リポジトリ管理とコード検索 +- **Brave Search** - リアルタイムWeb検索機能 -## Why MCP Matters for AI Coding +## MCPがAIコーディングにとって重要な理由 -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +MCPの前は、AIコーディングアシスタントは本質的に開発環境に対して盲目でした。トレーニングデータに基づいてコードを生成することはできましたが、実際のプロジェクト構造にアクセスしたり、設定ファイルを読んだり、開発ツールと対話したりすることはできませんでした。 -MCP changes this fundamentally. With MCP servers, your AI agent can: +MCPはこれを根本的に変えます。MCPサーバーを使うと、AIエージェントは次のことができます： -- Understand your entire codebase structure through filesystem access -- Look up current documentation for libraries you're using -- Execute database queries to understand your data model -- Search the web for the latest solutions to your specific problem -- Interact with your Git repository to understand commit history +- ファイルシステムアクセスを通じてコードベース全体の構造を理解 +- 使用中のライブラリの最新のドキュメントを検索 +- データモデルを理解するためにデータベースクエリを実行 +- 特定の問題の最新のソリューションをWebで検索 +- コミット履歴を理解するためにGitリポジトリと対話 -## Getting Started with MCP +## MCPの始め方 -Most modern AI coding tools now support MCP. Setting up your first MCP server typically involves: +ほとんどの最新のAIコーディングツールはMCPをサポートしています。最初のMCPサーバーを設定するには、通常以下が含まれます： -### 1. Choose an MCP Server +### 1. MCPサーバーを選択する -Start with something simple like the filesystem or web search MCP server. +ファイルシステムまたはWeb検索MCPサーバーなどの単純なものから始めます。 -### 2. Install the Server +### 2. サーバーをインストールする -Most MCP servers are distributed as npm packages or Python modules. Follow the installation instructions for your chosen server. +ほとんどのMCPサーバーはnpmパッケージまたはPythonモジュールとして配布されています。選択したサーバーのインストール手順に従います。 -### 3. Configure Your IDE +### 3. IDEを設定する -Add the MCP server configuration to your IDE's settings. The exact format varies by tool, but typically involves specifying the server's command and any required arguments. +MCPサーバー設定をIDEの設定に追加します。正確な形式はツールにより異なりますが、通常はサーバーのコマンドと必要な引数を指定することが含まれます。 -Here's an example configuration for Claude Code: +Claude Codeの設定例は次の通りです： ```json { @@ -87,14 +87,14 @@ Here's an example configuration for Claude Code: } ``` -### 4. Test the Integration +### 4. 統合をテストする -Ask your AI agent to use the newly connected tools. For example, if you installed a filesystem MCP, try asking it to read a specific file from your project. +AIエージェントに新しく接続されたツールを使用するように頼みます。たとえば、ファイルシステムMCPをインストールした場合、プロジェクトから特定のファイルを読むように頼んでみてください。 -## The Future of MCP +## MCPの未来 -The MCP ecosystem is still in its early stages, but the potential is enormous. As more developers build MCP servers for specialized tools and services, AI agents will become increasingly powerful and context-aware. +MCPエコシステムはまだ初期段階ですが、可能性は巨大です。専門的なツールとサービスのためにより多くの開発者がMCPサーバーを構築するにつれて、AIエージェントはますます強力でコンテキスト認識になります。 -We're moving toward a future where your AI coding assistant has seamless access to every tool in your development workflow—from your IDE to your cloud infrastructure. MCP is the protocol that makes this vision possible. +私たちは、AIコーディングアシスタントが開発ワークフローのすべてのツール（IDEからクラウドインフラストラクチャまで）にシームレスにアクセスできる未来に向かっています。MCPはこのビジョンを実現するプロトコルです。 -Explore the full catalog of available MCP servers in our [MCP Servers directory](/ai-coding-stack/mcp-servers) to find the right integrations for your workflow. +ワークフローに適した統合を見つけるために、[MCPサーバーディレクトリ](/ai-coding-stack/mcp-servers)で利用可能なMCPサーバーの全カタログを探索してください。 diff --git a/content/articles/ko/getting-started-with-ai-coding.mdx b/content/articles/ko/getting-started-with-ai-coding.mdx index 28e5210..ef5591b 100644 --- a/content/articles/ko/getting-started-with-ai-coding.mdx +++ b/content/articles/ko/getting-started-with-ai-coding.mdx @@ -1,7 +1,7 @@ --- -title: 'AI 코딩 시작하기: 종합 가이드' -description: 'IDE, CLI 및 코딩 생산성을 높이는 데 필요한 필수 도구를 사용하여 첫 번째 AI 기반 개발 환경을 설정하는 방법을 알아보세요.' -date: '2025-01-15' +title: "AI 코딩 시작하기: 종합 가이드" +description: "IDE, CLI 및 코딩 생산성을 높이는 데 필요한 필수 도구를 사용하여 첫 번째 AI 기반 개발 환경을 설정하는 방법을 알아보세요." +date: "2025-01-15" --- AI 기반 코딩 도구의 등장은 개발자가 코드를 작성, 디버깅 및 유지보수하는 방식을 근본적으로 변화시켰습니다. 경험이 풍부한 엔지니어이든 코딩 여정을 막 시작했든, 개발 워크플로우에 AI를 통합하면 생산성과 코드 품질을 크게 향상시킬 수 있습니다. diff --git a/content/articles/ko/mcp-servers-explained.mdx b/content/articles/ko/mcp-servers-explained.mdx index 471c469..d028f4e 100644 --- a/content/articles/ko/mcp-servers-explained.mdx +++ b/content/articles/ko/mcp-servers-explained.mdx @@ -1,7 +1,7 @@ --- -title: 'MCP 서버 이해하기: AI 컨텍스트의 미래' -description: '모델 컨텍스트 프로토콜 서버에 대한 심층 분석, 작동 방식, 그리고 프로젝트를 진정으로 이해하는 지능형 AI 코딩 어시스턴트를 구축하는 데 중요한 이유.' -date: '2025-01-10' +title: "MCP 서버 이해하기: AI 컨텍스트의 미래" +description: "모델 컨텍스트 프로토콜 서버에 대한 심층 분석, 작동 방식, 그리고 프로젝트를 진정으로 이해하는 지능형 AI 코딩 어시스턴트를 구축하는 데 중요한 이유." +date: "2025-01-10" --- 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버는 AI 에이전트가 외부 도구, 데이터 소스 및 API와 상호 작용하는 방식의 패러다임 전환을 나타냅니다. 이들은 격리된 AI 모델을 프로젝트를 진정으로 이해하는 컨텍스트 인식 코딩 동반자로 변환하는 연결 조직입니다. diff --git a/content/articles/pt/getting-started-with-ai-coding.mdx b/content/articles/pt/getting-started-with-ai-coding.mdx index 135c215..adb8b5d 100644 --- a/content/articles/pt/getting-started-with-ai-coding.mdx +++ b/content/articles/pt/getting-started-with-ai-coding.mdx @@ -1,51 +1,51 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "Começando com AI Coding: Um Guia Completo" +description: "Aprenda como configurar o seu primeiro ambiente de desenvolvimento alimentado por IA com IDEs, CLIs e as ferramentas essenciais que você precisa para aumentar a sua produtividade de programação." +date: "2025-01-15" --- -The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. +O surgimento de ferramentas de programação alimentadas por IA transformou fundamentalmente a forma como os desenvolvedores escrevem, fazem debug e mantêm código. Seja você um engenheiro experiente ou apenas começando a sua jornada de programação, integrar IA no seu fluxo de trabalho de desenvolvimento pode aumentar dramaticamente a sua produtividade e qualidade de código. -## Why AI Coding Matters +## Por que AI Coding é Importante -Traditional coding involves writing every line manually, looking up documentation, and debugging through trial and error. AI coding assistants change this paradigm by: +A programação tradicional envolve escrever cada linha manualmente, procurar documentação e fazer debug através de tentativa e erro. Assistentes de programação com IA mudam este paradigma ao: -- Providing intelligent autocomplete that understands context -- Generating boilerplate code from natural language descriptions -- Catching bugs before they make it to production -- Explaining complex code in plain English -- Suggesting optimizations and best practices +- Fornecer autocompletar inteligente que entende o contexto +- Gerar código boilerplate a partir de descrições em linguagem natural +- Capturar bugs antes que chegarem à produção +- Explicar código complexo em português claro +- Sugerir otimizações e melhores práticas -## Choosing Your IDE +## Escolhendo o seu IDE -Your choice of IDE is crucial for AI coding. The two most popular options are: +A escolha do seu IDE é crucial para AI Coding. As duas opções mais populares são: ### Cursor -Built from the ground up for AI pair programming. Cursor offers native AI chat, inline editing, and codebase-wide understanding. Best for developers who want AI deeply integrated into every aspect of their workflow. +Construído desde o início para programação em parceria com IA. Cursor oferece chat de IA nativo, edição em linha e compreensão de toda a base de código. Ideal para desenvolvedores que querem IA profundamente integrada em todos os aspectos do seu fluxo de trabalho. -### VS Code + Extensions +### VS Code + Extensões -Combine the familiar VS Code interface with AI extensions like GitHub Copilot, Codeium, or Tabnine. Best for developers who want to keep their existing setup while adding AI capabilities. +Combine a interface familiar do VS Code com extensões de IA como GitHub Copilot, Codeium ou Tabnine. Ideal para desenvolvedores que querem manter a sua configuração existente enquanto adicionam capacidades de IA. -## Setting Up Your First AI Coding Environment +## Configurando o seu Primeiro Ambiente de AI Coding -Here's a step-by-step guide to get started: +Aqui está um guia passo a passo para começar: -### 1. Choose Your IDE +### 1. Escolha o seu IDE -Download and install either Cursor or VS Code with your preferred AI extension. +Baixe e instale o Cursor ou VS Code com a sua extensão de IA preferida. -### 2. Configure API Keys +### 2. Configure Chaves API -Most AI coding tools require API keys from providers like OpenAI, Anthropic, or DeepSeek. Sign up for an account and generate your keys. +A maioria das ferramentas de programação com IA requer chaves API de provedores como OpenAI, Anthropic ou DeepSeek. Cadastre-se em uma conta e gere as suas chaves. -### 3. Practice with Simple Tasks +### 3. Pratique com Tarefas Simples -Start by asking your AI agent to generate simple functions, explain code snippets, or suggest improvements to existing code. +Comece pedindo ao seu agente de IA para gerar funções simples, explicar trechos de código ou sugerir melhorias ao código existente. -## Next Steps +## Próximos Passos -Once you're comfortable with basic AI coding, explore advanced topics like prompt engineering for better code generation and integrating AI into your CI/CD pipeline. +Depois de se sentir confortável com AI Coding básico, explore tópicos avançados como engenharia de prompts para melhor geração de código e integração de IA no seu pipeline CI/CD. -The AI coding ecosystem is evolving rapidly. Stay updated with the latest tools and best practices through the [AI Coding Stack](/ai-coding-stack) documentation. +O ecossistema de AI Coding está evoluindo rapidamente. Mantenha-se atualizado com as últimas ferramentas e melhores práticas através da documentação [AI Coding Stack](/ai-coding-stack). diff --git a/content/articles/pt/mcp-servers-explained.mdx b/content/articles/pt/mcp-servers-explained.mdx index 0488888..06f38e4 100644 --- a/content/articles/pt/mcp-servers-explained.mdx +++ b/content/articles/pt/mcp-servers-explained.mdx @@ -1,100 +1,100 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "Entendendo Servidores MCP: O Futuro do Contexto de IA" +description: "Um mergulho profundo em servidores do Protocolo de Contexto de Modelo, como funcionam e por que são cruciais para construir assistentes de programação com IA inteligentes que realmente entendem o seu projeto." +date: "2025-01-10" --- -Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. +Servidores do Protocolo de Contexto de Modelo (MCP) representam uma mudança de paradigma na maneira como agentes de IA interagem com ferramentas externas, fontes de dados e APIs. Eles são o tecido conectivo que transforma modelos de IA isolados em companheiros de programação conscientes de contexto que realmente entendem o seu projeto. -## What is MCP? +## O que é MCP? -The Model Context Protocol is an open standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. Think of MCP servers as specialized adapters that give your AI agent superpowers—whether that's reading from databases, searching the web, interacting with APIs, or accessing your filesystem. +O Protocolo de Contexto de Modelo é um padrão aberto desenvolvido pela Anthropic que permite que agentes de IA se conectem de forma segura a fontes de dados externas e ferramentas. Pense nos servidores MCP como adaptadores especializados que dão superpoderes ao seu agente de IA—seja lendo de bancos de dados, pesquisando na web, interagindo com APIs ou acessando o seu sistema de arquivos. -Unlike traditional API integrations that require custom code for each tool, MCP provides a standardized interface. This means any MCP-compatible AI agent can use any MCP server without custom integration work. +Diferente das integrações de API tradicionais que exigem código personalizado para cada ferramenta, o MCP fornece uma interface padronizada. Isso significa que qualquer agente de IA compatível com MCP pode usar qualquer servidor MCP sem trabalho de integração personalizado. -## How MCP Servers Work +## Como os Servidores MCP Funcionam -An MCP server is a lightweight process that exposes three core primitives: +Um servidor MCP é um processo leve que expõe três primitivos principais: -### Resources +### Recursos -Context and data that the AI can read. For example, a filesystem MCP server exposes your project files as resources. +Contexto e dados que a IA pode ler. Por exemplo, um servidor MCP de sistema de arquivos expõe os seus arquivos de projeto como recursos. -### Tools +### Ferramentas -Actions the AI can perform. A web search MCP might expose a search tool, while a database MCP could provide query execution tools. +Ações que a IA pode executar. Um servidor MCP de pesquisa na web pode expor uma ferramenta de pesquisa, enquanto um servidor MCP de banco de dados pode fornecer ferramentas de execução de consultas. ### Prompts -Templated interactions that guide the AI. These can include best practices or common workflows specific to the tool. +Interações com modelos que guiam a IA. Estes podem incluir melhores práticas ou fluxos de trabalho comuns específicos para a ferramenta. -## Popular MCP Servers +## Servidores MCP Populares -The MCP ecosystem is rapidly growing. Here are some essential servers: +O ecossistema MCP está crescendo rapidamente. Aqui estão alguns servidores essenciais: -- **Filesystem** - Access local files and directories -- **Playwright** - Browser automation and web scraping -- **Context7** - Up-to-date library documentation -- **PostgreSQL** - Database queries and schema inspection -- **GitHub** - Repository management and code search -- **Brave Search** - Real-time web search capabilities +- **Filesystem** - Acessar arquivos e diretórios locais +- **Playwright** - Automação de navegador e web scraping +- **Context7** - Documentação de biblioteca atualizada +- **PostgreSQL** - Consultas de banco de dados e inspeção de esquema +- **GitHub** - Gestão de repositório e pesquisa de código +- **Brave Search** - Capacidades de pesquisa na web em tempo real -## Why MCP Matters for AI Coding +## Por que o MCP é Importante para AI Coding -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +Antes do MCP, assistentes de programação com IA eram essencialmente cegos ao seu ambiente de desenvolvimento. Podiam gerar código baseado em dados de treinamento, mas não conseguiam aceder à estrutura real do seu projeto, ler os seus ficheiros de configuração ou interagir com os seus ferramentas de desenvolvimento. -MCP changes this fundamentally. With MCP servers, your AI agent can: +O MCP muda isto fundamentalmente. Com servidores MCP, o seu agente de IA pode: -- Understand your entire codebase structure through filesystem access -- Look up current documentation for libraries you're using -- Execute database queries to understand your data model -- Search the web for the latest solutions to your specific problem -- Interact with your Git repository to understand commit history +- Entender toda a estrutura da sua base de código através do acesso ao sistema de arquivos +- Procurar documentação atualizada para as bibliotecas que está a usar +- Executar consultas de banco de dados para entender o seu modelo de dados +- Pesquisar na web as últimas soluções para o seu problema específico +- Interagir com o seu repositório Git para entender o histórico de commits -## Getting Started with MCP +## Começando com o MCP -Most modern AI coding tools now support MCP. Setting up your first MCP server typically involves: +A maioria das ferramentas modernas de programação com IA agora suporta MCP. Configurar o seu primeiro servidor MCP geralmente envolve: -### 1. Choose an MCP Server +### 1. Escolha um Servidor MCP -Start with something simple like the filesystem or web search MCP server. +Comece com algo simples como o servidor MCP de sistema de arquivos ou pesquisa na web. -### 2. Install the Server +### 2. Instale o Servidor -Most MCP servers are distributed as npm packages or Python modules. Follow the installation instructions for your chosen server. +A maioria dos servidores MCP são distribuídos como pacotes npm ou módulos Python. Siga as instruções de instalação para o seu servidor escolhido. -### 3. Configure Your IDE +### 3. Configure o seu IDE -Add the MCP server configuration to your IDE's settings. The exact format varies by tool, but typically involves specifying the server's command and any required arguments. +Adicione a configuração do servidor MCP às configurações do seu IDE. O formato exato varia por ferramenta, mas geralmente envolve especificar o comando do servidor e quaisquer argumentos necessários. -Here's an example configuration for Claude Code: +Aqui está um exemplo de configuração para Claude Code: ```json { "mcpServers": { "filesystem": { "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"] + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/caminho/para/o/seu/projeto"] }, "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { - "BRAVE_API_KEY": "your-api-key-here" + "BRAVE_API_KEY": "sua-chave-api-aqui" } } } } ``` -### 4. Test the Integration +### 4. Teste a Integração -Ask your AI agent to use the newly connected tools. For example, if you installed a filesystem MCP, try asking it to read a specific file from your project. +Peça ao seu agente de IA para usar as ferramentas recém-conectadas. Por exemplo, se instalou um servidor MCP de sistema de arquivos, tente pedir-lhe para ler um ficheiro específico do seu projeto. -## The Future of MCP +## O Futuro do MCP -The MCP ecosystem is still in its early stages, but the potential is enormous. As more developers build MCP servers for specialized tools and services, AI agents will become increasingly powerful and context-aware. +O ecossistema MCP ainda está nos seus estágios iniciais, mas o potencial é enorme. Conforme mais desenvolvedores constroem servidores MCP para ferramentas e serviços especializados, os agentes de IA tornar-se-ão cada vez mais poderosos e conscientes de contexto. -We're moving toward a future where your AI coding assistant has seamless access to every tool in your development workflow—from your IDE to your cloud infrastructure. MCP is the protocol that makes this vision possible. +Estamos a mover-nos em direção a um futuro onde o seu assistente de programação com IA tem acesso perfeito a todas as ferramentas no seu fluxo de trabalho de desenvolvimento—do seu IDE à sua infraestrutura cloud. O MCP é o protocolo que torna esta visão possível. -Explore the full catalog of available MCP servers in our [MCP Servers directory](/ai-coding-stack/mcp-servers) to find the right integrations for your workflow. +Explore o catálogo completo de servidores MCP disponíveis no nosso [diretório de servidores MCP](/ai-coding-stack/mcp-servers) para encontrar as integrações certas para o seu fluxo de trabalho. diff --git a/content/articles/ru/getting-started-with-ai-coding.mdx b/content/articles/ru/getting-started-with-ai-coding.mdx index 135c215..d66bcdc 100644 --- a/content/articles/ru/getting-started-with-ai-coding.mdx +++ b/content/articles/ru/getting-started-with-ai-coding.mdx @@ -1,51 +1,51 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "Начало работы с AI Coding: Полное руководство" +description: "Узнайте, как настроить вашу первую среду разработки на базе ИИ с использованием IDE, CLI и необходимых инструментов для повышения вашей продуктивности программирования." +date: "2025-01-15" --- -The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. +Восхождение инструментов программирования на базе ИИ коренным образом изменило то, как разработчики пишут, отлаживают и поддерживают код. Будь вы опытным инженером или только начинаете свой путь программирования, интеграция ИИ в ваш рабочий процесс разработки может значительно повысить вашу продуктивность и качество кода. -## Why AI Coding Matters +## Почему AI Coding важен -Traditional coding involves writing every line manually, looking up documentation, and debugging through trial and error. AI coding assistants change this paradigm by: +Традиционное программирование включает написание каждой строки вручную, поиск документации и отладку методом проб и ошибок. Ассистенты программирования на базе ИИ меняют этот парадигму, обеспечивая: -- Providing intelligent autocomplete that understands context -- Generating boilerplate code from natural language descriptions -- Catching bugs before they make it to production -- Explaining complex code in plain English -- Suggesting optimizations and best practices +- Интеллектуальное автодополнение, понимающее контекст +- Генерацию шаблонного кода на основе описаний на естественном языке +- Обнаружение ошибок до их попадания в продакшн +- Объяснение сложного кода простым русским языком +- Предложение оптимизаций и лучших практик -## Choosing Your IDE +## Выбор вашей IDE -Your choice of IDE is crucial for AI coding. The two most popular options are: +Выбор вашей IDE имеет решающее значение для AI Coding. Два самых популярных варианта: ### Cursor -Built from the ground up for AI pair programming. Cursor offers native AI chat, inline editing, and codebase-wide understanding. Best for developers who want AI deeply integrated into every aspect of their workflow. +Создан с нуля для парного программирования с ИИ. Cursor предлагает нативный чат ИИ, встроенное редактирование и понимание всей базы кода. Идеально подходит для разработчиков, которые хотят глубокую интеграцию ИИ во все аспекты своего рабочего процесса. -### VS Code + Extensions +### VS Code + Расширения -Combine the familiar VS Code interface with AI extensions like GitHub Copilot, Codeium, or Tabnine. Best for developers who want to keep their existing setup while adding AI capabilities. +Объедините знакомый интерфейс VS Code с расширениями ИИ, такими как GitHub Copilot, Codeium или Tabnine. Идеально подходит для разработчиков, которые хотят сохранить существующую настройку, добавив возможности ИИ. -## Setting Up Your First AI Coding Environment +## Настройка вашей первой среды AI Coding -Here's a step-by-step guide to get started: +Вот пошаговое руководство для начала работы: -### 1. Choose Your IDE +### 1. Выберите вашу IDE -Download and install either Cursor or VS Code with your preferred AI extension. +Скачайте и установите Cursor или VS Code с вашим любимым расширением ИИ. -### 2. Configure API Keys +### 2. Настройте API ключи -Most AI coding tools require API keys from providers like OpenAI, Anthropic, or DeepSeek. Sign up for an account and generate your keys. +Большинству инструментов программирования на базе ИИ требуются API ключи от таких поставщиков, как OpenAI, Anthropic или DeepSeek. Зарегистрируйте аккаунт и сгенерируйте ваши ключи. -### 3. Practice with Simple Tasks +### 3. Практикуйтесь с простыми задачами -Start by asking your AI agent to generate simple functions, explain code snippets, or suggest improvements to existing code. +Начните с того, что попросите ваш агент ИИ сгенерировать простые функции, объяснить фрагменты кода или предложить улучшения существующего кода. -## Next Steps +## Следующие шаги -Once you're comfortable with basic AI coding, explore advanced topics like prompt engineering for better code generation and integrating AI into your CI/CD pipeline. +Как только вы освоитесь с базовым AI Coding, изучите продвинутые темы, такие как проектирование промптов для лучшей генерации кода и интеграция ИИ в ваш конвейер CI/CD. -The AI coding ecosystem is evolving rapidly. Stay updated with the latest tools and best practices through the [AI Coding Stack](/ai-coding-stack) documentation. +Экосистема AI Coding быстро развивается. Будьте в курсе последних инструментов и лучших практик через документацию [AI Coding Stack](/ai-coding-stack). diff --git a/content/articles/ru/mcp-servers-explained.mdx b/content/articles/ru/mcp-servers-explained.mdx index 0488888..8696a86 100644 --- a/content/articles/ru/mcp-servers-explained.mdx +++ b/content/articles/ru/mcp-servers-explained.mdx @@ -1,73 +1,73 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "Понимание серверов MCP: Будущее контекста ИИ" +description: "Глубокое погружение в серверы протокола контекста модели, как они работают и почему они критически важны для создания интеллектуальных ассистентов программирования на базе ИИ, которые действительно понимают ваш проект." +date: "2025-01-10" --- -Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. +Серверы протокола контекста модели (MCP) представляют собой смену парадигмы в том, как агенты ИИ взаимодействуют с внешними инструментами, источниками данных и API. Они являются связующей тканью, которая превращает изолированные модели ИИ в контекстно-осознанные компаньоны программирования, которые действительно понимают ваш проект. -## What is MCP? +## Что такое MCP? -The Model Context Protocol is an open standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. Think of MCP servers as specialized adapters that give your AI agent superpowers—whether that's reading from databases, searching the web, interacting with APIs, or accessing your filesystem. +Протокол контекста модели — это открытый стандарт, разработанный Anthropic, который позволяет агентам ИИ безопасно подключаться к внешним источникам данных и инструментам. Представьте серверы MCP как специализированные адаптеры, которые дают вашему агенту ИИ суперспособности — будь то чтение из баз данных, поиск в интернете, взаимодействие с API или доступ к вашей файловой системе. -Unlike traditional API integrations that require custom code for each tool, MCP provides a standardized interface. This means any MCP-compatible AI agent can use any MCP server without custom integration work. +В отличие от традиционных интеграций API, требующих настраиваемого кода для каждого инструмента, MCP предоставляет стандартизированный интерфейс. Это означает, что любой агент ИИ, совместимый с MCP, может использовать любой сервер MCP без работы по настраиваемой интеграции. -## How MCP Servers Work +## Как работают серверы MCP -An MCP server is a lightweight process that exposes three core primitives: +Сервер MCP — это лёгкий процесс, который предоставляет три основных примитива: -### Resources +### Ресурсы -Context and data that the AI can read. For example, a filesystem MCP server exposes your project files as resources. +Контекст и данные, которые ИИ может читать. Например, сервер MCP файловой системы предоставляет файлы вашего проекта как ресурсы. -### Tools +### Инструменты -Actions the AI can perform. A web search MCP might expose a search tool, while a database MCP could provide query execution tools. +Действия, которые может выполнять ИИ. Сервер MCP веб-поиска может предоставить инструмент поиска, а сервер MCP базы данных — инструменты выполнения запросов. -### Prompts +### Промпты -Templated interactions that guide the AI. These can include best practices or common workflows specific to the tool. +Шаблонные взаимодействия, которые направляют ИИ. Они могут включать лучшие практики или общие рабочие процессы, специфичные для инструмента. -## Popular MCP Servers +## Популярные серверы MCP -The MCP ecosystem is rapidly growing. Here are some essential servers: +Экосистема MCP быстро растёт. Вот некоторые важные серверы: -- **Filesystem** - Access local files and directories -- **Playwright** - Browser automation and web scraping -- **Context7** - Up-to-date library documentation -- **PostgreSQL** - Database queries and schema inspection -- **GitHub** - Repository management and code search -- **Brave Search** - Real-time web search capabilities +- **Filesystem** — доступ к локальным файлам и каталогам +- **Playwright** — автоматизация браузера и веб-скрапинг +- **Context7** — актуальная документация библиотек +- **PostgreSQL** — запросы к базе данных и инспекция схемы +- **GitHub** — управление репозиторием и поиск кода +- **Brave Search** — возможности веб-поиска в реальном времени -## Why MCP Matters for AI Coding +## Почему MCP важен для AI Coding -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +До MCP ассистенты программирования на базе ИИ были по существу слепы к вашей среде разработки. Они могли генерировать код на основе обучающих данных, но не могли получить доступ к фактической структуре вашего проекта, читать файлы конфигурации или взаимодействовать с вашими инструментами разработки. -MCP changes this fundamentally. With MCP servers, your AI agent can: +MCP радикально меняет это. С серверами MCP ваш агент ИИ может: -- Understand your entire codebase structure through filesystem access -- Look up current documentation for libraries you're using -- Execute database queries to understand your data model -- Search the web for the latest solutions to your specific problem -- Interact with your Git repository to understand commit history +- Понимать всю структуру вашей базы кода через доступ к файловой системе +- Искать актуальную документацию для используемых вами библиотек +- Выполнять запросы к базе данных для понимания вашей модели данных +- Искать в интернете последние решения для вашей конкретной проблемы +- Взаимодействовать с вашим репозиторием Git для понимания истории коммитов -## Getting Started with MCP +## Начало работы с MCP -Most modern AI coding tools now support MCP. Setting up your first MCP server typically involves: +Большинство современных инструментов программирования на базе ИИ теперь поддерживают MCP. Настройка вашего первого сервера MCP обычно включает: -### 1. Choose an MCP Server +### 1. Выберите сервер MCP -Start with something simple like the filesystem or web search MCP server. +Начните с чего-то простого, например, с сервера MCP файловой системы или веб-поиска. -### 2. Install the Server +### 2. Установите сервер -Most MCP servers are distributed as npm packages or Python modules. Follow the installation instructions for your chosen server. +Большинство серверов MCP распространяются как пакеты npm или модули Python. Следуйте инструкциям по установке для выбранного сервера. -### 3. Configure Your IDE +### 3. Настройте вашу IDE -Add the MCP server configuration to your IDE's settings. The exact format varies by tool, but typically involves specifying the server's command and any required arguments. +Добавьте конфигурацию сервера MCP в настройки вашей IDE. Точный формат зависит от инструмента, но обычно включает указание команды сервера и необходимых аргументов. -Here's an example configuration for Claude Code: +Вот пример конфигурации для Claude Code: ```json { @@ -87,14 +87,14 @@ Here's an example configuration for Claude Code: } ``` -### 4. Test the Integration +### 4. Протестируйте интеграцию -Ask your AI agent to use the newly connected tools. For example, if you installed a filesystem MCP, try asking it to read a specific file from your project. +Попросите вашего агента ИИ использовать вновь подключённые инструменты. Например, если вы установили сервер MCP файловой системы, попробуйте попросить его прочитать определённый файл из вашего проекта. -## The Future of MCP +## Будущее MCP -The MCP ecosystem is still in its early stages, but the potential is enormous. As more developers build MCP servers for specialized tools and services, AI agents will become increasingly powerful and context-aware. +Экосистема MCP всё ещё находится на ранних этапах, но потенциал огромен. По мере того как больше разработчиков будут создавать серверы MCP для специализированных инструментов и сервисов, агенты ИИ станут всё более мощными и осознанными контекста. -We're moving toward a future where your AI coding assistant has seamless access to every tool in your development workflow—from your IDE to your cloud infrastructure. MCP is the protocol that makes this vision possible. +Мы движемся к будущему, где ваш ассистент программирования на базе ИИ имеет бесшовный доступ к каждому инструменту в вашем потоке разработки — от вашей IDE до вашей облачной инфраструктуры. MCP — это протокол, который делает это видение возможным. -Explore the full catalog of available MCP servers in our [MCP Servers directory](/ai-coding-stack/mcp-servers) to find the right integrations for your workflow. +Исследуйте полный каталог доступных серверов MCP в нашем [каталоге серверов MCP](/ai-coding-stack/mcp-servers), чтобы найти подходящие интеграции для вашего рабочего процесса. diff --git a/content/articles/tr/getting-started-with-ai-coding.mdx b/content/articles/tr/getting-started-with-ai-coding.mdx index 135c215..92db373 100644 --- a/content/articles/tr/getting-started-with-ai-coding.mdx +++ b/content/articles/tr/getting-started-with-ai-coding.mdx @@ -1,51 +1,51 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "Yapay Zeka Kodlamaya Başlarken: Kapsamlı Bir Rehber" +description: "IDE'ler, CLI'ler ve kodlama verimliliğinizi artırmak için ihtiyacınız olan temel araçları kullanarak yapay zeka destekli ilk geliştirme ortamınızı nasıl kuracağınızı öğrenin." +date: "2025-01-15" --- -The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. +Yapay zeka destekli kodlama araçlarının yükselişi, geliştiricilerin kod yazma, hata ayıklama ve bakım yapma şeklini kökten değiştirdi. İster deneyimli bir mühendis olun ister kodlama yolculuğunuza yeni başlıyor olun, geliştirme iş akışınıza yapay zeka entegrasyonu, verimliliğinizi ve kod kalitenizi önemli ölçüde artırabilir. -## Why AI Coding Matters +## Yapay Zeka Kodlaması Neden Önemli -Traditional coding involves writing every line manually, looking up documentation, and debugging through trial and error. AI coding assistants change this paradigm by: +Geleneksel kodlama, her satırı manuel olarak yazmayı, dokümantasyon aramayı ve deneme-yanılma ile hata ayıklamayı içerir. Yapay zeka kodlama asistanları bu paradigmayı şu şekilde değiştirir: -- Providing intelligent autocomplete that understands context -- Generating boilerplate code from natural language descriptions -- Catching bugs before they make it to production -- Explaining complex code in plain English -- Suggesting optimizations and best practices +- Bağlamı anlayan akıllı otomatik tamamlama sağlama +- Doğal dil açıklamalarından örnek kod oluşturma +- Hataları üretim ortamına ulaşmadan önce yakalama +- Karmaşık kodları sade Türkçe ile açıklama +- Optimizasyonlar ve en iyi yöntemler önerme -## Choosing Your IDE +## IDE'nizi Seçin -Your choice of IDE is crucial for AI coding. The two most popular options are: +Yapay zeka kodlaması için IDE seçiminiz çok önemlidir. En popüler iki seçenek: ### Cursor -Built from the ground up for AI pair programming. Cursor offers native AI chat, inline editing, and codebase-wide understanding. Best for developers who want AI deeply integrated into every aspect of their workflow. +Yapay zeka ile eş programlama için sıfırdan inşa edildi. Cursor, yerel yapay zeka sohbeti, satır içi düzenleme ve tüm kod tabanı anlayışı sunar. Yapay zekanın iş akışlarının her yönüne derinlemesine entegre edilmesini isteyen geliştiriciler için en iyisidir. -### VS Code + Extensions +### VS Code + Eklentiler -Combine the familiar VS Code interface with AI extensions like GitHub Copilot, Codeium, or Tabnine. Best for developers who want to keep their existing setup while adding AI capabilities. +GitHub Copilot, Codeium veya Tabnine gibi yapay zeka eklentileriyle tanıdık VS Code arayüzünü birleştirin. Mevcut kurulumlarını korurken yetenekleri eklemek isteyen geliştiriciler için en iyisidir. -## Setting Up Your First AI Coding Environment +## İlk Yapay Zeka Kodlama Ortamınızı Kurma -Here's a step-by-step guide to get started: +Başlamak için adım adım rehber: -### 1. Choose Your IDE +### 1. IDE'nizi Seçin -Download and install either Cursor or VS Code with your preferred AI extension. +Cursor veya tercih ettiğiniz yapay zeka eklentili VS Code'u indirin ve yükleyin. -### 2. Configure API Keys +### 2. API Anahtarlarını Yapılandırın -Most AI coding tools require API keys from providers like OpenAI, Anthropic, or DeepSeek. Sign up for an account and generate your keys. +Çoğu yapay zeka kodlama aracı, OpenAI, Anthropic veya DeepSeek gibi sağlayıcılardan API anahtarları gerektirir. Bir hesap kaydedin ve anahtarlarınızı oluşturun. -### 3. Practice with Simple Tasks +### 3. Basit Görevlerle Pratik Yapın -Start by asking your AI agent to generate simple functions, explain code snippets, or suggest improvements to existing code. +Yapay zeka ajanınıza basit işlevler oluşturmasını, kod parçacıklarını açıklamasını veya mevcut koda iyileştirmeler önermesini isteğiyle başlayın. -## Next Steps +## Sonraki Adımlar -Once you're comfortable with basic AI coding, explore advanced topics like prompt engineering for better code generation and integrating AI into your CI/CD pipeline. +Temel yapay zeka kodlamaya alıştığınızda, daha iyi kod oluşturma için istem mühendisliği ve CI/CD boru hattına yapay zeka entegrasyonu gibi ileri düzey konuları keşfedin. -The AI coding ecosystem is evolving rapidly. Stay updated with the latest tools and best practices through the [AI Coding Stack](/ai-coding-stack) documentation. +Yapay zeka kodlama ekosistemi hızla gelişiyor. [AI Coding Stack](/ai-coding-stack) dokümantasyonu aracılığıyla en son araçları ve en iyi yöntemleri takip edin. diff --git a/content/articles/tr/mcp-servers-explained.mdx b/content/articles/tr/mcp-servers-explained.mdx index 0488888..56bf1f5 100644 --- a/content/articles/tr/mcp-servers-explained.mdx +++ b/content/articles/tr/mcp-servers-explained.mdx @@ -1,73 +1,73 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "MCP Sunucularını Anlamak: Yapay Zeka Bağlamının Geleceği" +description: "Model Bağlam Protokolü sunucularını, nasıl çalıştıklarını ve projenizi gerçekten anlayan akıllı yapay zeka kodlama asistanları oluşturmak için neden kritik olduklarını derinlemesine anlayın." +date: "2025-01-10" --- -Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. +Model Bağlam Protokolü (MCP) sunucuları, yapay zeka ajanlarının dış araçlarla, veri kaynaklarıyla ve API'lerle etkileşim şeklinde bir paradigm değişikliği temsil eder. Projeyi gerçekten anlayan bağlama duyarlı kodlama ortaklarına izole yapay zeka modellerini dönüştüren bağlayıcı dokudurlar. -## What is MCP? +## MCP Nedir? -The Model Context Protocol is an open standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. Think of MCP servers as specialized adapters that give your AI agent superpowers—whether that's reading from databases, searching the web, interacting with APIs, or accessing your filesystem. +Model Bağlam Protokolü, yapay zeka ajanlarını dış veri kaynaklarına ve toolara güvenli bağlanmasına olanak tanıyan Anthropic tarafından geliştirilen açık bir standarttır. MCP sunucularını, yapay zeka ajanınıza süper güçler veren özel adaptörler olarak düşünün—isterseniz veritabanlarından okuma, web arama, API etkileşimi veya dosya sisteminize erişim ve diğerleri. -Unlike traditional API integrations that require custom code for each tool, MCP provides a standardized interface. This means any MCP-compatible AI agent can use any MCP server without custom integration work. +Her araç için özel kod gerektiren geleneksel API entegrasyonlarının aksine, MCP standart bir arayüz sağlar. Bu, MCP uyumlu herhangi bir yapay zeka ajanının özel entegrasyon çalışması olmadan herhangi bir MCP sunucusunu kullanabileceği anlamına gelir. -## How MCP Servers Work +## MCP Sunucuları Nasıl Çalışır -An MCP server is a lightweight process that exposes three core primitives: +Bir MCP sunucusu, üç temel ilkeyi sunan hafif bir işlemdir: -### Resources +### Kaynaklar -Context and data that the AI can read. For example, a filesystem MCP server exposes your project files as resources. +Yapay zekanın okuyabileceği bağlam ve veriler. Örneğin, bir dosya sistemi MCP sunucusu proje dosyalarınızı kaynak olarak sunar. -### Tools +### Araçlar -Actions the AI can perform. A web search MCP might expose a search tool, while a database MCP could provide query execution tools. +Yapay zekanın gerçekleştirebileceği eylemler. Bir web arama MCP'si bir arama aracı, bir veritabanı MCP'sı ise sorgu yürütme araçları sunabilir. -### Prompts +### İstemler -Templated interactions that guide the AI. These can include best practices or common workflows specific to the tool. +Yapay zekayı yönlendiren şablonlu etkileşimler. Bunlar, araca özgü en iyi teknikler veya genel iş akışları içerebilir. -## Popular MCP Servers +## Popüler MCP Sunucuları -The MCP ecosystem is rapidly growing. Here are some essential servers: +MCP ekosistemi hızla büyüyor. İşte bazı temel sunucular: -- **Filesystem** - Access local files and directories -- **Playwright** - Browser automation and web scraping -- **Context7** - Up-to-date library documentation -- **PostgreSQL** - Database queries and schema inspection -- **GitHub** - Repository management and code search -- **Brave Search** - Real-time web search capabilities +- **Filesystem** - Yerel dosya ve dizinlere erişim +- **Playwright** - Tarayıcı otomasyonu ve web kazıma +- **Context7** - Güncel kütüphane belgeleri +- **PostgreSQL** - Veritabanı sorguları ve şema incelemesi +- **GitHub** - Depo yönetimi ve kod arama +- **Brave Search** - Gerçek zamanlı web arama yetenekleri -## Why MCP Matters for AI Coding +## MCP AI Kodlama İçin Neden Önemli -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +MCP'den önce, yapay zeka kodlama asistanları geliştirme ortamınıza esasen kördüler. Eğitim verilerine dayalı kod oluşturabilirlerdi, ancak gerçek proje yapınıza erişemezler, yapılandırma dosyalarınızı okuyamaz veya geliştirme araçlarınızla etkileşemezlerdi. -MCP changes this fundamentally. With MCP servers, your AI agent can: +MCP bunu kökten değiştirir. MCP sunucuları ile yapay zeka ajanınız şunları yapabilir: -- Understand your entire codebase structure through filesystem access -- Look up current documentation for libraries you're using -- Execute database queries to understand your data model -- Search the web for the latest solutions to your specific problem -- Interact with your Git repository to understand commit history +- Dosya sistemi erişimi yoluyla tüm kod tabanı yapısını anlama +- Kullandığınız kütüphaneler için güncel belgeleri arama +- Veri modelinizi anlamak için veritabanı sorguları yürütme +- Belirli sorununuz için en son çözümleri web'de arama +- İşlem geçmişini anlamak için Git deponuzla etkileşim -## Getting Started with MCP +### MCP'ye Başlarken -Most modern AI coding tools now support MCP. Setting up your first MCP server typically involves: +Çoğu modern yapay zeka kodlama aracı artık MCP'yi destekliyor. İlk MCP sunucunuzu kurmak genellikle şunları içerir: -### 1. Choose an MCP Server +### 1. MCP Sunucusunu Seçin -Start with something simple like the filesystem or web search MCP server. +Basit bir şeyle başlayın, örneğin dosya sistemi veya web arama MCP sunucusu. -### 2. Install the Server +### 2. Sunucuyu Yükleyin -Most MCP servers are distributed as npm packages or Python modules. Follow the installation instructions for your chosen server. +Çoğu MCP sunucusu npm paketleri veya Python modülleri olarak dağıtılır. Seçtiğiniz sunucunun yükleme talimatlarını izleyin. -### 3. Configure Your IDE +### 3. IDE'nizi Yapılandırın -Add the MCP server configuration to your IDE's settings. The exact format varies by tool, but typically involves specifying the server's command and any required arguments. +MCP sunucusu yapılandırmasını IDE ayarlarınıza ekleyin. Tam format araca göre değişir, ancak genellikle sunucunun komutunu ve gerekli argümanları belirtmeyi içerir. -Here's an example configuration for Claude Code: +İşte Claude Code için örnek bir yapılandırma: ```json { @@ -87,14 +87,14 @@ Here's an example configuration for Claude Code: } ``` -### 4. Test the Integration +### 4. Entegrasyonu Test Edin -Ask your AI agent to use the newly connected tools. For example, if you installed a filesystem MCP, try asking it to read a specific file from your project. +Yapay zeka ajanınıza yeni bağlanan araçları kullanmasını isteyin. Örneğin, bir dosya sistemi MCP yüklediyseniz, projenizden belirli bir dosyayı okumasını isteyin. -## The Future of MCP +## MCP'nin Geleceği -The MCP ecosystem is still in its early stages, but the potential is enormous. As more developers build MCP servers for specialized tools and services, AI agents will become increasingly powerful and context-aware. +MCP ekosistemi henüz erken aşamalarında, ancak potansiyel çok büyük. Daha fazla geliştirici kendi işlevsel araçlar ve servisler için MCP sunucuları oluşturdukça, yapay zeka ajanları giderek daha güçlü ve bağlama duyarlı hale gelecektir. -We're moving toward a future where your AI coding assistant has seamless access to every tool in your development workflow—from your IDE to your cloud infrastructure. MCP is the protocol that makes this vision possible. +Yapay zeka kodlama asistanının geliştirme iş akışınızdaki her araca—IDE'nizden bulut altyapınıza kadar—sorunsuz erişime sahip olduğu bir geleceğe doğru hareket ediyoruz. MCP bu vizyonu mümkün kılan protokoldür. -Explore the full catalog of available MCP servers in our [MCP Servers directory](/ai-coding-stack/mcp-servers) to find the right integrations for your workflow. +İş akışınız için doğru entegrasyonları bulmak için kullanılabilir MCP sunucularının tam kataloğunu [MCP Sunucuları dizinimizde](/ai-coding-stack/mcp-servers) keşfedin. diff --git a/content/articles/zh-Hans/getting-started-with-ai-coding.mdx b/content/articles/zh-Hans/getting-started-with-ai-coding.mdx index 48ecd0d..f6a4948 100644 --- a/content/articles/zh-Hans/getting-started-with-ai-coding.mdx +++ b/content/articles/zh-Hans/getting-started-with-ai-coding.mdx @@ -1,7 +1,7 @@ --- -title: 'AI 编码入门:综合指南' -description: '学习如何使用 IDE、命令行和必备工具搭建你的第一个 AI 驱动开发环境,提升编码生产力。' -date: '2025-01-15' +title: "AI 编码入门:综合指南" +description: "学习如何使用 IDE、命令行和必备工具搭建你的第一个 AI 驱动开发环境,提升编码生产力。" +date: "2025-01-15" --- AI 驱动的编码工具的兴起从根本上改变了开发者编写、调试和维护代码的方式。无论你是经验丰富的工程师还是刚开始编码之旅,将 AI 集成到开发工作流中都能显著提升你的生产力和代码质量。 diff --git a/content/articles/zh-Hans/mcp-servers-explained.mdx b/content/articles/zh-Hans/mcp-servers-explained.mdx index 1151a61..9ac00a3 100644 --- a/content/articles/zh-Hans/mcp-servers-explained.mdx +++ b/content/articles/zh-Hans/mcp-servers-explained.mdx @@ -1,7 +1,7 @@ --- -title: '理解 MCP 服务器：AI 上下文的未来' -description: '深入了解模型上下文协议服务器的工作原理，以及为什么它们对构建真正理解你项目的智能 AI 编码助手至关重要。' -date: '2025-01-10' +title: "理解 MCP 服务器：AI 上下文的未来" +description: "深入了解模型上下文协议服务器的工作原理，以及为什么它们对构建真正理解你项目的智能 AI 编码助手至关重要。" +date: "2025-01-10" --- 模型上下文协议(MCP)服务器代表了 AI Agent 与外部工具、数据源和 API 交互方式的范式转变。它们是将孤立的 AI 模型转变为真正理解你项目的上下文感知编码伙伴的连接组织。 diff --git a/content/articles/zh-Hant/getting-started-with-ai-coding.mdx b/content/articles/zh-Hant/getting-started-with-ai-coding.mdx index 135c215..634b292 100644 --- a/content/articles/zh-Hant/getting-started-with-ai-coding.mdx +++ b/content/articles/zh-Hant/getting-started-with-ai-coding.mdx @@ -1,51 +1,51 @@ --- -title: 'Getting Started with AI Coding: A Comprehensive Guide' -description: 'Learn how to set up your first AI-powered development environment with IDEs, CLIs, and the essential tools you need to boost your coding productivity.' -date: '2025-01-15' +title: "AI 編碼入門：綜合指南" +description: "學習如何使用 IDE、命令列和必備工具搭建你的第一個 AI 驅動開發環境，提升編碼生產力。" +date: "2025-01-15" --- -The rise of AI-powered coding tools has fundamentally transformed how developers write, debug, and maintain code. Whether you're a seasoned engineer or just starting your coding journey, integrating AI into your development workflow can dramatically boost your productivity and code quality. +AI 驅動的編碼工具的興起從根本上改變了開發者編寫、調試和維護代碼的方式。無論你是經驗豐富的工程師還是剛開始編碼之旅，將 AI 集成到開發工作流中都能顯著提升你的生產力和代碼品質。 -## Why AI Coding Matters +## 為什麼 AI 編碼很重要 -Traditional coding involves writing every line manually, looking up documentation, and debugging through trial and error. AI coding assistants change this paradigm by: +傳統編碼涉及手動編寫每一行代碼、查閱文檔以及通過試錯進行調試。AI 編碼助手改變了這一範式： -- Providing intelligent autocomplete that understands context -- Generating boilerplate code from natural language descriptions -- Catching bugs before they make it to production -- Explaining complex code in plain English -- Suggesting optimizations and best practices +- 提供理解上下文的智能自動完成 +- 從自然語言描述生成樣板代碼 +- 在錯誤進入生產環境之前捕獲它們 +- 用簡單的語言解釋複雜代碼 +- 建議優化和最佳實踐 -## Choosing Your IDE +## 選擇你的 IDE -Your choice of IDE is crucial for AI coding. The two most popular options are: +IDE 的選擇對 AI 編碼至關重要。兩個最受歡迎的選項是： ### Cursor -Built from the ground up for AI pair programming. Cursor offers native AI chat, inline editing, and codebase-wide understanding. Best for developers who want AI deeply integrated into every aspect of their workflow. +為 AI 結對編程而從頭構建。Cursor 提供原生 AI 聊天、內聯編輯和整個代碼庫的理解能力。最適合希望將 AI 深度集成到工作流每個方面的開發者。 -### VS Code + Extensions +### VS Code + 擴展 -Combine the familiar VS Code interface with AI extensions like GitHub Copilot, Codeium, or Tabnine. Best for developers who want to keep their existing setup while adding AI capabilities. +將熟悉的 VS Code 介面與 GitHub Copilot、Codeium 或 Tabnine 等 AI 擴展相結合。最適合希望在現有設置上添加 AI 功能的開發者。 -## Setting Up Your First AI Coding Environment +## 搭建你的第一個 AI 編碼環境 -Here's a step-by-step guide to get started: +以下是入門的分步指南： -### 1. Choose Your IDE +### 1. 選擇你的 IDE -Download and install either Cursor or VS Code with your preferred AI extension. +下載並安裝 Cursor 或帶有你首選 AI 擴展的 VS Code。 -### 2. Configure API Keys +### 2. 配置 API 密鑰 -Most AI coding tools require API keys from providers like OpenAI, Anthropic, or DeepSeek. Sign up for an account and generate your keys. +大多數 AI 編碼工具需要來自 OpenAI、Anthropic 或 DeepSeek 等供應商的 API 密鑰。註冊帳戶並生成你的密鑰。 -### 3. Practice with Simple Tasks +### 3. 從簡單任務練習 -Start by asking your AI agent to generate simple functions, explain code snippets, or suggest improvements to existing code. +首先讓你的 AI Agent 生成簡單函數、解釋代碼片段或建議改進現有代碼。 -## Next Steps +## 下一步 -Once you're comfortable with basic AI coding, explore advanced topics like prompt engineering for better code generation and integrating AI into your CI/CD pipeline. +一旦你熟悉了基本的 AI 編碼，探索高級主題，如提示工程以獲得更好的代碼生成，以及將 AI 集成到 CI/CD 流程中。 -The AI coding ecosystem is evolving rapidly. Stay updated with the latest tools and best practices through the [AI Coding Stack](/ai-coding-stack) documentation. +AI 編碼生態系統正在快速發展。通過 [AI 編碼技術棧](/ai-coding-stack) 文檔了解最新工具和最佳實踐。 diff --git a/content/articles/zh-Hant/mcp-servers-explained.mdx b/content/articles/zh-Hant/mcp-servers-explained.mdx index 0488888..7e36d38 100644 --- a/content/articles/zh-Hant/mcp-servers-explained.mdx +++ b/content/articles/zh-Hant/mcp-servers-explained.mdx @@ -1,73 +1,73 @@ --- -title: 'Understanding MCP Servers: The Future of AI Context' -description: 'Deep dive into Model Context Protocol servers, how they work, and why they are crucial for building intelligent AI coding assistants that truly understand your project.' -date: '2025-01-10' +title: "理解 MCP 伺服器：AI 上下文的未來" +description: "深入了解模型上下文協議伺服器的工作原理，以及為什麼它們對構建真正理解你項目的智能 AI 編碼助手至關重要。" +date: "2025-01-10" --- -Model Context Protocol (MCP) servers represent a paradigm shift in how AI agents interact with external tools, data sources, and APIs. They are the connective tissue that transforms isolated AI models into context-aware coding companions that truly understand your project. +模型上下文協議(MCP)伺服器代表了 AI Agent 與外部工具、數據源和 API 交互方式的範式轉變。它們是將孤立的 AI 模型轉變為真正理解你項目的上下文感知編碼夥伴的連接組織。 -## What is MCP? +## 什麼是 MCP? -The Model Context Protocol is an open standard developed by Anthropic that enables AI agents to securely connect to external data sources and tools. Think of MCP servers as specialized adapters that give your AI agent superpowers—whether that's reading from databases, searching the web, interacting with APIs, or accessing your filesystem. +模型上下文協議是 Anthropic 開發的開放標準，使 AI Agent 能夠安全地連接到外部數據源和工具。可以把 MCP 伺服器想像成專門的適配器，賦予你的 AI Agent 超能力——無論是從數據庫讀取、搜索網頁、與 API 交互還是訪問你的文件系統。 -Unlike traditional API integrations that require custom code for each tool, MCP provides a standardized interface. This means any MCP-compatible AI agent can use any MCP server without custom integration work. +與需要為每個工具編寫自定義代碼的傳統 API 集成不同，MCP 提供了標準化接口。這意味著任何兼容 MCP 的 AI Agent 都可以使用任何 MCP 伺服器，無需自定義集成工作。 -## How MCP Servers Work +## MCP 伺服器的工作原理 -An MCP server is a lightweight process that exposes three core primitives: +MCP 伺服器是一個輕量級進程，暴露三個核心原語： -### Resources +### 資源(Resources) -Context and data that the AI can read. For example, a filesystem MCP server exposes your project files as resources. +AI 可以讀取的上下文和數據。例如，文件系統 MCP 伺服器將你的項目文件作為資源暴露。 -### Tools +### 工具(Tools) -Actions the AI can perform. A web search MCP might expose a search tool, while a database MCP could provide query execution tools. +AI 可以執行的操作。網頁搜索 MCP 可能暴露搜索工具，而數據庫 MCP 可以提供查詢執行工具。 -### Prompts +### 提示(Prompts) -Templated interactions that guide the AI. These can include best practices or common workflows specific to the tool. +引導 AI 的模板化交互。這些可以包括特定於工具的最佳實踐或常見工作流。 -## Popular MCP Servers +## 流行的 MCP 伺服器 -The MCP ecosystem is rapidly growing. Here are some essential servers: +MCP 生態系統正在快速增長。以下是一些必備伺服器： -- **Filesystem** - Access local files and directories -- **Playwright** - Browser automation and web scraping -- **Context7** - Up-to-date library documentation -- **PostgreSQL** - Database queries and schema inspection -- **GitHub** - Repository management and code search -- **Brave Search** - Real-time web search capabilities +- **Filesystem** - 訪問本地文件和目錄 +- **Playwright** - 瀏覽器自動化和網頁抓取 +- **Context7** - 最新的庫文檔 +- **PostgreSQL** - 數據庫查詢和模式檢查 +- **GitHub** - 倉庫管理和代碼搜索 +- **Brave Search** - 實時網頁搜索功能 -## Why MCP Matters for AI Coding +## 為什麼 MCP 對 AI 編碼很重要 -Before MCP, AI coding assistants were essentially blind to your development environment. They could generate code based on training data, but couldn't access your actual project structure, read your configuration files, or interact with your development tools. +在 MCP 之前，AI 編碼助手本質上對你的開發環境是盲目的。它們可以基於訓練數據生成代碼，但無法訪問你的實際項目結構、讀取配置文件或與開發工具交互。 -MCP changes this fundamentally. With MCP servers, your AI agent can: +MCP 從根本上改變了這一點。有了 MCP 伺服器，你的 AI Agent 可以： -- Understand your entire codebase structure through filesystem access -- Look up current documentation for libraries you're using -- Execute database queries to understand your data model -- Search the web for the latest solutions to your specific problem -- Interact with your Git repository to understand commit history +- 通過文件系統訪問理解整個代碼庫結構 +- 查找你正在使用的庫的最新文檔 +- 執行數據庫查詢以理解你的數據模型 +- 在網上搜索針對你具體問題的最新解決方案 +- 與你的 Git 倉庫交互以理解提交歷史 -## Getting Started with MCP +## MCP 入門 -Most modern AI coding tools now support MCP. Setting up your first MCP server typically involves: +大多數現代 AI 編碼工具現在都支持 MCP。設置你的第一個 MCP 伺服器通常包括： -### 1. Choose an MCP Server +### 1. 選擇 MCP 伺服器 -Start with something simple like the filesystem or web search MCP server. +從簡單的東西開始，如文件系統或網頁搜索 MCP 伺服器。 -### 2. Install the Server +### 2. 安裝伺服器 -Most MCP servers are distributed as npm packages or Python modules. Follow the installation instructions for your chosen server. +大多數 MCP 伺服器以 npm 包或 Python 模塊分發。按照你選擇的伺服器的安裝說明操作。 -### 3. Configure Your IDE +### 3. 配置你的 IDE -Add the MCP server configuration to your IDE's settings. The exact format varies by tool, but typically involves specifying the server's command and any required arguments. +將 MCP 伺服器配置添加到 IDE 的設置中。確切的格式因工具而異，但通常涉及指定伺服器的命令和任何必需的參數。 -Here's an example configuration for Claude Code: +以下是 Claude Code 的配置示例： ```json { @@ -87,14 +87,14 @@ Here's an example configuration for Claude Code: } ``` -### 4. Test the Integration +### 4. 測試集成 -Ask your AI agent to use the newly connected tools. For example, if you installed a filesystem MCP, try asking it to read a specific file from your project. +讓你的 AI Agent 使用新連接的工具。例如，如果你安裝了文件系統 MCP，嘗試讓它從你的項目中讀取特定文件。 -## The Future of MCP +## MCP 的未來 -The MCP ecosystem is still in its early stages, but the potential is enormous. As more developers build MCP servers for specialized tools and services, AI agents will become increasingly powerful and context-aware. +MCP 生態系統仍處於早期階段，但潛力巨大。隨著更多開發者為專門的工具和服務構建 MCP 伺服器，AI Agent將變得越來越強大和上下文感知。 -We're moving toward a future where your AI coding assistant has seamless access to every tool in your development workflow—from your IDE to your cloud infrastructure. MCP is the protocol that makes this vision possible. +我們正在走向這樣一個未來：你的 AI 編碼助手可以無縫訪問開發工作流中的每個工具——從 IDE 到雲基礎設施。MCP 是使這一願景成為可能協議。 -Explore the full catalog of available MCP servers in our [MCP Servers directory](/ai-coding-stack/mcp-servers) to find the right integrations for your workflow. +在我們的 [MCP 伺服器目錄](/ai-coding-stack/mcp-servers) 中探索可用 MCP 伺服器的完整目錄，為你的工作流找到合適的集成。 diff --git a/content/docs/de/getting-started.mdx b/content/docs/de/getting-started.mdx index 9196d23..defeffc 100644 --- a/content/docs/de/getting-started.mdx +++ b/content/docs/de/getting-started.mdx @@ -1,19 +1,19 @@ --- -title: 'Erste Schritte' +title: "Erste Schritte" --- # Erste Schritte -AI Coding Stack ist ein umfassendes Verzeichnis und Metadaten-Repository für das KI-Coding-Ökosystem. Dieser Leitfaden hilft Ihnen zu verstehen, wie Sie die Website nutzen und zum Projekt beitragen können. +AI Coding Stack ist ein umfassendes Verzeichnis und Metadaten-Repository für das AI-Coding-Ökosystem. Dieser Leitfaden hilft Ihnen zu verstehen, wie Sie die Website nutzen und zum Projekt beitragen können. ## Den Stack Erkunden ### Kategorien Durchsuchen -Besuchen Sie [aicodingstack.io](https://aicodingstack.io), um verschiedene Kategorien von KI-Coding-Tools zu erkunden: +Besuchen Sie [aicodingstack.io](https://aicodingstack.io), um verschiedene Kategorien von AI-Coding-Tools zu erkunden: -- **IDEs** - Finden Sie KI-gestützte integrierte Entwicklungsumgebungen (VS Code, Cursor, TRAE) -- **CLIs** - Erkunden Sie Kommandozeilen-KI-Coding-Assistenten (Codex, Claude Code) +- **IDEs** - Finden Sie AI-gestützte integrierte Entwicklungsumgebungen (VS Code, Cursor, TRAE) +- **CLIs** - Erkunden Sie Kommandozeilen-AI-Coding-Assistenten (Codex, Claude Code) - **Modelle** - Vergleichen Sie große Sprachmodelle für Coding (Kimi K2, DeepSeek V3.1, GLM 4.5, Qwen3 Coder) - **Anbieter** - Überprüfen Sie LLM-API-Anbieter (DeepSeek, Moonshot, SiliconFlow, OpenRouter) diff --git a/content/docs/de/welcome.mdx b/content/docs/de/welcome.mdx index 1318b32..348c502 100644 --- a/content/docs/de/welcome.mdx +++ b/content/docs/de/welcome.mdx @@ -1,24 +1,24 @@ --- -title: 'Willkommen' +title: "Willkommen" --- # Willkommen -Willkommen zur AI Coding Stack Dokumentation. AI Coding Stack ist ein umfassendes Verzeichnis und Metadaten-Repository für das KI-Coding-Ökosystem. +Willkommen zur AI Coding Stack Dokumentation. AI Coding Stack ist ein umfassendes Verzeichnis und Metadaten-Repository für das AI-Coding-Ökosystem. ## Was ist AI Coding Stack? AI Coding Stack dient zwei Hauptzwecken: -1. **Eine öffentliche Website** unter [aicodingstack.io](https://aicodingstack.io) zum Entdecken und Vergleichen von KI-Coding-Tools +1. **Eine öffentliche Website** unter [aicodingstack.io](https://aicodingstack.io) zum Entdecken und Vergleichen von AI-Coding-Tools 2. **Ein von der Community gepflegtes Metadaten-Repository** mit kuratierten Informationen über Coding-Tools, Modelle und Plattformen ## Hauptfunktionen ### Umfassende Abdeckung -Erkunden Sie eine breite Palette von KI-Coding-Tools in mehreren Kategorien: -- **IDEs** - Integrierte Entwicklungsumgebungen mit KI-Integration -- **CLIs** - Kommandozeilen-KI-Coding-Assistenten +Erkunden Sie eine breite Palette von AI-Coding-Tools in mehreren Kategorien: +- **IDEs** - Integrierte Entwicklungsumgebungen mit AI-Integration +- **CLIs** - Kommandozeilen-AI-Coding-Assistenten - **Modelle** - Große Sprachmodelle optimiert für Coding-Aufgaben - **Anbieter** - LLM-API-Anbieter und Plattformen @@ -26,7 +26,7 @@ Erkunden Sie eine breite Palette von KI-Coding-Tools in mehreren Kategorien: Alle Metadaten werden in JSON-Manifest-Dateien gepflegt, sodass die Community einfach Informationen über verschiedene Tools beitragen, aktualisieren und verbessern kann. ### Einfache Entdeckung -Durchsuchen, vergleichen und entdecken Sie die richtigen KI-Coding-Tools für Ihren Workflow über unsere intuitive Website-Oberfläche. +Durchsuchen, vergleichen und entdecken Sie die richtigen AI-Coding-Tools für Ihren Workflow über unsere intuitive Website-Oberfläche. ## Erste Schritte @@ -56,4 +56,4 @@ Wenn Sie Fragen haben oder Unterstützung benötigen: ## Beitragen -AI Coding Stack ist Open Source und Community-gesteuert. Wir freuen uns über Beiträge zu unserem Metadaten-Repository und unserer Dokumentation. Helfen Sie uns, das umfassendste Verzeichnis von KI-Coding-Tools aufzubauen! +AI Coding Stack ist Open Source und Community-gesteuert. Wir freuen uns über Beiträge zu unserem Metadaten-Repository und unserer Dokumentation. Helfen Sie uns, das umfassendste Verzeichnis von AI-Coding-Tools aufzubauen! diff --git a/content/docs/en/getting-started.mdx b/content/docs/en/getting-started.mdx index a18f856..7fc8bed 100644 --- a/content/docs/en/getting-started.mdx +++ b/content/docs/en/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: 'Getting Started' +title: "Getting Started" --- # Getting Started diff --git a/content/docs/en/welcome.mdx b/content/docs/en/welcome.mdx index 7fc36d2..b4f28a7 100644 --- a/content/docs/en/welcome.mdx +++ b/content/docs/en/welcome.mdx @@ -1,5 +1,5 @@ --- -title: 'Welcome' +title: "Welcome" --- # Welcome diff --git a/content/docs/es/getting-started.mdx b/content/docs/es/getting-started.mdx index f55afe5..c944da9 100644 --- a/content/docs/es/getting-started.mdx +++ b/content/docs/es/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: 'Primeros Pasos' +title: "Primeros Pasos" --- # Primeros Pasos diff --git a/content/docs/es/welcome.mdx b/content/docs/es/welcome.mdx index 7635bf3..0be7e10 100644 --- a/content/docs/es/welcome.mdx +++ b/content/docs/es/welcome.mdx @@ -1,5 +1,5 @@ --- -title: 'Bienvenido' +title: "Bienvenido" --- # Bienvenido diff --git a/content/docs/fr/getting-started.mdx b/content/docs/fr/getting-started.mdx index 7640475..e3e4f51 100644 --- a/content/docs/fr/getting-started.mdx +++ b/content/docs/fr/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: 'Premiers Pas' +title: "Premiers Pas" --- # Premiers Pas diff --git a/content/docs/fr/welcome.mdx b/content/docs/fr/welcome.mdx index acb6b8a..0df7412 100644 --- a/content/docs/fr/welcome.mdx +++ b/content/docs/fr/welcome.mdx @@ -1,5 +1,5 @@ --- -title: 'Bienvenue' +title: "Bienvenue" --- # Bienvenue diff --git a/content/docs/id/getting-started.mdx b/content/docs/id/getting-started.mdx index 6b7c8fd..b289ded 100644 --- a/content/docs/id/getting-started.mdx +++ b/content/docs/id/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: 'Memulai' +title: "Memulai" --- # Memulai diff --git a/content/docs/id/welcome.mdx b/content/docs/id/welcome.mdx index dede076..e053ee7 100644 --- a/content/docs/id/welcome.mdx +++ b/content/docs/id/welcome.mdx @@ -1,5 +1,5 @@ --- -title: 'Selamat Datang' +title: "Selamat Datang" --- # Selamat Datang diff --git a/content/docs/ja/getting-started.mdx b/content/docs/ja/getting-started.mdx index 001e273..25f867d 100644 --- a/content/docs/ja/getting-started.mdx +++ b/content/docs/ja/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: 'はじめに' +title: "はじめに" --- # はじめに diff --git a/content/docs/ja/welcome.mdx b/content/docs/ja/welcome.mdx index 326d09e..0146c9f 100644 --- a/content/docs/ja/welcome.mdx +++ b/content/docs/ja/welcome.mdx @@ -1,5 +1,5 @@ --- -title: 'ようこそ' +title: "ようこそ" --- # ようこそ diff --git a/content/docs/ko/getting-started.mdx b/content/docs/ko/getting-started.mdx index 884fa2d..e9db239 100644 --- a/content/docs/ko/getting-started.mdx +++ b/content/docs/ko/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: '시작하기' +title: "시작하기" --- # 시작하기 diff --git a/content/docs/ko/welcome.mdx b/content/docs/ko/welcome.mdx index 0829490..ca2c7a0 100644 --- a/content/docs/ko/welcome.mdx +++ b/content/docs/ko/welcome.mdx @@ -1,5 +1,5 @@ --- -title: '환영합니다' +title: "환영합니다" --- # 환영합니다 diff --git a/content/docs/pt/getting-started.mdx b/content/docs/pt/getting-started.mdx index 7c8b9d5..0f341a1 100644 --- a/content/docs/pt/getting-started.mdx +++ b/content/docs/pt/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: 'Como Começar' +title: "Como Começar" --- # Como Começar diff --git a/content/docs/pt/welcome.mdx b/content/docs/pt/welcome.mdx index 12247cb..fe10091 100644 --- a/content/docs/pt/welcome.mdx +++ b/content/docs/pt/welcome.mdx @@ -1,5 +1,5 @@ --- -title: 'Bem-vindo' +title: "Bem-vindo" --- # Bem-vindo diff --git a/content/docs/ru/getting-started.mdx b/content/docs/ru/getting-started.mdx index d0593de..63684a9 100644 --- a/content/docs/ru/getting-started.mdx +++ b/content/docs/ru/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: 'Начало работы' +title: "Начало работы" --- # Начало работы diff --git a/content/docs/ru/welcome.mdx b/content/docs/ru/welcome.mdx index ea31a4c..29c3c37 100644 --- a/content/docs/ru/welcome.mdx +++ b/content/docs/ru/welcome.mdx @@ -1,5 +1,5 @@ --- -title: 'Добро пожаловать' +title: "Добро пожаловать" --- # Добро пожаловать diff --git a/content/docs/tr/getting-started.mdx b/content/docs/tr/getting-started.mdx index cd36478..5555a75 100644 --- a/content/docs/tr/getting-started.mdx +++ b/content/docs/tr/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: 'Başlarken' +title: "Başlarken" --- # Başlarken diff --git a/content/docs/tr/welcome.mdx b/content/docs/tr/welcome.mdx index ae409fb..b2c1469 100644 --- a/content/docs/tr/welcome.mdx +++ b/content/docs/tr/welcome.mdx @@ -1,5 +1,5 @@ --- -title: 'Hoş Geldiniz' +title: "Hoş Geldiniz" --- # Hoş Geldiniz @@ -30,7 +30,7 @@ Tüm meta veriler JSON manifest dosyalarında tutulur, bu da topluluğun çeşit ## Başlarken -AI Coding Stack'e yeni misiniz? Ekosistem如何 keşf edeceğinizi ve projeye katkıda bulunacağınızı öğrenmek için [Başlarken](/docs/getting-started) kılavuzumuza göz atın. +AI Coding Stack'e yeni misiniz? Ekosistemi nasıl keşf edeceğinizi ve projeye katkıda bulunacağınızı öğrenmek için [Başlarken](/docs/getting-started) kılavuzumuza göz atın. ## Belge Bölümleri diff --git a/content/docs/zh-Hans/getting-started.mdx b/content/docs/zh-Hans/getting-started.mdx index 87ad07c..90fb2a5 100644 --- a/content/docs/zh-Hans/getting-started.mdx +++ b/content/docs/zh-Hans/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: '快速入门' +title: "快速入门" --- # 快速入门 diff --git a/content/docs/zh-Hans/welcome.mdx b/content/docs/zh-Hans/welcome.mdx index 85f518f..94fc7f5 100644 --- a/content/docs/zh-Hans/welcome.mdx +++ b/content/docs/zh-Hans/welcome.mdx @@ -1,5 +1,5 @@ --- -title: '欢迎' +title: "欢迎" --- # 欢迎 diff --git a/content/docs/zh-Hant/getting-started.mdx b/content/docs/zh-Hant/getting-started.mdx index 0076df5..2b5217a 100644 --- a/content/docs/zh-Hant/getting-started.mdx +++ b/content/docs/zh-Hant/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: '快速開始' +title: "快速開始" --- # 快速開始 diff --git a/content/docs/zh-Hant/welcome.mdx b/content/docs/zh-Hant/welcome.mdx index a84d695..4e608bf 100644 --- a/content/docs/zh-Hant/welcome.mdx +++ b/content/docs/zh-Hant/welcome.mdx @@ -1,5 +1,5 @@ --- -title: '歡迎' +title: "歡迎" --- # 歡迎 diff --git a/content/faq/de/index.mdx b/content/faq/de/index.mdx index 39c2f5f..8aa994b 100644 --- a/content/faq/de/index.mdx +++ b/content/faq/de/index.mdx @@ -1,6 +1,6 @@ # Was ist AI Coding Stack und wie hilft es Entwicklern? -AI Coding Stack ist ein umfassendes Verzeichnis und Metadaten-Repository für das KI-Coding-Ökosystem. Es bietet eine zentrale Plattform zum Entdecken, Vergleichen und Erkunden KI-gestützter Entwicklungstools, einschließlich IDEs wie VS Code und Cursor, Kommandozeilen-Assistenten wie Claude Code, LLM-Modelle und API-Anbieter. Anstatt über verstreute Ressourcen zu suchen, bietet Ihnen AI Coding Stack detaillierte Spezifikationen, Preise und Funktionsvergleiche alles an einem Ort. +AI Coding Stack ist ein umfassendes Verzeichnis und Metadaten-Repository für das AI-Coding-Ökosystem. Es bietet eine zentrale Plattform zum Entdecken, Vergleichen und Erkunden AI-gestützter Entwicklungstools, einschließlich IDEs wie VS Code und Cursor, Kommandozeilen-Assistenten wie Claude Code, LLM-Modelle und API-Anbieter. Anstatt über verstreute Ressourcen zu suchen, bietet Ihnen AI Coding Stack detaillierte Spezifikationen, Preise und Funktionsvergleiche alles an einem Ort. # Wie verwende ich AI Coding Stack? @@ -13,14 +13,14 @@ AI Coding Stack ist ein webbasiertes Verzeichnis, das Sie direkt unter aicodings Die Plattform wird kontinuierlich mit neuen Tools und Informationen aktualisiert, sobald diese verfügbar werden. -# Welche KI-Coding-Tools und LLM-Anbieter sind in AI Coding Stack aufgeführt? +# Welche AI-Coding-Tools und LLM-Anbieter sind in AI Coding Stack aufgeführt? -AI Coding Stack bietet einen umfassenden Katalog von KI-Coding-Tools und -Diensten: +AI Coding Stack bietet einen umfassenden Katalog von AI-Coding-Tools und -Diensten: -- **IDEs**: Visual Studio Code, Cursor, TRAE und andere KI-verbesserte Code-Editoren -- **CLIs**: Claude Code, Codex und andere Kommandozeilen-KI-Assistenten -- **Erweiterungen**: GitHub Copilot, Cline, Continue, Roo Code und andere KI-Code-Assistent-Plugins -- **Modelle**: DeepSeek, Kimi K2, GLM, Qwen, GPT, Claude und andere führende KI-Modelle +- **IDEs**: Visual Studio Code, Cursor, TRAE und andere AI-verbesserte Code-Editoren +- **CLIs**: Claude Code, Codex und andere Kommandozeilen-AI-Assistenten +- **Erweiterungen**: GitHub Copilot, Cline, Continue, Roo Code und andere AI-Code-Assistent-Plugins +- **Modelle**: DeepSeek, Kimi K2, GLM, Qwen, GPT, Claude und andere führende AI-Modelle - **Anbieter**: OpenAI, Anthropic, DeepSeek, Moonshot, OpenRouter, SiliconFlow und mehr Das Verzeichnis wird kontinuierlich aktualisiert, wenn neue Tools und Anbieter auftauchen. @@ -35,7 +35,7 @@ Ja, AI Coding Stack ist vollständig Open Source und unter der Apache 2.0 Lizenz - Dokumentation und Leitfäden verbessern - Pull-Requests einreichen -Besuchen Sie das [GitHub-Repository](https://github.com/aicodingstack/aicodingstack.io), um mit dem Beitragen zum KI-Coding-Ökosystem zu beginnen. +Besuchen Sie das [GitHub-Repository](https://github.com/aicodingstack/aicodingstack.io), um mit dem Beitragen zum AI-Coding-Ökosystem zu beginnen. # Wie hilft mir AI Coding Stack bei der Auswahl der richtigen Tools? diff --git a/content/manifesto/de/index.mdx b/content/manifesto/de/index.mdx index a3d6a72..2d973d1 100644 --- a/content/manifesto/de/index.mdx +++ b/content/manifesto/de/index.mdx @@ -2,7 +2,7 @@ Der AI Coding Stack stellt einen grundlegenden Wandel in der Art und Weise dar, wie wir Software entwickeln. Er definiert ein neues Paradigma, bei dem künstliche Intelligenz tief in jeden Aspekt des Entwicklungsworkflows integriert ist und ein zusammenhängendes Ökosystem schafft, das die Produktivität von Entwicklern verstärkt. -Im Kern ist der AI Coding Stack ein einheitliches Ökosystem wesentlicher Komponenten, die zusammenarbeiten, um eine nahtlose, intelligente Entwicklungserfahrung zu schaffen. **IDEs**, **CLIs**, **Erweiterungen** und **Modelle** bilden das Fundament moderner KI-gestützter Programmierung, wobei jede einen eigenen Zweck erfüllt und dennoch harmonisch zusammenarbeitet. +Im Kern ist der AI Coding Stack ein einheitliches Ökosystem wesentlicher Komponenten, die zusammenarbeiten, um eine nahtlose, intelligente Entwicklungserfahrung zu schaffen. **IDEs**, **CLIs**, **Erweiterungen** und **Modelle** bilden das Fundament moderner AI-gestützter Programmierung, wobei jede einen eigenen Zweck erfüllt und dennoch harmonisch zusammenarbeitet. **IDEs** wie Cursor und VS Code bieten die visuelle Schnittstelle, in der Code zum Leben erweckt wird, mit intelligenter Autovervollständigung, Code-Generierung und kontextbezogener Unterstützung. **Erweiterungen** verleihen diesen Editoren KI-gestützte Fähigkeiten – von fortgeschrittener Code-Vervollständigung und intelligentem Refactoring bis hin zu spezialisierter Sprachunterstützung und Produktivitäts-Tools. **CLIs** wie Claude Code bringen KI-Fähigkeiten direkt in Ihre Kommandozeile und ermöglichen natürlichsprachliche Interaktionen mit Ihrer Codebasis. @@ -10,4 +10,4 @@ Im Kern ist der AI Coding Stack ein einheitliches Ökosystem wesentlicher Kompon Die Kraft des AI Coding Stack liegt nicht in einem einzelnen Tool, sondern darin, wie diese Komponenten integriert sind. Wenn Ihre IDE Ihren Codebasis-Kontext versteht, wenn Ihr CLI dieselben Modelle wie Ihr Editor nutzt und wenn Ihr Terminal intelligent Befehle basierend auf Ihrem Workflow vorschlägt – dann entsteht wahre Produktivität. -Die Zukunft des Codings ist nicht nur KI-gestützt – sie ist KI-orchestriert. Willkommen beim AI Coding Stack. +Die Zukunft des Codings ist nicht nur AI-gestützt – sie ist AI-orchestriert. Willkommen beim AI Coding Stack. diff --git a/content/manifesto/pt/index.mdx b/content/manifesto/pt/index.mdx index 46d4263..fe37248 100644 --- a/content/manifesto/pt/index.mdx +++ b/content/manifesto/pt/index.mdx @@ -8,6 +8,6 @@ No seu núcleo, AI Coding Stack é um ecossistema unificado de componentes essen **Modelos** incluindo DeepSeek, Kimi, Claude e GPT alimentam a inteligência por trás de cada sugestão, geração de código e análise, fornecendo o tecido conectivo que torna toda a sua stack verdadeiramente inteligente. -O poder de AI Coding Stack não reside em nenhuma ferramenta individual, mas em como estes componentes se integram. Quando seu IDE entende o contexto da sua base de código, quando sua CLI utiliza os mesmos modelos do seu editor, e quando seu terminal sugere inteligentemente comandos baseados no seu fluxo de trabalho—é quando a verdadeira produtividade emerge. +O poder de AI Coding Stack não reside em nenhuma ferramenta individual, mas em como estes componentes se integram. Quando seu IDE compreende o contexto da sua base de código, quando sua CLI utiliza os mesmos modelos do seu editor, e quando seu terminal sugere inteligentemente comandos baseados no seu fluxo de trabalho—é quando a verdadeira produtividade emerge. O futuro da codificação não é apenas assistida por IA—é orquestrada por IA. Bem-vindo ao AI Coding Stack. diff --git a/cspell.json b/cspell.json index 26a75b4..1240973 100644 --- a/cspell.json +++ b/cspell.json @@ -48,108 +48,97 @@ "useGitignore": true, "ignorePaths": ["cloudflare-env.d.ts", "docs", ".claude"], "words": [ + "API'lerle", "Anthropics", + "BYOK", "Benefíciate", - "bienvene", - "berechtigungsbasierter", "BMAD", - "BYOK", - "Coden", - "Codierungsaufgaben", - "Codierungsbenchmarks", - "Codierungsmodell", - "fortschrittlichestes", - "Funktionsaufrufung", - "gtag", - "görselleştirin", - "hochkapazitatives", - "Intinya", - "Maks", - "Multimodal", - "Optimierung", - "orkestr", - "Porcentagem", - "Sugeriendo", - "RAG", - "refactorización", - "refactorieren", - "refatoração", - "Refatoração", - "Spesifikasyon", - "Spesifikasyonlar", - "spesifikasyonlar", - "spesifikasyonları", - "spesifikasyonlarını", - "TTFB", - "Türkçe", - "Vervollständigungstool", - "yığınınızı", - "Бенчмарки", - "Мультимодальное", - "мультимодальные", - "İndir", - "İzleme", - "İNDEKS", - "agentic", - "agentischer", - "AiCodingStack", + "CI'nizde", "CLIs", "CLI'lere", - "cmdk", + "Coden", + "CODE", "Codierungs", "Codierungsassistent", "Codierungsassistenz", + "Codierungsbenchmarks", + "Codierungsmodell", "Codierungsplattform", + "Codierungsproduktivität", + "Codierungsreise", "Codierungsunterstützung", - "deepv", - "dvcode", + "Codierungsaufgaben", + "Codierungsmodelle", + "Droid'larını", + "Droid'ları", "Entwicklungsworkflows", - "hrefs", + "Entwicklungsworkflow", + "Experitez", + "Funktionsaufrufung", + "Granüler", + "IDE'nize", + "IDE'nizi", + "IDE'nizden", "IDE'lere", "IDE'lerin", + "İnşa", + "İsme", + "İster", + "İstemler", + "İşte", + "İçin", + "İşlem", + "İndir", + "İzleme", + "İNDEKS", + "İnsanlar", "Integrationen", "Junie", - "Kuaishou", "Kimi", "Kiro", "Kode", + "komutlari", + "kullaniminda", + "Kuik", "MMMU", - "mmmu", - "Neovate", + "Maks", + "Mengkonversi", + "mengorkestrasi", + "Moonshot", + "moonshotai", + "Optimierung", + "Optimizasyonlar", + "Porcentagem", "Pulumi", "Qoder", - "QoderCLI", "Qwen", + "qwen", + "qoder", + "qodercli", "Roo", - "shareAI", - "TRAE", - "linkedin", - "Видеоклауд", - "Сообщественная", - "агентачный", - "агентного", - "агентные", - "агентным", - "агентными", - "интеллекцию", - "инференса", - "кодерского", - "мульти", - "мультимодальная", - "мультимодальным", - "мультимодальных", - "настр", - "настраивае", - "оркестрирует", - "пания", - "помошник", - "фронтенд", + "Sıganos", + "Síganos", + "Sugeriendo", + "TTFB", + "Tasarlanmisitir", + "Tasarlanmistir", + "tasarlandi", + "Türkçe", + "Vervollständigungstool", + "agentco", + "agentico", + "agentischer", "agenticen", "ajent", + "aiCodingStack", + "ajant", + "ajanına", + "ajanınıza", "akislari", "akislarindaki", "akislarini", "akislarni", + "ajan", "alaninda", "anlayisi", "aracilar", @@ -162,65 +151,128 @@ "autônomo", "autônomos", "ayiklama", + "berechtigungsbasierter", "berbayar", + "bienvene", "cagirme", + "cagirme", + "calistiran", + "calistirin", + "cagirma", "calistiran", "calistirin", "canli", - "CI'nizde", + "cmdk", "construíndo", "customizaveis", "d'intelligenc", + "débogent", + "deepv", "demokratizasyonunu", "desteg", "detayli", "didesain", - "Droid'ları", - "Experitez", - "Granüler", + "dvcode", + "etkileşemezlerdi", + "fortschrittlichestes", + "gtag", + "görselleştirin", "hatalari", "hizlandiran", "hizli", + "hochkapazitatives", "hook'larını", - "IDE'nize", - "İnsanlar", - "karmaik", - "komutlari", + "hrefs", + "Intinya", + "Kwai", + "Kwais", + "Kwai'nin", + "Kuaishou", + "kuaikatonai", "kullanin", "kullanir", "kurallarinizi", - "Mengkonversi", - "mengorkestrasi", + "kapsamli", + "karmaik", + "kwaikatonai", + "kwaikatonai", + "Kwaikatonai", + "laboratuvari", + "linkedin", + "mengdebug", + "menginstal", "modalli", "modlu", "modu", "Modları", + "multilíngue", + "orkestr", + "мультимодальный", "odakli", "optimizasyon", "orkestrasyonu", "orkestre", "pengkodean", "pengodean", + "potensinya", "privibilidade", "programcıdır", "projectos", + "Промпты", + "RAG", + "refactorieren", "refactorisation", "Refactorisent", + "refactorización", "Refactorizan", + "Refatoração", "Refatoram", "saglayicinin", "saglayicisiyla", "satci", + "shareAI", "specialisée", + "spesifikasyon", + "Spesifikasyonlar", + "spesifikasyonlar", + "spesifikasyonları", + "spesifikasyonlarını", "tabanli", - "tasarlanmisitir", - "tasarlanmistir", "teknologların", "yanitlar", "yardimci", "yardimcisidir", + "yazin", "yayin", - "yazin" + "yığınınızı", + "yığınınızı", + "Бенчмарки", + "Мультимодальное", + "Мультимодальный", + "мульти", + "мультимодальная", + "мультимодальным", + "мультимодальных", + "мультимодальные", + "Видеоклауд", + "агентачный", + "агентная", + "агентного", + "агентные", + "агентным", + "агентные", + "агентными", + "агентной", + "интеллекцию", + "инференса", + "кодерского", + "настр", + "настраивае", + "оркестрирует", + "пания", + "помошник", + "сообщественная", + "фронтенд" ], "allowCompoundWords": true } diff --git a/data/github-stars.json b/data/github-stars.json index 5d832c5..ac9883a 100644 --- a/data/github-stars.json +++ b/data/github-stars.json @@ -55,6 +55,7 @@ }, "models": { "composer": null, + "deepseek-3-2": null, "glm-4-6v": null } } diff --git a/docs/COMPONENT-RELATIONSHIP-DIAGRAM.md b/docs/COMPONENT-RELATIONSHIP-DIAGRAM.md index cc0888c..725ff83 100644 --- a/docs/COMPONENT-RELATIONSHIP-DIAGRAM.md +++ b/docs/COMPONENT-RELATIONSHIP-DIAGRAM.md @@ -1,249 +1,504 @@ -# Component & Layout Relationship Diagram +# AI Coding Stack - Component & Architecture Diagram -This document outlines the simplified structure and relationships between layouts and components in the AI Coding Stack project. +**Last Updated:** January 6, 2026 -## Design Principles +This document provides a comprehensive overview of the AI Coding Stack project architecture, component relationships, and data flow. -1. **Minimal Nesting** - Only 2 layouts total: RootLayout (app/) and PageLayout -2. **Inline Over Abstraction** - Pages compose components directly instead of using specialized layouts -3. **DRY** - Components are reused across pages, layouts are not nested +--- + +## High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────────────────────────────┐ +│ AI CODING STACK ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ MANIFESTS/ │────▶│ GENERATORS/ │────▶│ GENERATED/ │ │ +│ │ (Data Source) │ │ (Build Tools) │ │ (Typed Output) │ │ +│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ +│ │ │ │ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌──────────────────────────────────────────────────────────────────────────┐ │ +│ │ src/lib/ │ │ +│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ manifest- │ │ metadata/ │ │ i18n/ │ │ landscape- │ │ │ +│ │ │ registry.ts │ │ (schemas) │ │ (locales) │ │ data.ts │ │ │ +│ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │ +│ └──────────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────────────────────────────┐ │ +│ │ src/app/[locale]/ │ │ +│ │ ┌─────────────┐ ┌────────────────────┐ ┌─────────────────────┐ │ │ +│ │ │ layout.tsx │▶ │ Pages (Routing) │ │ opengraph-image.* │ │ │ +│ │ │ (Root) │ │ - ides/ │ │ (Social Images) │ │ │ +│ │ └─────────────┘ │ - clis/ │ └─────────────────────┘ │ │ +│ │ │ - models/ │ │ +│ │ │ - extensions/ │ │ +│ │ │ - articles/ │ │ +│ │ │ - docs/ │ │ +│ │ └────────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────────────────────────────┐ │ +│ │ src/components/ │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ +│ │ │ Layout │ │ Product │ │ Controls │ │ Navigation│ │ Sidebar etc │ │ │ +│ │ │ Layer │ │ Layer │ │ Layer │ │ Layer │ │ │ │ │ +│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │ │ +│ └──────────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────────┘ +``` --- -## Structure +## Directory Structure + +### Root Level +``` +aicodingstack.io/ +├── .claude/ # Claude Code skills and settings +├── .github/ # GitHub: workflows, templates, CODEOWNERS, dependabot +├── docs/ # Project documentation +├── manifests/ # Core data: JSON manifest files + schemas +├── public/ # Static assets +├── scripts/ # Build/fetch/generate scripts +├── skills/ # Claude Code skills +├── src/ # Application source code +└── [config files] # package.json, next.config.* tsconfig.json, etc. +``` + +### manifests/ (Data Source) +``` +manifests/ +├── $schemas/ # JSON Schema definitions for validation +│ ├── ides.schema.json +│ ├── clis.schema.json +│ ├── extensions.schema.json +│ ├── models.schema.json +│ ├── providers.schema.json +│ ├── vendors.schema.json +│ └── github-stars.schema.json +├── ides/*.jsonc # IDE manifest files +├── clis/*.jsonc # CLI manifest files +├── extensions/*.jsonc # Extension manifest files +├── models/*.jsonc # Model manifest files +├── providers/*.jsonc # Provider manifest files +├── vendors/*.jsonc # Vendor manifest files +└── github-stars.json # Centralized star counts +``` + +### scripts/ (Build Tools) +``` +scripts/ +├── fetch/ # Data fetching scripts +│ ├── fetch-github-stars.mjs +│ └── index.mjs +├── generate/ # Code generation scripts +│ ├── generate-i18n.mjs +│ ├── generate-manifests.mjs +│ └── index.mjs +├── refactor/ # Refactoring utilities +└── _shared/ # Shared utilities for scripts +``` +### .github/workflows/ (CI/CD) +``` +.github/workflows/ +├── ci.yml # Main CI checks (lint, type-check, build, test) +├── deploy-preview.yml # Preview deployments from PRs +├── deploy-staging.yml # Staging environment +├── deploy-production.yml # Production deployment +├── scheduled-checks.yml # URL validation, benchmark updates +├── update-github-stars.yml # Scheduled GitHub stars fetch +├── stale.yml # Stale issue/PR management +├── cleanup-preview.yml # Preview cleanup +└── dependabot-auto-merge.yml +``` + +### src/ (Application Source) ``` src/ -├── app/[locale]/layout.tsx [RootLayout - Next.js root layout] -│ -├── layouts/ -│ └── PageLayout.tsx [Only layout - Header + Footer + optional schema] -│ -└── components/ - ├── Header.tsx [Site header with navigation] - ├── Footer.tsx [Site footer] - ├── JsonLd.tsx [Schema.org structured data] - ├── ThemeProvider.tsx [Theme context provider] - ├── ClientLayout.tsx [Client-side wrapper for interactivity] - │ - ├── product/ [Product-related components] - │ ├── ProductHero.tsx [Product header info] - │ ├── ProductPricing.tsx [Pricing section] - │ ├── ResourceLinks.tsx [Resource links (download, changelog, pricing, mcp, issue)] - │ ├── CommunityLinks.tsx [Community links (linkedin, twitter, github, youtube, discord, reddit, blog)] - │ ├── ProductCommands.tsx[Install/launch commands] - │ ├── RelatedProducts.tsx[Related products grid] - │ ├── LinkCard.tsx [Link card component] - │ └── GitHubStarHistory.tsx [GitHub stars chart] - │ - ├── navigation/ [Navigation components] - │ ├── BackToNavigation.tsx ["Back to" link] - │ ├── Breadcrumb.tsx [Breadcrumb navigation] - │ ├── StackMegaMenu.tsx [AI Coding Stack mega menu] - │ ├── RankingMegaMenu.tsx[Ranking mega menu] - │ └── StackTabs.tsx [Stack category tabs] - │ - ├── controls/ [UI controls] - │ ├── CopyButton.tsx - │ ├── FilterSortBar.tsx - │ ├── LanguageSwitcher.tsx - │ ├── SearchDialog.tsx - │ ├── SearchInput.tsx - │ └── ThemeSwitcher.tsx - │ - ├── sidebar/ [Sidebar components] - │ ├── Sidebar.tsx [Main sidebar] - │ └── DocsSidebar.tsx [Documentation sidebar] - │ - ├── og/ [OpenGraph images] - │ └── OGImageTemplate.tsx - │ - └── [other components] - ├── ComparisonTable.tsx [Comparison data table] - ├── CollectionScrollbar.tsx [Horizontal scroll for collections] - ├── CollectionSection.tsx [Collection section wrapper] - ├── MarkdownContent.tsx [Markdown content renderer] - ├── MDXComponents.tsx [MDX component mappings] - ├── ModelBenchmarks.tsx [Model benchmark scores] - ├── ModelSpecifications.tsx [Model technical specs] - ├── PageHeader.tsx [Page header component] - ├── PlatformIcons.tsx [Platform icon display] - ├── PlatformLinks.tsx [Platform links (HuggingFace, etc.)] - ├── VendorModels.tsx [Vendor's models grid] - ├── VendorProducts.tsx [Vendor's products grid] - └── VerifiedBadge.tsx [Verified checkmark badge] +├── app/[locale]/ # Next.js App Router (i18n) +│ ├── layout.tsx # Root layout (i18n provider, Google Analytics) +│ ├── page.tsx # Homepage +│ ├── [routes]/ # All page routes +│ └── opengraph-image.tsx # OG images +├── components/ # React components +│ ├── controls/ # UI controls (search, filters, theme) +│ ├── navigation/ # Navigation components +│ ├── product/ # Product-specific components +│ ├── sidebar/ # Sidebar components +│ ├── og/ # OG image templates +│ └── [shared components] # PageHeader, JsonLd, etc. +├── i18n/ # Internationalization +│ ├── config.ts # Locale config +│ ├── navigation.ts # Localized Link component +│ └── locales/ # Translation files (en, zh-Hans, de, ko) +├── lib/ # Core library modules +│ ├── data/ # Data utilities +│ ├── generated/ # Auto-generated typed imports +│ ├── metadata/ # SEO metadata system +│ │ └── schemas/ # Schema.org builders +│ ├── manifest-i18n.ts # Manifest translation layer +│ ├── manifest-registry.ts# Manifest query system +│ ├── landscape-data.ts # Landscape page data +│ ├── search.ts # Search functionality +│ ├── collections.ts # Collections data +│ ├── benchmarks.ts # Benchmark data +│ ├── format.ts # Formatting utilities +│ ├── pricing.ts # Pricing utilities +│ └── license.tsx # License component +├── types/ # TypeScript type definitions +│ └── manifests.ts # Manifest types (mapped from schemas) +├── layouts/ # Layout components +│ └── PageLayout.tsx # Main page layout +└── middleware.ts # Next.js middleware (redirects, etc.) ``` --- -## Layout Structure - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ LAYOUT STRUCTURE │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ RootLayout (Next.js app/[locale]/layout.tsx) │ -│ ├── Provides: i18n, theme, basic HTML structure │ -│ └── NOT counted as a "layout" for this project │ -│ │ -│ PageLayout (src/layouts/PageLayout.tsx) │ -│ ├── Provides: JsonLd (optional), Header, Footer │ -│ └── Used by: ALL pages │ -│ │ -│ All pages use PageLayout and compose their own content: │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -│ │ -└─────────────────────────────────────────────────────────────────────────────┘ +## Core Systems + +### 1. Manifest System + +The manifest system is the core data layer: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ MANIFEST SYSTEM │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ manifests/*.jsonc (Source) │ +│ │ │ +│ ▼ │ +│ scripts/generate/generate-manifests.mjs │ +│ │ │ +│ ▼ │ +│ src/lib/generated/*.ts (Typed Access) │ +│ │ │ +│ ├──▶ src/lib/manifest-registry.ts (Query API) │ +│ │ │ +│ └──▶ src/lib/manifest-i18n.ts (Translation Layer) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ ``` ---- +**Key Files:** +- `src/lib/manifest-registry.ts` - Central manifest query system +- `src/lib/manifest-i18n.ts` - Translates manifest fields +- `src/types/manifests.ts` - TypeScript definitions (1:1 with schemas) +- `src/lib/generated/*.ts` - Auto-generated imports -## Page Usage Examples - -### IDE/CLI/Extension Detail Pages -```tsx - - - - - - - - - - -``` - -### Model Detail Pages -```tsx - - - - - - - - -``` - -### Vendor/Provider Detail Pages -```tsx - - - - - - - - - +### 2. i18n System + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ I18N SYSTEM │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ src/i18n/config.ts - Locale configuration │ +│ ├── defaultLocale: 'en' │ +│ └── locales: ['en', 'zh-Hans', 'de', 'ko'] │ +│ │ +│ src/i18n/navigation.ts - Localized Link component │ +│ │ +│ src/i18n/locales/*.json - Translation files │ +│ ├── en.json │ +│ ├── zh-Hans.json │ +│ ├── de.json │ +│ └── ko.json │ +│ │ +│ Usage: │ +│ import { Link } from '@/i18n/navigation' │ +│ import { useTranslations } from '@/i18n/navigation' │ +│ │ +└─────────────────────────────────────────────────────────────────┘ ``` ---- +### 3. Metadata & SEO System -## Component Dependencies - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ COMPONENT DEPENDENCIES │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ PageLayout │ -│ ├── JsonLd │ -│ ├── Header │ -│ │ ├── SearchDialog │ -│ │ ├── StackMegaMenu │ -│ │ ├── RankingMegaMenu │ -│ │ └── i18n Link │ -│ └── Footer │ -│ ├── LanguageSwitcher │ -│ └── ThemeSwitcher │ -│ │ -│ Pages compose components directly: │ -│ ├── Breadcrumb │ -│ ├── ProductHero │ -│ │ ├── VerifiedBadge │ -│ │ └── PlatformIcons │ -│ ├── RelatedProducts → LinkCard │ -│ ├── ProductPricing │ -│ ├── ResourceLinks → LinkCardGrid → LinkCard │ -│ ├── CommunityLinks → LinkCardGrid → LinkCard → PlatformIcons │ -│ ├── ProductCommands → CopyButton │ -│ ├── PlatformLinks → PlatformIcons │ -│ ├── ModelSpecifications │ -│ ├── ModelBenchmarks │ -│ ├── VendorProducts → LinkCard │ -│ ├── VendorModels → LinkCard │ -│ ├── BackToNavigation │ -│ ├── ComparisonTable │ -│ ├── CollectionScrollbar │ -│ ├── CollectionSection │ -│ ├── MarkdownContent │ -│ ├── MDXComponents │ -│ ├── PageHeader │ -│ ├── Sidebar │ -│ └── DocsSidebar │ -│ │ -└─────────────────────────────────────────────────────────────────────────────┘ +``` +┌─────────────────────────────────────────────────────────────────┐ +│ METADATA & SEO SYSTEM │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ src/lib/metadata/ │ +│ ├── config.ts - Site-wide SEO config │ +│ ├── generators.ts - Page-specific metadata generators │ +│ ├── helpers.ts - Helper functions (OG, Twitter) │ +│ ├── robots.ts - Robots configuration │ +│ ├── templates.ts - Base metadata templates │ +│ └── schemas/ - Schema.org structured data │ +│ ├── types.ts - Schema type definitions │ +│ ├── builders.ts - Schema builder functions │ +│ ├── generators.ts - Page-specific schema generators │ +│ └── validators.ts - Schema validation │ +│ │ +│ opengraph-image.tsx files - Route-specific OG images │ +│ │ +│ Schemas supported: │ +│ - Organization, WebSite, FAQPage │ +│ - SoftwareApplication (IDEs, CLIs, Extensions) │ +│ - Product, BreadcrumbList, Article, TechArticle │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 4. External Data Fetching + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ EXTERNAL DATA FETCHING │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Scripts for fetching external data: │ +│ │ +│ scripts/fetch/fetch-github-stars.mjs │ +│ ├── Fetches from GitHub API │ +│ └── Writes to manifests/github-stars.json │ +│ │ +│ Scheduled workflows: │ +│ .github/workflows/update-github-stars.yml (daily) │ +│ .github/workflows/scheduled-checks.yml (weekly) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ ``` --- -## Page → Layout/Component Matrix +## Component Architecture -| Page Type | Layout | Components Used | -|-----------|--------|-----------------| -| IDE Detail | PageLayout | Breadcrumb, ProductHero, RelatedProducts, ProductPricing, ResourceLinks, CommunityLinks, ProductCommands, BackToNavigation | -| CLI Detail | PageLayout | Breadcrumb, ProductHero, RelatedProducts, ProductPricing, ResourceLinks, CommunityLinks, ProductCommands, BackToNavigation | -| Extension Detail | PageLayout | Breadcrumb, ProductHero, RelatedProducts, ProductPricing, ResourceLinks, CommunityLinks, ProductCommands, BackToNavigation | -| Model Detail | PageLayout | Breadcrumb, ProductHero, PlatformLinks, ModelSpecifications, ModelBenchmarks, BackToNavigation | -| Vendor Detail | PageLayout | Breadcrumb, ProductHero, CommunityLinks, VendorProducts, VendorModels, BackToNavigation | -| Provider Detail | PageLayout | Breadcrumb, ProductHero, PlatformLinks, CommunityLinks, BackToNavigation | -| Homepage/Listings | PageLayout | Custom components | -| Article/Docs | PageLayout | MarkdownContent, etc. | +### Page Layer Structure + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ PAGE COMPONENTS │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ RootLayout (src/app/[locale]/layout.tsx) │ +│ ├── i18n provider │ +│ ├── Google Analytics (@next/third-parties) │ +│ ├── ThemeProvider │ +│ └── ClientLayout (for interactivity) │ +│ │ +│ PageLayout (src/layouts/PageLayout.tsx) │ +│ ├── JsonLd (optional schema) │ +│ ├── Header │ +│ │ ├── SearchDialog │ +│ │ ├── StackMegaMenu │ +│ │ ├── RankingMegaMenu │ +│ │ └── i18n Link │ +│ └── Footer │ +│ ├── LanguageSwitcher │ +│ └── ThemeSwitcher │ +│ │ +│ Pages compose components directly (no nested layouts) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Product Components + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ PRODUCT COMPONENTS │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ProductHero.tsx - Main product header │ +│ ├── VerifiedBadge │ +│ └── PlatformIcons │ +│ │ +│ RelatedProducts.tsx - Related product grid │ +│ ├── LinkCard │ +│ │ +│ ProductPricing.tsx - Pricing table │ +│ │ +│ ResourceLinks.tsx - Resource links (download, docs) │ +│ ├── LinkCard │ +│ │ +│ CommunityLinks.tsx - Community links (social) │ +│ ├── LinkCard │ +│ └── PlatformIcons │ +│ │ +│ ProductCommands.tsx - Install/launch commands │ +│ ├── CopyButton │ +│ │ +│ ModelBenchmarks.tsx - Model benchmark scores │ +│ ModelSpecifications.tsx - Model technical specs │ +│ VendorProducts.tsx - Vendor's product grid │ +│ VendorModels.tsx - Vendor's model grid │ +│ GitHubStarHistory.tsx - GitHub stars chart │ +│ PlatformLinks.tsx - Platform links (HuggingFace) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` --- -## Key Design Patterns +## Data Flow + +### Build-Time Data Flow + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ BUILD-TIME DATA FLOW │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ npm run generate │ +│ │ │ +│ ▼ │ +│ Script: generate-manifests.mjs │ +│ ├── Reads manifests/*.jsonc │ +│ ├── Validates against schemas │ +│ └── Writes src/lib/generated/*.ts │ +│ │ │ +│ ▼ │ +│ build │ +│ │ │ +│ ▼ │ +│ Static HTML generated for all locales │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Runtime Data Flow + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ RUNTIME DATA FLOW │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ User Visit │ +│ │ │ +│ ▼ │ +│ Middleware (redirects, locale detection) │ +│ │ │ +│ ▼ │ +│ RootLayout (i18n context, analytics) │ +│ │ │ +│ ▼ │ +│ Page Component │ +│ ├── reads manifest-registry.ts (cached) │ +│ ├── uses manifest-i18n.ts for translations │ +│ ├── generates metadata │ +│ └── renders components │ +│ │ │ +│ ▼ │ +│ Browser Response │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- -### 1. Single Layout Pattern -- Only 1 layout: `PageLayout` -- Pages compose components directly -- No layout inheritance or nesting +## Page Types -### 2. Component Composition -- Each page imports the components it needs directly -- Components are reusable (ProductHero, PlatformLinks, etc.) -- No "smart layouts" that know about page specifics -- Direct imports from component paths (no barrel exports) +| Page Type | Route | Components | Schema | +|-----------|-------|------------|--------| +| Homepage | `/` | Hero sections, cards | WebSite, FAQPage | +| IDE List | `/ides` | FilterSortBar, cards | - | +| IDE Detail | `/ides/[slug]` | ProductHero, RelatedProducts, ProductPricing, ResourceLinks, CommunityLinks, ProductCommands | SoftwareApplication, BreadcrumbList | +| CLI List | `/clis` | FilterSortBar, cards | - | +| CLI Detail | `/clis/[slug]` | ProductHero, RelatedProducts, ProductPricing, ResourceLinks, CommunityLinks, ProductCommands | SoftwareApplication, BreadcrumbList | +| Extension List | `/extensions` | FilterSortBar, cards | - | +| Extension Detail | `/extensions/[slug]` | ProductHero, RelatedProducts, ProductPricing, ResourceLinks, CommunityLinks, ProductCommands | SoftwareApplication, BreadcrumbList | +| Model List | `/models` | FilterSortBar, cards | - | +| Model Detail | `/models/[slug]` | ProductHero, PlatformLinks, ModelSpecifications, ModelBenchmarks | Product | +| Provider List | `/model-providers` | FilterSortBar, cards | - | +| Provider Detail | `/model-providers/[slug]` | ProductHero, PlatformLinks, CommunityLinks | Organization | +| Vendor Detail | `/vendors/[slug]` | ProductHero, CommunityLinks, VendorProducts, VendorModels | Organization | +| Article | `/articles/[slug]` | MarkdownContent, PageHeader | Article | +| Docs | `/docs/[slug]` | MarkdownContent, DocsSidebar, PageHeader | TechArticle | +| Comparison | `/[type]/comparison` | ComparisonTable, FilterSortBar | - | +| Search | `/search` | SearchDialog, SearchResults | - | --- -## Migration Notes +## Key Dependencies + +### Internal Dependencies -### Before (nested layouts): ``` -EntityDetailLayout (base) -└── VendorEntityDetailLayout (extends base, adds ProductHero) - └── ProductDetailLayout (adds product sections) +Components +├── depend on → src/lib/manifest-registry.ts +├── depend on → src/lib/manifest-i18n.ts +├── depend on → src/lib/generated/*.ts +├── depend on → src/lib/metadata/generators.ts +└── depend on → src/i18n/navigation.ts + +Pages +├── depend on → src/components/* +├── depend on → src/lib/manifest-registry.ts +├── depend on → src/lib/metadata/generators.ts +└── depend on → src/i18n/navigation.ts + +Lib Modules +├── manifest-registry.ts depends on → src/lib/generated/*.ts +├── manifest-i18n.ts depends on → src/i18n/locales/*.json +├── metadata/ depends on → src/lib/manifest-registry.ts +└── landscape-data.ts depends on → src/lib/generated/*.ts ``` -### After (flat): +### External Dependencies + +| Dependency | Purpose | +|------------|---------| +| next | React framework (v15) | +| react | UI library (v19) | +| @next/third-parties | Google Analytics integration | +| lucide-react | Icons | +| ibm-plex-mono | Monospaced font | +| claude-ui | UI components (if used) | +| playwright | Automated fetching (via skills) | + +--- + +## Deployment + ``` -PageLayout (Header + Footer) -└── Page directly composes components +┌─────────────────────────────────────────────────────────────────┐ +│ DEPLOYMENT FLOW │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Git Push │ +│ │ │ +│ ▼ │ +│ GitHub Actions CI (.github/workflows/ci.yml) │ +│ ├── Lint │ +│ ├── Type Check │ +│ ├── Build │ +│ ├── URL Validation │ +│ └── Spell Check │ +│ │ │ +│ ▼ │ +│ Cloudflare Pages (via deploy-production.yml) │ +│ ├── Build Output: .open-next │ +│ └── Edge Runtime │ +│ │ │ + ▼ │ +│ https://aicodingstack.io │ +│ │ +└─────────────────────────────────────────────────────────────────┘ ``` -### Benefits: -1. **No layout nesting** - Clear data flow -2. **Explicit composition** - Page code shows exactly what components are used -3. **Easier to modify** - Change one page without affecting others -4. **Better testability** - Components can be tested independently -5. **Simpler mental model** - Only 1 layout to understand +--- + +## Related Documentation + +- `SCHEMA-ARCHITECTURE.md` - Schema system details +- `SCHEMA-ALIGNMENT.md` - Schema/Type correspondence +- `METADATA_OPTIMIZATION.md` - Metadata system +- `SEO-AUDIT-REPORT.md` - SEO implementation status +- `PERFORMANCE.md` - Performance considerations +- `scripts/README.md` - Build and generation scripts +- `CLAUDE.md` - Development guidelines + +--- + +**Document Version:** 2.0 +**Last Updated:** January 6, 2026 diff --git a/docs/DOCUMENTATION_MAINTENANCE.md b/docs/DOCUMENTATION_MAINTENANCE.md new file mode 100644 index 0000000..c11c119 --- /dev/null +++ b/docs/DOCUMENTATION_MAINTENANCE.md @@ -0,0 +1,303 @@ +# Documentation Maintenance Strategy + +**Last Updated:** January 6, 2026 + +--- + +## Purpose + +This document outlines the strategy for maintaining accurate, up-to-date documentation in the AI Coding Stack project. + +--- + +## Documentation Principles + +### 1. Single Source of Truth + +- **Code is the source of truth** - Documentation should reflect what the code actually does +- When code changes, documentation must be updated +- Use code examples that can be tested/verified + +### 2. DRY (Don't Repeat Yourself) + +- Avoid duplicating information across multiple documents +- Use cross-references instead of rewriting content +- Each document should have a clear, single purpose + +### 3. Document Why, Not Just What + +- Explain design decisions and trade-offs +- Include context for architectural choices +- Document edge cases and gotchas + +### 4. Version Control + +- All changes to docs/ should follow the same review process as code +- Use descriptive commit messages for documentation updates +- Include the document name in commit messages: `docs(specs.md): update manifest types table` + +--- + +## Document Ownership + +Each document has clear ownership and update triggers: + +| Document | Owner Type | Update Triggers | Review Frequency | +|----------|------------|-----------------|------------------| +| `ORIGINAL-SPECS.md` | Core team | Project scope changes, new manifest types | Never | +| `COMPONENT-RELATIONSHIP-DIAGRAM.md` | Core team | Architectural changes, new systems | Monthly | +| `SCHEMA-ARCHITECTURE.md` | Metadata lead | Schema system changes | As needed | +| `METADATA_OPTIMIZATION.md` | Metadata lead | SEO/metadata system changes | As needed | +| `SEO-AUDIT-REPORT.md` | SEO lead | Quarterly SEO audit | Quarterly | +| `MANIFEST_I18N.md` | i18n lead | Translation system changes | As needed | +| `PERFORMANCE.md` | Performance lead | Performance guidelines changes | As needed | +| `GITHUB_SETUP_MANUAL_STEPS.md` | DevOps lead | CI/CD workflow changes | As needed | +| `FETCH_GITHUB_STARS.md` | DevOps lead | External fetching system changes | As needed | + +--- + +## Update Process + +### 1. Pre-Update Checklist + +Before updating documentation: + +- [ ] Verify the code change is complete +- [ ] Test the code examples (if any) +- [ ] Check if other docs reference this content +- [ ] Plan the update purpose (clarification, correction, addition) + +### 2. Making Updates + +Follow these guidelines: + +```bash +# Use conventional commits for documentation +git add docs/COMPONENT-RELATIONSHIP-DIAGRAM.md +git commit -m "docs(COMPONENT-RELATIONSHIP-DIAGRAM.md): add Deployment flow section" +``` + +**Commit Types:** +- `docs(filename):` - Documentation only changes +- `chore(filename):` - Documentation maintenance updates +- `feat(filename):` - New documentation sections +- `fix(filename):` - Documentation corrections + +### 3. Post-Update Checklist + +After updating documentation: + +- [ ] Update the "Last Updated" date +- [ ] Update version number (if applicable) +- [ ] Verify cross-references are still valid +- [ ] Check for broken links +- [ ] Request a review from the document owner + +--- + +## Review Schedule + +### Monthly Checks + +- [ ] Verify `COMPONENT-RELATIONSHIP-DIAGRAM.md` against current codebase structure +- [ ] Check all "Last Updated" dates - flag documents >6 months old +- [ ] Review recent code changes for documentation needs + +### Quarterly Reviews + +- [ ] Complete SEO audit updates in `SEO-AUDIT-REPORT.md` +- [ ] Review `specs.md` for project scope changes +- [ ] Verify all documentation links are working +- [ ] Update version references (Next.js, React, etc.) + +### As-Needed Updates + +All other documents are updated as changes occur in their respective domains. + +--- + +## Automation Opportunities + +### 1. CI Checks + +Potential automated checks: + +- [ ] Markdown linting (markdownlint) +- [ ] Link checker for all docs/ +- [ ] Spelling check on documentation files +- [ ] Code block syntax validation + +### 2. Generated Documentation + +Currently generated: + +- [x] `src/lib/generated/*.ts` - Typed manifest imports +- [ ] Consider: Auto-generating API docs from TypeScript types + +### 3. Documentation Coverage Tracking + +Potential metrics to track: + +- Number of files with "Last Updated" > 6 months +- Code changes without corresponding documentation updates +- Broken links in documentation + +--- + +## Documentation Template + +All new documentation files should follow this structure: + +```markdown +# Document Title + +**Last Updated:** YYYY-MM-DD +**Owner:** [Team member or role] +**Version:** x.y + +--- + +## Purpose + +Brief description of what this document covers and who should read it. + +--- + +## Overview + +High-level introduction to the topic. + +--- + +## [Sections...] + +Organized content with clear headings and subheadings. + +Use code blocks for examples: + +```typescript +// Example code +``` + +Use tables for structured data: + +| Column 1 | Column 2 | +|----------|----------| +| Value A | Value B | + +--- + +## Related Files + +| File | Purpose | +|------|---------| +| `path/to/file` | Description | + +--- + +## Related Documentation + +- `[Link](./other-doc.md)` - Brief description + +--- + +**Version:** x.y +**Last Updated:** YYYY-MM-DD +``` + +--- + +## Deprecated Documentation + +When a document becomes obsolete: + +1. Add a DEPRECATED notice at the top: + +```markdown +> **DEPRECATED:** This document is no longer maintained. +> Please see [NEW_DOCUMENT.md](./NEW_DOCUMENT.md) for current information. +``` + +2. Update cross-references to point to the new document + +3. After 3 months, remove the deprecated document + +--- + +## Contribute Guidelines + +### Adding New Documentation + +1. Check if similar documentation exists +2. Choose an appropriate filename +3. Follow the documentation template +4. Add to the documentation index (if applicable) +5. Submit as a PR with the `documentation` label + +### Updating Existing Documentation + +1. Read the entire document first +2. Preserve the structure and style +3. Update the "Last Updated" date +4. Increment version number if the change is significant +5. Submit as a PR with the `documentation` label + +--- + +## Troubleshooting + +### Documentation Discrepancies + +If you find documentation that doesn't match the code: + +1. Check the git blame for the last update +2. Create an issue labeled `documentation-outdated` +3. Tag the document owner +4. Include the specific discrepancy + +### Missing Documentation + +If you can't find information you need: + +1. Check the documentation map in `specs.md` +2. Search in the codebase for comments +3. Create an issue labeled `documentation-need` + +--- + +## Metrics & KPIs + +Track the following to ensure documentation quality: + +| Metric | Target | Frequency | +|--------|--------|-----------| +| Docs updated in last 6 months | >90% | Monthly | +| Broken links in docs/ | 0 | Quarterly | +| docs/ coverage for major features | 100% | Per release | +| Documentation review time | <3 days | Per PR | + +--- + +## Continuous Improvement + +### Documentation Retrospectives + +Quarterly reviews should include: + +- What documentation updates were needed? +- What was difficult to document? +- What documentation was most helpful? +- What can be improved? + +### Documentation Debt Tracking + +Create issues for: + +- Outdated documentation (`documentation-outdated`) +- Missing documentation (`documentation-need`) +- Documentation improvements (`documentation-improvement`) + +--- + +**Version:** 1.0 +**Last Updated:** January 6, 2026 diff --git a/docs/FETCH_GITHUB_STARS.md b/docs/FETCH_GITHUB_STARS.md index 258590f..f136789 100644 --- a/docs/FETCH_GITHUB_STARS.md +++ b/docs/FETCH_GITHUB_STARS.md @@ -1,84 +1,212 @@ # GitHub Stars Fetcher -This script fetches GitHub star counts for all projects in the manifest files and updates the `githubStars` field. +**Last Updated:** January 6, 2026 -## Features +This document describes the GitHub stars fetching system for AI Coding Stack. -- Fetches star counts from GitHub API for all projects with GitHub URLs -- Converts star counts to 'k' format (e.g., 1.5k, 23.4k) -- Handles different JSON structures (direct `githubUrl` field vs nested `communityUrls.github`) -- Supports GitHub authentication to avoid rate limits -- Automatic retry delay to avoid hitting API rate limits +--- -## Prerequisites +## Overview -```bash -npm install -# or if you only need the built-in Node.js modules, no installation needed +The GitHub Stars Fetcher fetches star counts from the GitHub API for all projects in the manifest files and creates a centralized `github-stars.json` data file. + +**Implementation**: `scripts/fetch/fetch-github-stars.mjs` +**Output**: `manifests/github-stars.json` + +--- + +## Schema + +The stars data follows `manifests/$schemas/github-stars.schema.json`: + +```typescript +interface ManifestGitHubStars { + extensions: { [productId: string]: number | null } + clis: { [productId: string]: number | null } + ides: { [productId: string]: number | null } +} ``` +--- + ## Usage -### Using npm script (Recommended) +### Fetch Stars with GitHub Token (Recommended) -#### Without GitHub Token (Rate Limited) ```bash -npm run fetch:github-stars +GITHUB_TOKEN=your_github_token_here npm run generate ``` -⚠️ **Warning**: Without authentication, you're limited to 60 requests per hour. +### Fetch Stars Without Token (Rate Limited) -#### With GitHub Token (Recommended) ```bash -GITHUB_TOKEN=your_github_token_here npm run fetch:github-stars +npm run generate ``` -With authentication, you get 5,000 requests per hour. +### Direct Script Execution -### Using Node.js directly - -#### Without GitHub Token ```bash node scripts/fetch/index.mjs github-stars ``` -#### With GitHub Token -```bash -GITHUB_TOKEN=your_github_token_here node scripts/fetch/index.mjs github-stars -``` +--- ## Getting a GitHub Token 1. Go to https://github.com/settings/tokens -2. Click "Generate new token" → "Generate new token (classic)" +2. Click **Generate new token** → **Generate new token (classic)** 3. Give it a name (e.g., "acs-stars-fetcher") -4. Select scopes: Only need `public_repo` (or no scopes for public repos) -5. Click "Generate token" -6. Copy the token and use it in the command above +4. Scopes: `public_repo` (or none for public repos only) +5. Click **Generate token** +6. Copy the token and use it as `GITHUB_TOKEN` environment variable + +--- + +## Rate Limits + +| Authentication | Requests | Time Period | +|----------------|----------|-------------| +| With token | 5,000 | 1 hour | +| Without token | 60 | 1 hour | + +**Recommendation**: Always use a GitHub token to avoid rate limiting. + +--- + +## How It Works + +### 1. Data Sources -## What It Does +The script fetches GitHub URLs from these files: -The script processes these files: -- `manifests/terminals.json` (uses `communityUrls.github` field) -- `manifests/extensions.json` (uses `communityUrls.github` field) -- `manifests/ides.json` (uses `communityUrls.github` field) -- `manifests/clis.json` (uses `communityUrls.github` field) -- `manifests/providers.json` (uses `communityUrls.github` field) -- `manifests/vendors.json` (uses `communityUrls.github` field) +| Category | File | URL Field | +|----------|------|-----------| +| Extensions | `manifests/extensions/*.json` | `communityUrls.github` | +| CLIs | `manifests/clis/*.json` | `communityUrls.github` | +| IDEs | `manifests/ides/*.json` | `communityUrls.github` | +| Models | `manifests/models/*.json` | `communityUrls.github` | + +### 2. Processing Steps For each project: -1. Extracts the GitHub URL -2. Parses owner/repo from the URL -3. Fetches star count from GitHub API -4. Converts to 'k' format (1 decimal place) -5. Updates the `githubStars` field -## Output Format +1. Extract GitHub URL from `communityUrls.github` field +2. Parse owner/repo from URL (e.g., `microsoft/playwright`) +3. Fetch star count from GitHub API: `GET /repos/:owner/:repo/stargazers` +4. Store raw star count (number) +5. Write to `manifests/github-stars.json` + +### 3. Output Format + +```json +{ + "extensions": { + "playwright": 90450, + "context7": 2150, + "claude-code": 5420 + }, + "clis": { + "github-copilot-cli": 3450, + "codex-cli": 1230 + }, + "ides": { + "cursor": 42000 + } +} +``` + +--- + +## Display Format + +When displaying stars on the site, they are formatted with a helper function: + +```typescript +// Formats: 42000 → "42k", 1500 → "1.5k", 150 → "150" +function formatStars(stars: number | null): string +``` + +This is separate from the stored format (raw numbers). + +--- + +## Usage in Components + +### Import Stars Data + +```typescript +import { githubStars } from '@/lib/generated/github-stars' + +// Get stars for an IDE +const cursorStars = githubStars.ides['cursor'] // Returns number or null + +// Display formatted +const displayStars = formatStars(cursorStars) // "42k" +``` + +### ProductHero Component -The `githubStars` field will be populated with numbers in 'k' format: -- `1500` stars → `1.5` -- `23456` stars → `23.5` -- `123` stars → `0.1` +```typescript +import { githubStars } from '@/lib/generated/github-stars' + + +``` + +--- + +## Files Involved + +| Category | File | Purpose | +|----------|------|---------| +| Script | `scripts/fetch/fetch-github-stars.mjs` | Fetch implementation | +| Entry | `scripts/fetch/index.mjs` | Category runner | +| Output | `manifests/github-stars.json` | Stars data | +| Type | `src/types/manifests.ts` | `ManifestGitHubStars` interface | +| Import | `src/lib/generated/github-stars.ts` | Typed import | +| Schema | `manifests/$schemas/github-stars.schema.json` | Validation | + +--- + +## Integration with Build Process + +The GitHub stars data is automatically generated as part of the build: + +```bash +npm run generate # Includes star fetching +npm run dev # Generate + start dev server +npm run build # Generate + build for production +``` + +--- + +## Updating Stars + +To update star counts after changes to manifests: + +```bash +# Single update +npm run generate + +# Force rebuild +rm manifests/github-stars.json && npm run generate +``` + +--- + +## Error Handling + +The script handles: + +1. **Missing GitHub URLs**: Skips products without `communityUrls.github` +2. **Private Repos**: Sets value to `null` for access errors +3. **API Errors**: Logs error and continues +4. **Rate Limits**: Logs warning and returns cached/empty data + +--- ## Example Output @@ -88,32 +216,22 @@ The `githubStars` field will be populated with numbers in 'k' format: ✅ Using GitHub token for authentication 🔍 Fetching stars for Playwright (microsoft/playwright)... - ✅ Updated Playwright: 65.3k stars + ✅ Updated Playwright: 90450 stars 🔍 Fetching stars for Context7 (upstash/context7)... - ✅ Updated Context7: 2.1k stars - + ✅ Updated Context7: 2150 stars ================================================== 🎉 All files processed! ================================================== -``` - -## Error Handling - -The script handles: -- ❌ Invalid GitHub URLs -- ❌ Repositories not found (404) -- ❌ Rate limit errors (403) -- ❌ Network errors -- ⏭️ Projects without GitHub URLs (skipped) -## Rate Limiting +✅ Written to manifests/github-stars.json +``` -The script includes a 1-second delay between requests to avoid hitting rate limits. You can adjust this in the code if needed. +--- -## Notes +**Related Files:** +- `src/lib/landscape-data.ts` - Uses stars for sorting +- `src/components/product/ProductHero.tsx` - Displays stars on product pages +- `src/app/[locale]/ides/comparison/page.client.tsx` - Comparison rankings -- Star counts are rounded to 1 decimal place in 'k' format -- Projects without GitHub URLs are skipped -- The script preserves all other fields in the JSON files -- JSON files are formatted with 2-space indentation +**Last Updated:** January 6, 2026 diff --git a/docs/I18N-ARCHITECTURE-RULES.md b/docs/I18N-ARCHITECTURE-RULES.md new file mode 100644 index 0000000..8e42029 --- /dev/null +++ b/docs/I18N-ARCHITECTURE-RULES.md @@ -0,0 +1,495 @@ +# i18n Translation Architecture Rules + +## Overview + +This document defines the rules and best practices for organizing translation resources in the `translations/` directory. + +## Current Structure Analysis + +### Observed Pattern +``` +translations/ +├── {locale}/ # 12 language directories (en, de, es, fr, id, ja, ko, pt, ru, tr, zh-Hans, zh-Hant) +│ ├── index.ts # Unified export entry +│ ├── shared.json # Shared translations (actions, terms, etc.) +│ ├── components.json # Component translations (organized by component name) +│ └── pages/ # Page-specific translations +│ ├── home.json +│ ├── stacks.json # ⚠️ NEEDS REFACTORING - contains multiple pages +│ ├── comparison.json +│ └── ... +``` + +### Key Findings + +1. **stacks.json is overloaded**: Contains translations for multiple pages/features: + - ides, clis, extensions, models, vendors (list pages) + - ideDetail, cliDetail, extensionDetail, modelDetail, vendorDetail (detail pages) + - modelCompare (comparison page) + - modelProviders, modelProviderDetail + - overview + +2. **Usage pattern in code**: + ```tsx + const tPage = useTranslations('pages.stacks') + const tShared = useTranslations('shared') + // or + const tComponent = useTranslations('components.common.footer') + const tShared = useTranslations('shared') + ``` + +3. **Over-reliance on `@:` references**: Many page/component translations reference shared translations using `@:shared.xxx`, which is redundant given the tPage + tShared pattern in code. + +## Architecture Rules + +### Rule 1: Page Translation File Granularity + +**Principle**: Each page or closely related page group should have its own JSON file. + +**Implementation**: +- ❌ **Bad**: Single `stacks.json` containing translations for ides, clis, extensions, models, vendors, etc. +- ✅ **Good**: Split into dedicated files: + ``` + pages/ + ├── home.json + ├── ides.json # IDE list page + ├── ide-detail.json # IDE detail page + ├── clis.json # CLI list page + ├── cli-detail.json # CLI detail page + ├── extensions.json + ├── extension-detail.json + ├── models.json + ├── model-detail.json + ├── model-compare.json + ├── model-providers.json + ├── model-provider-detail.json + ├── vendors.json + ├── vendor-detail.json + ├── stacks-overview.json # Overview/landing page + └── ... + ``` + +**Rationale**: +- Better file organization and maintainability +- Easier to locate translations for specific pages +- Clearer code-to-translation mapping +- Reduces cognitive load when editing translations + +--- + +### Rule 2: Component Translation Directory Structure + +**Principle**: `components.json` should be refactored into a directory structure that **mirrors the `src/components/` directory structure**. + +**Current Component Structure**: +``` +src/components/ +├── Header.tsx +├── Footer.tsx +├── PageHeader.tsx +├── controls/ +│ ├── SearchDialog.tsx +│ ├── ThemeSwitcher.tsx +│ └── ... +├── navigation/ +│ ├── BackToNavigation.tsx +│ ├── Breadcrumb.tsx +│ ├── StackTabs.tsx +│ └── ... +├── sidebar/ +│ ├── DocsSidebar.tsx +│ └── ... +└── product/ + ├── ProductHero.tsx + ├── ComparisonTable.tsx + └── ... +``` + +**Target Translation Structure**: +- ❌ **Bad**: Flat `components.json` file with all components +- ✅ **Good**: Organize by component directory: + ``` + components/ + ├── common.json # Root-level components (Header, Footer, PageHeader, etc.) + ├── navigation.json # All components in src/components/navigation/ + ├── controls.json # All components in src/components/controls/ + ├── sidebar.json # All components in src/components/sidebar/ + └── product.json # All components in src/components/product/ + ``` + +**Internal Structure** (example for components/navigation.json): + ```json + { + "backToNavigation": { + "backTo": "Back to", + "indexLabel": "INDEX" + }, + "breadcrumb": { + "home": "Home" + }, + "stackTabs": { + "overview": "Overview", + "ides": "IDEs" + } + } + ``` + +**Migration Strategy**: +- Root-level components → `components/common.json` +- Each subdirectory → One JSON file named after the directory +- Within each JSON, organize by component name (camelCase) +- Update index.ts to export from new structure + +**Rationale**: +- **Clear mapping**: Easy to find translations for any component +- **Scalability**: Grows naturally with the component library +- **Consistency**: Developers familiar with component structure know where to find translations +- **Maintainability**: Moving/renaming components means updating translations in parallel + +--- + +### Rule 3: Minimize `@:` References in JSON Files + +**Principle**: Since the codebase uses `tPage + tShared` or `tComponent + tShared` patterns, JSON files should minimize `@:shared` references and let the code handle multiple translation sources. + +**Implementation**: +- ❌ **Bad**: Page JSON with many `@:shared` references + ```json + { + "cliDetail": { + "documentation": "@:shared.terms.documentation", + "download": "@:shared.actions.download", + "license": "@:shared.terms.license" + } + } + ``` + +- ✅ **Good**: Let the code use tShared directly + ```tsx + // In component code + const tPage = useTranslations('pages.cliDetail') + const tShared = useTranslations('shared') + + // Use directly + + {tShared('terms.documentation')} + ``` + +**When to use `@:` references**: +- ✅ Within the same namespace (e.g., `@:pages.home.title` within pages/home.json) +- ✅ For DRY within the same file (avoid duplicating long strings) +- ❌ Avoid cross-namespace references to `shared` (let code handle it) + +**Rationale**: +- Reduces indirection and improves readability +- Makes it clear which translations are page-specific +- Simplifies refactoring and moving translations +- Code is the source of truth for composition logic + +--- + +### Rule 4: Metadata Placement + +**Principle**: Page metadata (meta title, description, keywords, OG tags) should be co-located with page translations. + +**Implementation**: +```json +{ + "meta": { + "title": "AI Coding Stack - Your AI Coding Ecosystem Hub", + "description": "Comprehensive directory for AI coding tools...", + "keywords": "AI coding, IDEs, CLIs, extensions, models" + }, + "title": "Your AI Coding Ecosystem Hub", + "subtitle": "Discover, Compare, Build Faster.", + "...": "..." +} +``` + +**Rationale**: +- Single source of truth for page content +- Easier to maintain consistency between visible content and metadata +- Aligns with Next.js metadata generation patterns + +--- + +### Rule 5: Multi-Language Incremental Translation Strategy + +**Principle**: To simplify development workflow, new translation keys should initially use English placeholders across all locales, with proper translation happening in a separate step. + +**Implementation Workflow**: + +1. **Add new feature/page**: Create translation keys in `translations/en/*.json` +2. **Propagate to all locales**: Copy English values to all other 11 language files as placeholders +3. **Mark for translation**: (Optional) Use a convention like `[EN]` prefix or tracking file +4. **Batch translation**: Periodically translate all English placeholders to respective languages + +**Example**: +```json +// translations/en/pages/new-feature.json +{ + "title": "New Feature", + "description": "This is a new feature" +} + +// translations/zh-Hans/pages/new-feature.json (initial) +{ + "title": "New Feature", // English placeholder + "description": "This is a new feature" +} + +// translations/zh-Hans/pages/new-feature.json (after translation) +{ + "title": "新功能", + "description": "这是一个新功能" +} +``` + +**Rationale**: +- Prevents broken UI in non-English locales during development +- Allows feature development to proceed without waiting for translations +- Enables batch translation for efficiency +- Clear visibility of what needs translation + +--- + +## Translation File Naming Conventions + +### File Names +- Use kebab-case: `model-providers.json`, `cli-detail.json` +- Be descriptive and specific +- Avoid abbreviations unless widely understood + +### Translation Keys +- Use camelCase: `maxOutput`, `contextWindow`, `visitWebsite` +- Nest logically but avoid deep nesting (max 3 levels recommended) +- Use singular for object keys, plural for lists + +### Namespaces +- `shared.actions.*` - User actions (view, download, compare) +- `shared.terms.*` - Domain terminology (license, vendor, documentation) +- `shared.categories.*` - Category names (singular, plural, all) +- `shared.labels.*` - UI labels +- `components.common.{componentName}.*` - Root-level component translations + - `components.common.header.*` - Header component + - `components.common.footer.*` - Footer component + - `components.common.pageHeader.*` - PageHeader component +- `components.{subdirectory}.{componentName}.*` - Subdirectory component translations + - `components.navigation.breadcrumb.*` - Navigation/Breadcrumb component + - `components.navigation.stackTabs.*` - Navigation/StackTabs component + - `components.controls.searchDialog.*` - Controls/SearchDialog component + - `components.product.productHero.*` - Product/ProductHero component +- `pages.{pageName}.*` - Page-specific content + +--- + +## Migration Checklist + +To align the current codebase with these rules: + +### Phase 1: Split stacks.json +- [ ] Create individual page translation files (ides.json, clis.json, etc.) +- [ ] Update index.ts to import new files +- [ ] Update component code to use correct translation namespaces +- [ ] Remove old stacks.json references + +### Phase 2: Refactor components.json +- [ ] Create components/ directory +- [ ] Split components.json into files by component location: + - `components/common.json` - Root-level components (Header, Footer, PageHeader) + - `components/navigation.json` - All navigation/* components + - `components/controls.json` - All controls/* components + - `components/sidebar.json` - All sidebar/* components + - `components/product.json` - All product/* components +- [ ] Update index.ts to import from new directory structure +- [ ] Update component code to use new translation paths: + - Root components: `useTranslations('components.common.{componentName}')` + - Subdirectory components: `useTranslations('components.{subdirectory}.{componentName}')` + +### Phase 3: Remove redundant @: references +- [ ] Audit all page and component JSON files +- [ ] Remove @:shared references where code can use tShared +- [ ] Update component code to use both tPage/tComponent and tShared + +### Phase 4: Standardize metadata +- [ ] Ensure all pages have meta objects +- [ ] Verify metadata localization completeness + +### Phase 5: Establish translation workflow +- [ ] Document the English placeholder → translation workflow +- [ ] Set up tooling or scripts to detect untranslated content (if needed) + +--- + +## Examples + +### Example 1: Page Translation (models.json) + +```json +{ + "meta": { + "title": "AI Coding Models | Compare LLMs for Code 2025", + "description": "Compare large language models optimized for code generation..." + }, + "title": "AI Coding Models", + "subtitle": "Large language models optimized for code generation and analysis", + "compareAll": "Compare All Models", + "search": "Search by name...", + "filters": { + "context": "Context:", + "pricing": "Pricing:", + "size": "Size:" + }, + "lifecycle": { + "latest": "Latest", + "maintained": "Maintained", + "deprecated": "Deprecated", + "noResults": "No {lifecycle} models match your search" + } +} +``` + +### Example 2: Component Translation (components/common.json) + +```json +{ + "header": { + "aiCodingStack": "AI Coding Stack", + "manifesto": "Manifesto", + "landscape": "Landscape", + "collections": "Collections", + "ranking": "Ranking", + "openMenu": "Open menu", + "closeMenu": "Close menu" + }, + "footer": { + "copyright": "© 2025 AI Coding Stack • Built with ❤︎ • Open Source", + "tagline": "Your AI Coding Ecosystem Hub.", + "openSource": "Open source AI coding metadata repository.", + "selectLanguage": "Select Language", + "toggleTheme": "Toggle theme" + }, + "pageHeader": { + "backToTop": "Back to top" + } +} +``` + +### Example 3: Component Translation (components/navigation.json) + +```json +{ + "breadcrumb": { + "home": "Home" + }, + "backToNavigation": { + "backTo": "Back to", + "indexLabel": "INDEX" + }, + "stackTabs": { + "overview": "Overview", + "ides": "IDEs", + "clis": "CLIs", + "extensions": "Extensions", + "models": "Models" + } +} +``` + +### Example 4: Component Translation (components/controls.json) + +```json +{ + "searchDialog": { + "placeholder": "Search...", + "noResults": "No results found" + }, + "themeSwitcher": { + "light": "Light mode", + "dark": "Dark mode" + }, + "copyButton": { + "copied": "Copied!", + "copyToClipboard": "Copy to clipboard" + } +} +``` + +### Example 5: Code Usage Pattern + +```tsx +// ✅ Correct: Use multiple translation sources in pages +import { useTranslations } from 'next-intl' + +function ModelDetailPage() { + const tPage = useTranslations('pages.modelDetail') + const tShared = useTranslations('shared') + + return ( +
+

{tPage('title')}

+ + {tShared('terms.license')} +

{tPage('description')}

+
+ ) +} + +// ✅ Correct: Use multiple translation sources in components (root-level) +function Header() { + const tComponent = useTranslations('components.common.header') + const tShared = useTranslations('shared') + + return ( +
+

{tComponent('aiCodingStack')}

+ + +
+ ) +} + +// ✅ Correct: Use translations for components in subdirectories +function Breadcrumb() { + const tComponent = useTranslations('components.navigation.breadcrumb') + + return ( + + ) +} + +// ❌ Incorrect: Over-reliance on @: in JSON +// pages/model-detail.json +{ + "download": "@:shared.actions.download", // Don't do this + "license": "@:shared.terms.license" // Let code use tShared +} +``` + +--- + +## Benefits of These Rules + +1. **Maintainability**: Clear structure makes it easy to find and update translations +2. **Scalability**: Supports growth without becoming unwieldy +3. **Developer Experience**: Intuitive organization reduces cognitive load +4. **Type Safety**: Better alignment with code enables stronger typing +5. **Localization Workflow**: Clear process for adding new languages and content +6. **Performance**: Smaller, focused files load faster and are easier to cache + +--- + +## Conclusion + +These rules establish a clear, scalable architecture for i18n translations that: +- Aligns with code patterns (tPage + tShared, tComponent + tShared) +- Promotes maintainability through logical file organization +- Simplifies development with English placeholder strategy +- Reduces redundancy by minimizing cross-namespace @: references +- Co-locates related content (metadata with page translations) + +All future translation work should follow these guidelines. diff --git a/docs/MANIFEST_I18N.md b/docs/MANIFEST_I18N.md index 210c36a..c42e854 100644 --- a/docs/MANIFEST_I18N.md +++ b/docs/MANIFEST_I18N.md @@ -1,185 +1,334 @@ -# Manifest i18n Guide +# Manifest Internationalization (i18n) -This document describes how to add multi-language support for manifest files. +**Last Updated:** January 6, 2026 + +--- ## Overview -We use **Solution 4 (Hybrid Approach)**: Add an `i18n` field to each manifest entry to store translations. +The AI Coding Stack has **two separate internationalization systems** that share the same locale configuration: -## Structure +1. **UI Translation System** - Translates static UI strings using `next-intl` +2. **Manifest Translation System** - Translates manifest data (using the same locales) -```json -{ - "id": "example", - "name": "Example Tool", - "description": "This is an example tool for demonstration.", - // ... other fields ... - "i18n": { - "zh-Hans": { - "description": "这是一个用于演示的示例工具。" - } - } +--- + +## System 1: UI Translation System (next-intl) + +### Supported Locales + +| Locale | Code | Status | +|--------|------|--------| +| English | `en` | ✅ Default | +| German | `de` | ✅ Full | +| Spanish | `es` | ✅ Full | +| French | `fr` | ✅ Full | +| Indonesian | `id` | ✅ Full | +| Japanese | `ja` | ✅ Full | +| Korean | `ko` | ✅ Full | +| Portuguese | `pt` | ✅ Full | +| Russian | `ru` | ✅ Full | +| Turkish | `tr` | ✅ Full | +| Simplified Chinese | `zh-Hans` | ✅ Full | +| Traditional Chinese | `zh-Hant` | ✅ Full | + +### Configuration + +**File:** `src/i18n/config.ts` + +```typescript +export const defaultLocale = 'en' +export const locales = ['en', 'de', 'es', 'fr', 'id', 'ja', 'ko', 'pt', 'ru', 'tr', 'zh-Hans', 'zh-Hant'] +``` + +### Translation Files + +**Directory:** `translations/{locale}/` + +``` +translations/ +├── en/ # English (default) +│ ├── components.json # Component translations +│ ├── pages/ # Page-specific translations +│ │ ├── home.json +│ │ ├── articles.json +│ │ ├── comparison.json +│ │ └── ... +│ ├── shared.json # Shared translations +│ └── index.ts # Entry point +├── zh-Hans/ # Simplified Chinese +└── ... (other locales) +``` + +### Usage in Components + +```typescript +import { useTranslations } from 'next-intl' + +export default function MyComponent() { + const tComponent = useTranslations('shared') + return

{tComponent('welcome')}

+} +``` + +### Usage in Server Components + +```typescript +import { getTranslations } from 'next-intl/server' + +export default async function Page() { + const tPage = await getTranslations('home') + return

{t('title')}

} ``` -## Supported Languages +### Navigation -Currently supported languages (defined in `src/i18n/config.ts`): -- `en` (English) - Default language -- `zh-Hans` (Simplified Chinese) +**File:** `src/i18n/navigation.ts` -## Translatable Fields +The `Link` component provides localized routing: + +```typescript +import { Link } from '@/i18n/navigation' + +// Automatically prepends the locale to the URL +IDEs // → /en/ides or /zh-Hans/ides +``` -Currently supports translating the following fields: -- `description` - Tool description +--- -Future extensions can include: -- `name` - Tool name (if localized names are needed) -- Other custom fields +## System 2: Manifest Translation System -## Steps to Add Translations +### Purpose -### 1. Add Translation in Manifest File +Translates manifest data (IDEs, CLIs, models, etc.) using the same **12 locales** as the UI system: -Edit the corresponding manifest file (e.g., `manifests/terminals.json`): +| Locale | Code | Status | +|--------|------|--------| +| English | `en` | ✅ Default (no translation needed) | +| German | `de` | ✅ Supported via translations field | +| Spanish | `es` | ✅ Supported via translations field | +| French | `fr` | ✅ Supported via translations field | +| Indonesian | `id` | ✅ Supported via translations field | +| Japanese | `ja` | ✅ Supported via translations field | +| Korean | `ko` | ✅ Supported via translations field | +| Portuguese | `pt` | ✅ Supported via translations field | +| Russian | `ru` | ✅ Supported via translations field | +| Turkish | `tr` | ✅ Supported via translations field | +| Simplified Chinese | `zh-Hans` | ✅ Supported via translations field | +| Traditional Chinese | `zh-Hant` | ✅ Supported via translations field | -```json +### Core Module: `src/lib/manifest-i18n.ts` + +```typescript +function localizeManifestItem( + item: T, + locale: Locale, // Any of the 18 supported locales + fields: (keyof T)[] = ['description'] +): T + +function localizeManifestItems( + items: T[], + locale: Locale, + fields?: (keyof T)[] +): T[] +``` + +### Translation Structure + +Manifest items support translations through: + +```jsonc { - "id": "warp", - "name": "Warp", - "description": "Warp is a modern Rust-based terminal emulator with AI-powered features.", - "i18n": { + "id": "cursor", + "name": "Cursor", + "description": "An AI-powered code editor", + "translations": { "zh-Hans": { - "description": "Warp 是一款基于 Rust 的现代终端模拟器，具有 AI 驱动的功能。" + "name": "Cursor", + "description": "一款 AI 驱动的代码编辑器" + }, + "de": { + "name": "Cursor", + "description": "Ein AI-gesteuerter Code-Editor" + }, + "ko": { + "name": "Cursor", + "description": "AI 기반 코드 에디터" } } } ``` -### 2. Use Translations in Code - -We provide utility functions in `src/lib/manifest-i18n.ts` to handle translations: +### Usage Example ```typescript -import { localizeManifestItem } from '@/lib/manifest-i18n'; -import type { Locale } from '@/i18n/config'; -import terminals from '@/../../manifests/terminals.json'; +import { localizeManifestItems } from '@/lib/manifest-i18n' +import { ides } from '@/lib/generated/ides' +import type { Locale } from '@/i18n/config' + +export default function IDEList({ locale }: { locale: Locale }) { + const translatedIDEs = localizeManifestItems(ides, locale, ['description']) + + return ( +
    + {translatedIDEs.map(ide => ( +
  • {ide.description}
    • + ))} +
+ ) +} +``` -// In a page component -export default async function TerminalPage({ params }) { - const { locale, slug } = await params; - const terminalRaw = terminals.find((t) => t.id === slug); +--- - // Apply localization - const terminal = localizeManifestItem(terminalRaw, locale as Locale); +## Architecture Diagram - // Now terminal.description will automatically return the appropriate translation - // If locale is 'zh-Hans', returns Chinese; if 'en' or no translation, returns English -} +``` +┌─────────────────────────────────────────────────────────────────┐ +│ I18N SYSTEMS │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ Shared Locale Configuration: │ +│ 12 locales (en, de, es, fr, id, ja, ko, pt, ru, tr, │ +│ zh-Hans, zh-Hant) │ +│ │ +│ UI TRANSLATIONS (next-intl) │ +│ ├── Uses: translations/{locale}/*.json │ +│ └── Used for: static UI strings │ +│ │ +│ MANIFEST TRANSLATIONS (manifest-i18n.ts) │ +│ ├── Uses: item.translations field │ +│ └── Used for: manifest data (names, descriptions) │ +│ │ +└─────────────────────────────────────────────────────────────────┘ ``` -### 3. Batch Process Multiple Entries +--- -For list pages, use `localizeManifestItems`: +## Translation Coverage -```typescript -import { localizeManifestItems } from '@/lib/manifest-i18n'; +### UI Content ✅ -const localizedTerminals = localizeManifestItems(terminals, locale); -``` +All 12 locales have full UI translation coverage. -## API Reference +### Manifest Data ⚠️ -### `localizeManifestItem(item: T, locale: Locale, fields?: (keyof T)[]): T` +The translation infrastructure is fully implemented, but actual translations need to be added to individual manifest files. Coverage varies by manifest type. -Applies localization to a single manifest entry. +### Adding Manifest Translations -**Parameters:** -- `item` - Manifest entry object -- `locale` - Target language ('en' or 'zh-Hans') -- `fields` - List of fields to translate (optional, defaults to `['description']`) +Include translations for all supported locales in manifest files: -**Returns:** A new object with translations applied +```jsonc +{ + "id": "my-tool", + "name": "My Tool", + "description": "A great development tool", + "translations": { + "zh-Hans": { + "name": "我的工具", + "description": "一个很棒的开发工具" + }, + "zh-Hant": { + "name": "我的工具", + "description": "一個很棒的開發工具" + }, + "de": { + "name": "Mein Werkzeug", + "description": "Ein großartiges Entwicklungswerkzeug" + }, + "es": { + "name": "Mi Herramienta", + "description": "Una gran herramienta de desarrollo" + }, + "fr": { + "name": "Mon Outil", + "description": "Un excellent outil de développement" + }, + "id": { + "name": "Alat Saya", + "description": "Alat pengembangan yang hebat" + }, + "ja": { + "name": "私のツール", + "description": "素晴らしい開発ツール" + }, + "ko": { + "name": "내 도구", + "description": "훌륭한 개발 도구" + }, + "pt": { + "name": "Minha Ferramenta", + "description": "Uma ótima ferramenta de desenvolvimento" + }, + "ru": { + "name": "Мой инструмент", + "description": "Отличный инструмент для разработки" + }, + "tr": { + "name": "Araçım", + "description": "Harika bir geliştirme aracı" + } + } +} +``` -### `localizeManifestItems(items: T[], locale: Locale, fields?: (keyof T)[]): T[]` +--- -Applies localization to an array of manifest entries. +## Key Files -**Parameters:** -- `items` - Array of manifest entries -- `locale` - Target language -- `fields` - List of fields to translate (optional) +| File | Purpose | +|------|---------| +| `src/i18n/config.ts` | Locale configuration | +| `src/i18n/navigation.ts` | Localized Link component | +| `src/i18n/lib-core.ts` | Reference resolution | +| `src/i18n/request.ts` | Request config for next-intl | +| `src/lib/manifest-i18n.ts` | Manifest translation layer | +| `translations/{locale}/` | UI translation files | -**Returns:** A new array with translations applied +--- -### `getLocalizedField(item: T, field: keyof T, locale: Locale): string` +## Best Practices -Gets the localized value of a single field. +### 1. Always Use Localized Link -**Parameters:** -- `item` - Manifest entry object -- `field` - Field name -- `locale` - Target language +```typescript +// ✅ Correct +import { Link } from '@/i18n/navigation' -**Returns:** Localized field value (returns original value if no translation exists) +// ❌ Incorrect +import Link from 'next/link' +``` -## Examples +### 2. Use Translation Keys, Don't Hardcode -### terminals.json Example +```typescript +// ✅ Correct +const tShared = useTranslations('shared') +return -```json -[ - { - "id": "iterm2", - "name": "iTerm2", - "vendor": "George Nachman", - "description": "iTerm2 is a terminal emulator for macOS.", - "i18n": { - "zh-Hans": { - "description": "iTerm2 是一款 macOS 终端模拟器。" - } - } - } -] +// ❌ Incorrect +return ``` -### providers.json Example - -```json -[ - { - "id": "deepseek", - "name": "DeepSeek", - "description": "A leading AI research company focused on developing advanced language models.", - "i18n": { - "zh-Hans": { - "description": "领先的 AI 研究公司，专注于开发先进的语言模型。" - } - } - } -] -``` +### 3. Manifest Translation Fields -## Best Practices +Default translated field is `description`. Other fields can be translated: -1. **Maintain Consistency** - Ensure all entries of the same type have translations for the same languages -2. **Accurate Translation** - Translations should accurately convey the original meaning, avoid over-interpretation -3. **Be Concise** - Descriptions should be brief and easy to understand -4. **Validate JSON** - Ensure JSON format is correct after adding translations -5. **Progressive Addition** - Start by adding translations for important entries, then gradually complete others +```typescript +localizeManifestItem(item, locale, ['name', 'description']) +``` -## Contributing Translations +--- -We welcome contributors to add translations to manifests! +## Related Documentation -1. Fork this project -2. Add `i18n` fields to manifest files -3. Submit a PR describing your translations -4. Wait for review and merge +- `specs.md` - Project specifications +- `COMPONENT-RELATIONSHIP-DIAGRAM.md` - Architecture overview +- `SCHEMA-ARCHITECTURE.md` - Schema system details -## Future Extensions +--- -- Support for more languages (Japanese, Korean, etc.) -- Support for more translatable fields -- Automatic detection of missing translations -- Translation quality check tools +**Version:** 2.0 +**Last Updated:** January 6, 2026 diff --git a/docs/METADATA_OPTIMIZATION.md b/docs/METADATA_OPTIMIZATION.md index 103841f..47f715d 100644 --- a/docs/METADATA_OPTIMIZATION.md +++ b/docs/METADATA_OPTIMIZATION.md @@ -1,331 +1,512 @@ # Metadata & JSON-LD Schema Optimization Implementation -## ✅ Completed - Phase 1: Infrastructure - -### 1. **JSON-LD Schema System** (`src/lib/metadata/schemas/`) - -#### Created Files: -- ✅ `types.ts` - Complete Schema.org type definitions -- ✅ `builders.ts` - Reusable schema builders (15+ functions) -- ✅ `generators.ts` - High-level schema generators with React cache() -- ✅ `validators.ts` - Schema validation and error checking -- ✅ `index.ts` - Unified exports - -#### Key Features: -- **Type-safe**: Full TypeScript support for all Schema.org types -- **DRY Principle**: Eliminate code duplication across pages -- **Cached**: All generators use React `cache()` for performance -- **Validated**: Built-in validation for development environment - -#### Supported Schema Types: -- ✅ Organization -- ✅ Person -- ✅ SoftwareApplication -- ✅ Product -- ✅ ItemList -- ✅ BreadcrumbList -- ✅ Article / TechArticle -- ✅ WebSite (with SearchAction) -- ✅ FAQPage +**Last Updated:** January 6, 2026 + +This document describes the complete metadata and structured data architecture for AI Coding Stack. + +--- + +## Overview + +The metadata system consists of two integrated subsystems: + +1. **Schema System** (`src/lib/metadata/schemas/`) - JSON-LD structured data generation +2. **Metadata System** (`src/lib/metadata/`) - Page metadata (title, description, OpenGraph, etc.) + +Both systems are fully typed, validated, and optimized for SEO. --- -### 2. **Metadata Templates** (`src/lib/metadata/`) +## 1. Schema System (`src/lib/metadata/schemas/`) + +### Architecture -#### Created Files: -- ✅ `templates.ts` - Reusable metadata templates -- ✅ `robots.ts` - Centralized robots configuration -- Enhanced `config.ts` with `SEO_CONFIG` +``` +src/lib/metadata/schemas/ +├── types.ts # Schema.org type definitions +├── builders.ts # Reusable schema builders +├── generators.ts # High-level page-specific generators +├── validators.ts # Schema validation utilities +└── index.ts # Public API surface +``` + +### Supported Schema Types + +| Type | Purpose | +|------|---------| +| Organization | Company/brand info | +| Person | Individual author info | +| SoftwareApplication | IDEs, CLIs, Extensions | +| Product | Models, commercial products | +| ItemList | Category list pages | +| BreadcrumbList | Navigation breadcrumbs | +| FAQPage | Frequently asked questions | +| Article | Blog posts, articles | +| WebSite | Site-wide search/identity | +| Offer | Pricing information | +| AggregateRating | Review ratings | -#### Key Features: -- **Base Templates**: `createBaseMetadata()`, `createPageMetadata()`, `createRootLayoutMetadata()` -- **Robots Config**: Page-type specific robots directives -- **SEO Config**: Site verification, authors, creator, publisher +### Key Functions -#### New Robots Features: -- Default robots with max-image-preview, max-snippet -- No-index for search pages -- Customizable per-page-type +```typescript +// Builders - Low-level schema construction +buildOrganizationSchema() +buildPersonSchema() +buildSoftwareApplicationSchema() +buildProductSchema() +buildItemListSchema() +buildBreadcrumbListSchema() +buildArticleSchema() +buildFAQPageSchema() +buildWebSiteSchema() + +// Generators - High-level page schemas +generateRootOrganizationSchema() +generateWebSiteSchema() +generateFAQPageSchema() +generateSoftwareDetailSchema() +generateModelDetailSchema() +generateListPageSchema() +generateArticleSchema() +generateDocsSchema() +generateVendorSchema() + +// Validators +validateSchema() +validateOrThrow() +validateAndLog() +``` + +**Full documentation:** See [SCHEMA-ARCHITECTURE.md](./SCHEMA-ARCHITECTURE.md) --- -### 3. **Updated Pages** +## 2. Metadata System (`src/lib/metadata/`) + +### Architecture -#### ✅ Root Layout (`app/[locale]/layout.tsx`) -**Changes:** -- Uses `createRootLayoutMetadata()` template -- Generates Organization & WebSite schemas with new generators -- Added title template: `%s - AI Coding Stack` -- Proper OpenGraph locale handling -- Cleaner, more maintainable code +``` +src/lib/metadata/ +├── index.ts # Public API exports +├── config.ts # Site configuration, SEO defaults +├── templates.ts # Metadata template functions +├── generators.ts # High-level metadata generators +├── helpers.ts # Helper functions +└── robots.ts # Robots configuration +``` + +### Directory: `index.ts` + +Main entry point exporting all metadata functionality: + +```typescript +// Exports +export * from './config' +export * from './templates' +export * from './generators' +export * from './helpers' +export * from './robots' +export * from './schemas' +``` + +### Directory: `config.ts` + +Site-wide configuration and SEO defaults: -**Before:** ```typescript -// 120+ lines of hardcoded metadata -const organizationSchema = { - '@context': 'https://schema.org', - // ... manual construction +export const SITE_CONFIG = { + name: 'AI Coding Stack', + url: 'https://aicodingstack.io', + twitter: { + site: '@aicodingstack', + creator: '@aicodingstack', + }, + github: 'https://github.com/aicodingstack/aicodingstack.io', +} + +export const METADATA_DEFAULTS = { + siteName: 'AI Coding Stack', + description: 'Comprehensive directory for AI coding tools...', + currentYear: new Date().getFullYear(), } ``` -**After:** +### Directory: `robots.ts` + +Centralized robots configuration: + ```typescript -// Clean, generated schemas -const organizationSchema = await generateRootOrganizationSchema() -const websiteSchema = await generateWebSiteSchema() +export const DEFAULT_ROBOTS = { + index: true, + follow: true, + googleBot: { + index: true, + 'max-image-preview': 'large', + 'max-snippet': -1, + 'max-video-preview': -1, + }, +} + +// Get robots by page type +export function getPageRobots(pageType: PageType): Metadata['robots'] ``` ---- +### Directory: `templates.ts` -#### ✅ Homepage (`app/[locale]/page.tsx`) -**Changes:** -- FAQ schema now uses `generateFAQPageSchema()` -- Cleaner code, same functionality +Metadata template functions: ---- +```typescript +// Create base metadata structure +export function createBaseMetadata(...): Metadata -#### ✅ CLIs Detail Page (`app/[locale]/clis/[slug]/page.tsx`) -**Changes:** -- Schema generation using `generateSoftwareDetailSchema()` -- ~30 lines of schema code → ~15 lines -- Type-safe, validated, cached +// Create page metadata with robots rules +export function createPageMetadata(...): Metadata ---- +// Create root layout metadata +export function createRootLayoutMetadata(...): Metadata +``` + +### Directory: `helpers.ts` -## 📊 Statistics +Helper functions for building metadata components: -### Code Reduction: -- **Root Layout**: 120 lines → 70 lines (42% reduction) -- **CLIs Detail**: ~30 lines schema → ~15 lines (50% reduction) -- **Total Schema Code**: ~200 lines → ~100 lines across migrated pages +```typescript +// Build alternates (canonical + hreflang) +export function buildAlternates(...) -### Files Created: -- 7 new files in `src/lib/metadata/schemas/` -- 2 new files in `src/lib/metadata/` -- 1,500+ lines of reusable, type-safe infrastructure +// Build OpenGraph metadata +export function buildOpenGraph(...) ---- +// Build Twitter Card metadata +export function buildTwitterCard(...) -## 🎯 Benefits Achieved +// BuildSEO-optimized titles +export function buildDetailPageTitle(...) +export function buildListPageTitle(...) -### 1. **DRY Principle** -- ✅ All schema logic centralized -- ✅ Single source of truth for schema generation -- ✅ Easy to update globally +// Build descriptions +export function buildProductDescription(...) -### 2. **Type Safety** -- ✅ Full TypeScript coverage -- ✅ Compiler catches errors -- ✅ IDE autocomplete support +// Build keywords +export function buildKeywords(...) -### 3. **Performance** -- ✅ React `cache()` prevents duplicate data fetching -- ✅ Metadata + page component use same cached data +// Format utilities +export function formatPlatforms(...) +export function formatPriceForDescription(...) +``` -### 4. **SEO Improvements** -- ✅ Complete metadata on all pages -- ✅ Proper robots directives -- ✅ Title templates -- ✅ Structured data validation +### Directory: `generators.ts` -### 5. **Developer Experience** -- ✅ New pages: just call generator function -- ✅ Validation in development mode -- ✅ Clear error messages -- ✅ Comprehensive documentation +High-level metadata generators for different page types: + +```typescript +// List pages (ides, clis, models, etc.) +export async function generateListPageMetadata(options: { + locale: Locale + category: Category + translationNamespace: string + additionalKeywords?: string[] +}): Promise + +// Software product detail pages (ides, clis, extensions) +export async function generateSoftwareDetailMetadata(options: { + locale: Locale + category: Category + slug: string + product: { name, description, vendor, platforms?, pricing?, license? } + typeDescription: string +}): Promise + +// Model detail pages +export async function generateModelDetailMetadata(options: { + locale: Locale + slug: string + model: { name, description, vendor, size?, contextWindow?, maxOutput?, tokenPricing? } + translationNamespace: string +}): Promise + +// Comparison pages +export async function generateComparisonMetadata(...) + +// Article pages +export async function generateArticleMetadata(...) + +// Documentation pages +export async function generateDocsMetadata(...) + +// Static pages (home, manifesto, etc.) +export async function generateStaticPageMetadata(...) +``` --- -## 📝 Migration Guide +## 3. Integration Patterns -### For Detail Pages (IDEs, Extensions, Models, etc.) +### Root Layout -**Before:** ```typescript -// Manual schema construction -const schema = { - '@context': 'https://schema.org', - '@type': 'SoftwareApplication', - name: product.name, - // ... 30+ lines of manual mapping +// src/app/[locale]/layout.tsx +import { createRootLayoutMetadata } from '@/lib/metadata' +import { generateRootOrganizationSchema, generateWebSiteSchema } from '@/lib/metadata/schemas' + +export async function generateMetadata({ params }): Promise { + const { locale } = await params + const messages = await getMessages({ locale }) + + return createRootLayoutMetadata({ + locale, + title: messages.site.title, + description: messages.site.description, + keywords: ['AI coding tools', 'AI IDE', 'AI CLI'].join(', '), + canonical: locale === defaultLocale ? '/' : `/${locale}`, + languageAlternates: buildLanguageAlternates(''), + openGraph: { + type: 'website', + locale: mapLocaleToOG(locale), + alternateLocale: locales.filter(l => l !== locale).map(mapLocaleToOG), + // Images auto-detected from opengraph-image.tsx + }, + twitter: { + card: 'summary_large_image', + // Images auto-detected from opengraph-image.tsx + }, + }) } + +const organizationSchema = await generateRootOrganizationSchema() +const websiteSchema = await generateWebSiteSchema() + +return ( + + + + + + +) ``` -**After:** +### Detail Page (Software) + ```typescript +// src/app/[locale]/ides/[slug]/page.tsx import { generateSoftwareDetailSchema } from '@/lib/metadata/schemas' +import { generateSoftwareDetailMetadata } from '@/lib/metadata' + +export async function generateMetadata({ params }): Promise { + const { locale, slug } = await params + const ide = await getManifestEntry('ides', slug) + + return generateSoftwareDetailMetadata({ + locale, + category: 'ides', + slug: ide.slug, + product: { + name: ide.name, + description: ide.description, + vendor: ide.vendor, + platforms: ide.platforms, + pricing: ide.pricing, + license: ide.license, + }, + typeDescription: 'AI-Powered IDE', + }) +} const schema = await generateSoftwareDetailSchema({ - product: { - name: product.name, - description: product.description, - vendor: product.vendor, - // ... simple data object - }, + product: ide, category: 'ides', locale, }) -``` -### For List Pages +return <>{/* page content */} +``` -Add ItemList schema: +### List Page ```typescript +// src/app/[locale]/ides/page.tsx import { generateListPageSchema } from '@/lib/metadata/schemas' +import { generateListPageMetadata } from '@/lib/metadata' + +export async function generateMetadata({ params }): Promise { + const { locale } = await params + + return generateListPageMetadata({ + locale, + category: 'ides', + translationNamespace: 'pages.ides', + }) +} const schema = await generateListPageSchema({ - items: products.map(p => ({ - id: p.id, - name: p.name, - description: p.description, + items: ides.map(ide => ({ + name: ide.name, + url: `${baseUrl}/ides/${ide.slug}`, + description: ide.description, })), - category: 'ides', - locale, - translationNamespace: 'pages.ides', + itemName: 'IDEs', + itemDescription: 'AI-powered code editors', }) -return ( - <> - - {/* ... page content */} - -) +return <>{/* page content */} ``` --- -## 🚀 Next Steps (Phase 2) - -### Remaining Migrations: - -#### Detail Pages (Priority: High) -- [ ] IDEs detail page (`app/[locale]/ides/[slug]/page.tsx`) -- [ ] Extensions detail page (`app/[locale]/extensions/[slug]/page.tsx`) -- [ ] Models detail page (`app/[locale]/models/[slug]/page.tsx`) -- [ ] Model Providers detail page (`app/[locale]/model-providers/[slug]/page.tsx`) -- [ ] Vendors detail page (`app/[locale]/vendors/[slug]/page.tsx`) - -**Migration Template:** -```typescript -// 1. Import generator -import { generateSoftwareDetailSchema } from '@/lib/metadata/schemas' - -// 2. Replace manual schema with generator -const schema = await generateSoftwareDetailSchema({ - product: { ... }, - category: 'ides', // or 'extensions', etc. - locale, -}) -``` +## 4. Features Implemented + +### Canonical URLs +- ✅ Automatically generated for all pages +- ✅ Respects locale structure +- ✅ Consistent across all page types + +### Language Alternates (hreflang) +- ✅ Generated for all locales (en, zh-Hans, de, ko) +- ✅ Based on canonical path + +### OpenGraph +- ✅ Complete metadata for all pages +- ✅ Locale-aware og:locale +- ✅ Auto-detected images from `opengraph-image.tsx` files +- ✅ Article type for detail pages, website for others + +### Twitter Cards +- ✅ Summary large image cards +- ✅ Auto-detected images from `opengraph-image.tsx` files +- ✅ Consistent with OpenGraph metadata + +### Structured Data +- ✅ Organization schema on root layout +- ✅ WebSite schema with search action +- ✅ FAQPage schema on homepage +- ✅ SoftwareApplication schema for IDEs/CLIs/Extensions +- ✅ Product schema for Models +- ✅ BreadcrumbList schema on detail pages +- ✅ ItemList schema on list pages +- ✅ Article schema for articles/docs + +### Robots Configuration +- ✅ Default robots with max-preview settings +- ✅ Page-type aware (no-index for search pages) +- ✅ Customizable per page + +### Performance +- ✅ All generators use React `cache()` +- ✅ No duplicate data fetching +- ✅ Efficient schema building --- -#### List Pages (Priority: Medium) -- [ ] IDEs list page -- [ ] CLIs list page -- [ ] Extensions list page -- [ ] Models list page -- [ ] Model Providers list page -- [ ] Vendors list page - -**Add ItemList schema to each:** -```typescript -const listSchema = await generateListPageSchema({ ... }) -``` +## 5. Migration Status + +### Schema Migration - COMPLETE ✅ + +| Page Type | Schema Generator | Status | +|-----------|------------------|--------| +| Root Layout | `generateRootOrganizationSchema`, `generateWebSiteSchema` | ✅ Done | +| Homepage | `generateFAQPageSchema` | ✅ Done | +| IDE Detail | `generateSoftwareDetailSchema` | ✅ Done | +| CLI Detail | `generateSoftwareDetailSchema` | ✅ Done | +| Extension Detail | `generateSoftwareDetailSchema` | ✅ Done | +| Model Detail | `generateModelDetailSchema` | ✅ Done | +| List Pages | `generateListPageSchema` | ✅ Done | +| Articles | `generateArticleSchema` | ✅ Done | +| Docs | `generateDocsSchema` | ✅ Done | +| Vendors | `generateVendorSchema` | ✅ Done | + +### Metadata Migration - COMPLETE ✅ + +All pages use the new metadata generators: +- ✅ Root layout metadata generator +- ✅ List page metadata generator +- ✅ Software detail metadata generator +- ✅ Model detail metadata generator +- ✅ Article metadata generator +- ✅ Docs metadata generator +- ✅ Comparison metadata generator +- ✅ Static page metadata generator --- -#### Article/Docs Pages (Priority: Low) -- [ ] Articles detail page -- [ ] Docs detail page +## 6. Code Statistics -**Use Article/TechArticle schema:** -```typescript -import { generateArticleSchema, generateDocsSchema } from '@/lib/metadata/schemas' -``` +### Infrastructure Created ---- +| Destination | Size | +|-------------|------| +| Schema types, builders, generators, validators | ~1,500 lines | +| Metadata config, templates, generators, helpers | ~1,200 lines | +| Total reusable infrastructure | ~2,700 lines | -### Testing & Validation (Priority: High) +### Code Reduction -#### 1. **Development Validation** -```bash -npm run dev -# Check console for schema validation warnings -``` +| Page Type | Before | After | Reduction | +|-----------|--------|-------|-----------| +| Root Layout | ~150 lines | ~75 lines | 50% | +| Detail Page Schema | ~40 lines | ~8 lines | 80% | +| Detail Page Metadata | ~30 lines | ~12 lines | 60% | -#### 2. **Google Rich Results Test** -- Test each page type -- Verify structured data is recognized -- https://search.google.com/test/rich-results +--- -#### 3. **Schema.org Validator** -- Validate schema markup -- https://validator.schema.org/ +## 7. Benefits + +### SEO Improvements +- ✅ Complete structured data on all pages +- ✅ Rich snippet eligibility +- ✅ Proper canonical URLs +- ✅ Language alternates for i18n +- ✅ Optimized robots directives +- ✅ Social media preview cards + +### Developer Experience +- ✅ Type-safe throughout +- ✅ Single function call for complete metadata +- ✅ Consistent implementation across pages +- ✅ Easy to extend for new page types +- ✅ Validation in development mode -#### 4. **Search Console** -- Monitor structured data coverage -- Check for errors/warnings -- https://search.google.com/search-console +### Performance +- ✅ Cached data fetching +- ✅ No duplicate queries +- ✅ Efficient schema building --- -## 📚 Usage Examples +## 8. Usage Examples -### Example 1: Software Product Schema -```typescript -const schema = await generateSoftwareDetailSchema({ - product: { - name: 'Cursor', - description: 'AI-first code editor', - vendor: 'Anysphere', - websiteUrl: 'https://cursor.sh', - downloadUrl: 'https://cursor.sh/download', - version: '0.42.0', - platforms: [{ os: 'macOS' }, { os: 'Windows' }], - pricing: [ - { name: 'Free', value: 0, currency: 'USD' }, - { name: 'Pro', value: 20, currency: 'USD', per: 'month' }, - ], - license: 'Proprietary', - }, - category: 'ides', - locale: 'en', -}) -``` +### Add Metadata to New Page -### Example 2: FAQ Schema ```typescript -const schema = await generateFAQPageSchema([ - { - question: 'What is AI Coding Stack?', - answer: 'A comprehensive directory for AI coding tools...', - }, - // ... more FAQs -]) +import { generateStaticPageMetadata } from '@/lib/metadata' + +export async function generateMetadata({ params }): Promise { + return generateStaticPageMetadata({ + locale: params.locale, + basePath: 'new-page', + title: 'New Page Title', + description: 'Page description for SEO', + keywords: 'keyword1, keyword2', + ogType: 'website', + pageType: 'static', + }) +} ``` -### Example 3: Article Schema +### Custom Schema + ```typescript -const schema = await generateArticleSchema({ - article: { - title: 'Getting Started with AI Coding', - description: 'Learn how to use AI coding tools', - slug: 'getting-started', - date: '2025-01-15', - author: 'AI Coding Stack Team', - }, - locale: 'en', - type: 'Article', +import { buildOrganizationSchema } from '@/lib/metadata/schemas' + +const customOrgSchema = buildOrganizationSchema({ + name: 'My Company', + url: 'https://example.com', + description: 'Description here', }) ``` ---- - -## 🔧 Development Tools +### Validate Schema -### Enable Schema Validation ```typescript import { validateAndLog } from '@/lib/metadata/schemas' @@ -333,51 +514,38 @@ const schema = await generateSoftwareDetailSchema({ ... }) validateAndLog(schema, 'IDE Detail Page') ``` -### Custom Robots Configuration -```typescript -import { getCustomRobots } from '@/lib/metadata' +--- -const robots = getCustomRobots({ - index: false, - follow: true, - maxImagePreview: 'large', -}) -``` +## 9. Testing & Validation ---- +### Verification Steps -## 📖 References +1. **Schema Validation** +```bash +npm run dev +# Check console for schema validation warnings +``` -- [Next.js Metadata API](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) -- [Schema.org Documentation](https://schema.org/) -- [Google Search Central - Structured Data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data) -- [Project CLAUDE.md](./CLAUDE.md) - Project guidelines +2. **Google Rich Results Test** +- https://search.google.com/test/rich-results ---- +3. **Schema.org Validator** +- https://validator.schema.org/ -## 🎉 Summary +4. **Search Console** +- https://search.google.com/search-console +- Monitor structured data coverage -### What We Built: -1. **Complete JSON-LD Schema System** - Type-safe, validated, cached -2. **Metadata Templates** - Reusable, consistent across all pages -3. **Robots Configuration** - Centralized, page-type aware -4. **Migration Examples** - Root layout, homepage, CLIs detail page +--- -### Impact: -- **50% code reduction** in schema generation -- **100% type safety** with TypeScript -- **Unified system** for all pages -- **Better SEO** with complete structured data -- **Faster development** for new pages +## 10. References -### Next Actions: -1. Migrate remaining detail pages (5 pages) -2. Add ItemList schemas to list pages (6 pages) -3. Add Article schemas to content pages (2 pages) -4. Test and validate with Google tools -5. Monitor Search Console for improvements +- [SCHEMA-ARCHITECTURE.md](./SCHEMA-ARCHITECTURE.md) - Schema system documentation +- [Next.js Metadata API](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) +- [Schema.org Documentation](https://schema.org/) +- [Google Search Central - Structured Data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data) --- -**Status**: Phase 1 Complete ✅ -**Ready for**: Phase 2 Migration 🚀 +**Status**: Complete ✅ +**Date**: January 6, 2026 diff --git a/docs/MODEL_BENCHMARK_REFERENCE.md b/docs/MODEL_BENCHMARK_REFERENCE.md new file mode 100644 index 0000000..a9de093 --- /dev/null +++ b/docs/MODEL_BENCHMARK_REFERENCE.md @@ -0,0 +1,7 @@ +SWE-bench：https://www.swebench.com +Terminal-Bench：https://www.tbench.ai/leaderboard/terminal-bench/2.0 +MMMU：https://mmmu-benchmark.github.io/#leaderboard +MMMU-Pro：https://mmmu-benchmark.github.io/#leaderboard +WebDev Arena：https://web.lmarena.ai/leaderboard +SciCode：https://scicode-bench.github.io/leaderboard/ +LiveCodeBench：https://livecodebench.github.io/leaderboard.html diff --git a/docs/MODEL_SPEC_REFERENCE.md b/docs/MODEL_SPEC_REFERENCE.md new file mode 100644 index 0000000..237d657 --- /dev/null +++ b/docs/MODEL_SPEC_REFERENCE.md @@ -0,0 +1,23 @@ +# Model Spec Reference + +## Foundation Model Providers + +| Provider | Model List | Model Detail | +|----------|------------|-------------| +| Alibaba Cloud | https://help.aliyun.com/zh/dashscope/developer-reference/tongyiqianwen-large-language-models | https://help.aliyun.com/zh/dashscope/developer-reference/tongyiqianwen-large-language-models#`{modelId}` | +| Anthropic | https://platform.claude.com/docs/en/about-claude/models/overview | | +| DeepSeek | https://platform.deepseek.com/api-docs/zh-cn/ | https://platform.deepseek.com/api-docs/zh-cn/ | +| Google AI | https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models | https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro | +| Meta AI | https://llama.meta.com/docs/models/ | https://llama.meta.com/docs/models/`{modelId}` | +| MiniMax | https://platform.minimaxi.com/document/LLM/introduction | https://platform.minimaxi.com/document/LLM/introduction | +| Moonshot | https://platform.moonshot.ai/docs | - | +| OpenAI | https://platform.openai.com/docs/models | https://platform.openai.com/docs/models/gpt-5.2 | +| xAI | https://docs.x.ai/docs/models | https://docs.x.ai/docs | +| Z.ai | https://docs.z.ai | - | + +## Model Service Providers + +| Provider | Model List | Model Detail | +|----------|------------|-------------| +| OpenRouter | https://openrouter.ai/models | https://openrouter.ai/models/`{modelId}` | +| SiliconFlow | https://docs.siliconflow.cn/Models | - | diff --git a/docs/ORIGINAL-SPECS.md b/docs/ORIGINAL-SPECS.md new file mode 100644 index 0000000..e9b66af --- /dev/null +++ b/docs/ORIGINAL-SPECS.md @@ -0,0 +1,24 @@ +AI Coding Stack - Your AI Coding Ecosystem Hub + +This project is the AI Coding Stack website (aicodingstack.io), serving as a comprehensive directory for AI coding tools, and also provides open-source metadata for the AI coding ecosystem (available for community contributions from developers). + + + +# Metadata +In the ides.jsonc file, define all mainstream Coding IDE information with the following fields: +name, logo id, vendor, description, website url, docs url, latest version +IDEs include: VS Code, Cursor, TRAE + +In the clis.jsonc file, define all mainstream Coding CLI information with the following fields: +name, logo id, vendor, description, website url, docs url, latest version +CLIs include: Codex, Claude Code + +name, logo id, vendor, description, website url, docs url, latest version + +In the models.jsonc file, define all mainstream Coding LLM information with the following fields: +name, logo id, size, total context, max output, pricing, artificial analysis url, openrouter url +Models include: Kimi K2 0905, DeepSeek V3.1, GLM 4.5, Qwen3 Coder + +In the providers.jsonc file, define all mainstream LLM Providers information with the following fields: +name, logo id, description, website url, docs url +Providers include: DeepSeek, Moonshot, SiliconFlow, OpenRouter, Z.ai diff --git a/docs/PERFORMANCE_AUDIT.md b/docs/PERFORMANCE_AUDIT.md index ddbde16..220dab2 100644 --- a/docs/PERFORMANCE_AUDIT.md +++ b/docs/PERFORMANCE_AUDIT.md @@ -2,1132 +2,339 @@ ## aicodingstack.io Project **Audit Date:** October 6, 2025 -**Next.js Version:** 15.4.6 +**Last Updated:** January 6, 2026 +**Next.js Version:** 15.5.9 **Build Time:** ~2 seconds -**Total Static Pages:** 28 -**Build Size:** 176 MB +**Total Static Pages:** 100+ +**Build Size:** ~180 MB --- ## Executive Summary -### 🟢 Strengths -- Excellent use of Static Site Generation (SSG) -- Small First Load JS bundles (~99-109 KB) -- Fast build times (2 seconds) -- Good server component adoption -- Proper font optimization with `next/font` - -### 🔴 Critical Issues -1. **Excessive client-side JavaScript** - Too many `'use client'` directives -2. **Missing cache configuration** - No revalidation strategies -3. **ThemeProvider causes flash** - Blocks initial render -4. **Large manifest imports** - 38KB JSON imported into client bundles -5. **No bundle analyzer** - Missing optimization visibility -6. **Missing image optimization** - Not using `next/image` - -### 📊 Performance Impact Estimate -- **Potential LCP improvement:** 30-50% (by fixing ThemeProvider) -- **JS bundle reduction:** ~25-35KB (by moving pages to server components) -- **Build time savings:** Minimal (already fast) +### 🟢 Current Status: Production-Ready ---- - -## 1. Rendering Strategy Analysis - -### ✅ What's Working Well -- **Static Generation:** All 28 pages properly use SSG via `generateStaticParams()` -- **Server Components:** Dynamic routes (articles, docs, IDE details) are server components -- **Build Output:** Clean separation of static (○) and SSG (●) pages - -### ❌ Critical Problems - -#### Problem 1.1: Unnecessary Client Components -**Location:** 8 out of 13 page files use `'use client'` unnecessarily - -**Affected Files:** -``` -src/app/page.tsx ← Homepage -src/appides/page.tsx ← IDE listing -src/appmodels/page.tsx ← Models listing -src/appterminals/page.tsx ← Terminals listing -src/appclis/page.tsx ← CLIs listing -src/appmodel-providers/page.tsx -src/app/curated-collections/page.tsx -``` - -**Impact:** -- Forces entire page to be client-rendered -- Adds 43.5-54.1 KB of unnecessary React runtime to each page -- Prevents optimal streaming and Suspense benefits -- Increases Time to Interactive (TTI) - -**Root Cause:** -- Homepage: Only needs `'use client'` for copy button state -- Listing pages: Import JSON directly (should be server-side only) - -**Fix (High Priority):** -```tsx -// ❌ BEFORE: src/app/page.tsx -'use client'; -import { useState } from 'react'; - -export default function Home() { - const [copied, setCopied] = useState(false); - // ... entire page -} +This audit document originally outlined several performance concerns. Through systematic implementation, **all critical and high-priority issues have been resolved**. -// ✅ AFTER: Split into server + client components -// src/app/page.tsx (Server Component) -import Header from '@/components/Header'; -import Footer from '@/components/Footer'; -import HeroSection from '@/components/home/HeroSection'; -import FeaturesSection from '@/components/home/FeaturesSection'; -import FAQSection from '@/components/home/FAQSection'; - -export default function Home() { - return ( - <> -
- - - -