# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **translation repository** for Claude Code documentation, focusing on translating English technical documentation into Chinese. The repository maintains source documents in `/source/` and their translated versions in `/translated/`.

**Primary languages:**
- Source: English
- Target: Chinese (Simplified)

## Repository Structure

```
translation/
├── source/                     # Original English documents
│   ├── documents/             # Markdown documentation
│   │   ├── awesome-claude-code.md
│   │   ├── claude-code-infrastructure-showcase/
│   │   ├── newsminimalist/
│   │   └── wirelesswire/
│   └── assets/                # Images, SVGs, other resources
├── translated/                 # Chinese translations
│   ├── documents/             # Translated markdown files
│   │   ├── awesome-claude-code.md (translated)
│   │   ├── claude-code-infrastructure-showcase/ (translated)
│   │   └── ...
│   └── assets/                # Translated resources
├── references/                 # Translation resources
│   ├── glossary/              # Term glossary
│   │   └── glossary.md        # English-Chinese term pairs
│   ├── style-guide.md         # Translation style guidelines
│   └── resources/             # Reference materials
├── reviews/                    # Review records
│   ├── review-001.md         # Translation review notes
│   └── feedback.md           # Feedback and improvements
├── .claude/                   # Claude Code configuration
│   └── settings.local.json
├── CLAUDE.md                  # This file
└── README.md                  # Project description
```

## Key Documents

### `/references/glossary/glossary.md`
Maintains consistent terminology throughout translations. Always check here first when translating technical terms.

### `/references/style-guide.md`
Defines translation style standards, tone, and language preferences for this project.

### `/translated/[path]/[file].md` and `/source/[path]/[file].md`
**Critical**: Always maintain the exact same directory structure and filename between source and translated documents. Only the language changes, not the structure.

## Translation Architecture

This repository uses a **simple directory mirroring** pattern:
- Source files in `/source/` → Translated files in `/translated/`
- One-to-one mapping: `/source/documents/a/b/c.md` → `/translated/documents/a/b/c.md`

**No complex build tools or frameworks** - just Markdown files organized by language.

## Translation Principles

When working with translations:

1. **Accuracy**: Stay faithful to the original meaning
2. **Fluency**: Use natural Chinese expressions  
3. **Consistency**: Use uniform terminology throughout
4. **Context adaptation**: Adjust tone for Chinese technical readers
5. **Format preservation**: All Markdown formatting, code blocks, links, and images must be preserved exactly

## Common Workflows

### Translating a new document:
1. Read the source document in `/source/documents/`
2. Create translated version in `/translated/documents/` with same structure
3. Reference `/references/glossary/glossary.md` for term consistency
4. Update `/reviews/` with translation notes

### Updating an existing translation:
1. Compare source and translated files to identify changes
2. Apply updates following the same translation principles
3. Mark updated sections in review notes

### Finding term translations:
- **Always check** `/references/glossary/glossary.md` before translating any technical term
- Maintain consistency across all translated files
- Add new terms to the glossary when encountered

## Development Tasks

### No Build System Required
This is a documentation project. Documents are plain Markdown files. There is no:
- Build process
- Test suite
- Linting configuration
- Compilation step

Simply edit Markdown files directly.

### Adding new documents:
- Place English source in `/source/documents/[category]/`
- Create Chinese translation in `/translated/documents/[category]/`
- Maintain identical directory structure
- Update git history with descriptive commit messages

### Updating translations:
1. Read both source and translated files
2. Identify changed sections in source
3. Update corresponding sections in translation
4. Verify formatting and links are preserved

## Important Workflow Notes

1. **Directory mirroring is sacred**: Never change the directory structure between source and translation
2. **Terminology consistency**: Before translating any technical term, check the glossary
3. **Format preservation**: Markdown tables, code blocks, links, and images must be preserved exactly
4. **Review process**: Significant translations should be documented in `/reviews/`
5. **Version control**: Use meaningful commit messages describing what was translated or updated

## Working with Claude Code

When assisting with this repository, Claude Code should:
- Read source documents before creating translations
- Always check the glossary before translating technical terms
- Preserve all Markdown formatting
- Maintain consistent terminology across all files
- Document translation decisions when they're non-obvious

## Quick Reference

- **Translate new doc**: Copy structure from `/source/` → `/translated/`, maintain directory paths
- **Find term translation**: Check `/references/glossary/glossary.md`
- **Style questions**: Refer to `/references/style-guide.md`
- **Document decisions**: Add notes to `/reviews/` when making significant translation choices

## Version Control

Commit message format:
```
[类型]: 简要描述

详细说明：
- 变更内容
- 涉及文件
- 注意事项

版本：vX.Y
翻译者：[姓名]
日期：[YYYY-MM-DD]
```

Change types:
- `feat`: New translation content
- `fix`: Correct translation errors
- `update`: Update existing translations
- `review`: Review modifications
- `style`: Format or style adjustments

---

**Last Updated**: 2025-11-20
**Purpose**: Guide Claude Code instances working with this translation repository