MicroFish/.kiro/specs/i18n-translate-backend-comments/requirements.md

# Requirements Document

## Introduction
This specification covers the developer-facing internationalization of `backend/` Python source: translating Chinese docstrings and inline comments to English so that English-speaking maintainers can read and review the code without translation overhead. The change is mechanical — no behavior, no public strings, no symbol names are modified. It is one of several i18n tickets (#2, #3, #4, #5, #6, #7); this spec covers ticket #7 only.

## Boundary Context
- **In scope**: Translation of Chinese-language characters that appear in Python docstrings (module/class/function) and inline `#` comments under `backend/`. Removal of comments that merely restate the code. Preservation of `TODO:` / `FIXME:` markers and embedded ticket references.
- **Out of scope**: Chinese characters inside string literals (prompt templates, `logger.{info,warning,error}` arguments, API response bodies, error messages returned to clients) — these are tracked separately by issues #2/#3/#4/#5/#6. No refactoring, reformatting, renaming, or behavior changes.
- **Adjacent expectations**: Spec `i18n-externalize-backend-logs` (issue #6) and the prompt-translation specs handle string-literal Chinese; this spec must leave those untouched so the other tickets remain mergeable.

## Requirements

### Requirement 1: Translation Coverage of In-Scope Files
**Objective:** As a maintainer, I want every Chinese docstring and inline comment in the in-scope backend files translated to English, so that I can read and review the code without translation tools.

#### Acceptance Criteria
1. The Backend Codebase shall contain no Chinese characters (Unicode range U+4E00–U+9FFF) inside Python docstrings under `backend/app/__init__.py`, `backend/app/config.py`, `backend/app/models/`, `backend/app/services/`, `backend/app/api/`, `backend/app/utils/`, `backend/run.py`, and `backend/scripts/`.
2. The Backend Codebase shall contain no Chinese characters inside Python `#` inline comments under the same paths.
3. When `grep -rln '[一-鿿]' backend/ --include='*.py'` is run after this change, the Backend Codebase shall return only files whose remaining Chinese is contained within string literals owned by issues #2/#3/#4/#5/#6.
4. When a docstring is translated, the Translator shall preserve Google-style docstring shape (`Args:`, `Returns:`, `Raises:`, `Yields:` sections) per `dev-guidelines.md`.

### Requirement 2: Preservation of Code Behavior
**Objective:** As a maintainer, I want the translation to be comments-and-docstrings-only, so that runtime behavior is provably unchanged.

#### Acceptance Criteria
1. The Translator shall not modify any executable Python statement (assignments, function calls, control flow, decorators, imports).
2. The Translator shall not modify any Python string literal (single-, double-, triple-quoted, f-string, raw, byte) regardless of whether it contains Chinese characters.
3. The Translator shall not rename any symbol (variable, function, class, module, parameter).
4. When `uv run python -m pytest backend/scripts/test_profile_format.py` is run after the change, the Backend Codebase shall exit with status 0.
5. If a diff line touches any non-comment, non-docstring code, the Translator shall reject that diff hunk and revise.

### Requirement 3: Comment Quality Hygiene
**Objective:** As a maintainer, I want translated comments to add value, so that the codebase remains easy to read after the migration.

#### Acceptance Criteria
1. When a Chinese comment merely restates the immediately following code (e.g. `# 初始化客户端` above `client = Client()`), the Translator shall delete the comment rather than translate it.
2. When a Chinese comment captures non-obvious *why* (constraints, workarounds, invariants), the Translator shall translate it to a faithful English equivalent.
3. The Translator shall preserve any `TODO:` / `FIXME:` marker and any embedded ticket reference (e.g. `#1234`, `PROJ-456`) verbatim within the translated comment.
4. The Translator shall not introduce new comments that did not exist (or had no Chinese equivalent) in the original source.

### Requirement 4: Style and Format Compliance
**Objective:** As a maintainer, I want the translated output to comply with project style rules, so that no follow-up cleanup PR is needed.

#### Acceptance Criteria
1. The Translator shall keep all translated docstrings and comments at or below 120 characters per line.
2. The Translator shall not introduce trailing whitespace on any line.
3. The Translator shall preserve the original indentation (tabs/spaces) of every comment and docstring.
4. The Translator shall use double quotes for any docstring it rewrites, matching the existing Python convention in the file.
5. Where a file already uses 4-space indentation, the Translator shall preserve that indentation.

### Requirement 5: Discovery and Verification Workflow
**Objective:** As a reviewer, I want a reproducible discovery and verification workflow, so that I can confirm coverage and absence of regressions in CI or locally.

#### Acceptance Criteria
1. The Translator shall enumerate candidate files using `grep -rln '[一-鿿]' backend/ --include='*.py'` before beginning work.
2. The Translator shall re-run the same `grep` after each batch and confirm the residual hits are limited to string-literal Chinese owned by adjacent tickets (#2/#3/#4/#5/#6).
3. When the residual `grep` hits include any non-string-literal Chinese, the Translator shall classify those hits as in-scope and continue translation until they are gone.
4. The Translator shall verify that `git diff --stat` only reports changes inside the in-scope file paths listed in Requirement 1.

### Requirement 6: Tracking and Branching
**Objective:** As a release manager, I want the work tracked against ticket #7 on a dedicated branch, so that the PR remains scoped and traceable.

#### Acceptance Criteria
1. The Translator shall produce changes on a branch named `docs/i18n-7-translate-backend-comments`.
2. The Translator shall reference issue `salestech-group/MiroFish#7` in commit messages or PR description.
3. When committing, the Translator shall use Conventional Commits with type `docs` and scope `i18n` (e.g. `docs(i18n): translate chinese docstrings/comments in backend/<area>`).
4. The Translator shall not include unrelated changes (e.g. dependency bumps, config changes, refactors) in the resulting PR.