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

Implementation Plan

Foundation

• 1. Establish baseline and working branch
• 1.1 Create translation working branch and capture baseline state
  • Create branch docs/i18n-7-translate-backend-comments from main.
  • Capture the baseline residual hits by running the discovery scan (the regex [一-鿿] against backend/**/*.py, excluding .venv); record the file list as the work queue.
  • Run cd backend && uv run python -m pytest scripts/test_profile_format.py and confirm a green baseline before any edits.
  • Observable: a fresh branch exists, the baseline file list of 37 in-scope files is captured, and the baseline pytest run passes.
  • Requirements: 5.1, 6.1

Core — Per-Package Translation

• 2. Translate Chinese docstrings and inline comments per package

• 2.1 (P) Translate backend/app/models/

  • Translate Chinese module/class/function docstrings and # comments in backend/app/models/__init__.py, backend/app/models/project.py, and backend/app/models/task.py.
  • Apply the docstring-vs-value disambiguation rule (first-statement only) so that no string literal is touched.
  • Apply the Google-style key map (参数: → Args:, 返回: → Returns:, 异常: → Raises:, 产生:/生成: → Yields:, 示例: → Examples:, 注意:/备注: → Note:).
  • Drop comments that merely restate the next executable line; preserve TODO:/FIXME: and any embedded ticket reference verbatim.
  • Re-run the residual scan and confirm backend/app/models/ no longer has Chinese in non-string-literal positions.
  • Re-run cd backend && uv run python -m pytest scripts/test_profile_format.py and confirm exit 0.
  • Observable: zero non-string-literal Chinese remains in backend/app/models/*.py, and the test command exits 0.
  • Requirements: 1.1, 1.2, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 4.5
  • Boundary: backend/app/models/

• 2.2 (P) Translate backend/app/utils/

  • Translate Chinese docstrings and # comments in backend/app/utils/__init__.py, file_parser.py, llm_client.py, locale.py, logger.py, retry.py, and zep_paging.py.
  • Be especially careful with locale.py and logger.py: they intentionally route Chinese strings through their value paths; only docstrings and # comments are in scope.
  • Apply Rules 1–5 from design.md (disambiguation, key map, comment hygiene, style, preservation).
  • Re-run the residual scan and confirm backend/app/utils/ no longer has Chinese in non-string-literal positions.
  • Re-run the pytest command and confirm exit 0.
  • Observable: zero non-string-literal Chinese remains in backend/app/utils/*.py, and the test command exits 0.
  • Requirements: 1.1, 1.2, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 4.5
  • Boundary: backend/app/utils/

• 2.3 (P) Translate backend/app/services/ — complete (all 12 files; finished in this installment)

  • Translate Chinese docstrings and # comments across all 12 service files: __init__.py, graph_builder.py, ontology_generator.py, oasis_profile_generator.py, report_agent.py, simulation_config_generator.py, simulation_ipc.py, simulation_manager.py, simulation_runner.py, text_processor.py, zep_entity_reader.py, zep_graph_memory_updater.py, zep_tools.py.
  • Treat all triple-quoted prompt templates and value strings as out of scope (owned by issues #2/#3/#4/#5/#6) — only the first-statement docstrings of modules/classes/functions are in scope.
  • Apply Rules 1–5 from design.md.
  • Re-run the residual scan and confirm backend/app/services/ no longer has Chinese in non-string-literal positions.
  • Re-run the pytest command and confirm exit 0.
  • Observable: zero non-string-literal Chinese remains in backend/app/services/*.py, and the test command exits 0.
  • Requirements: 1.1, 1.2, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 4.5
  • Boundary: backend/app/services/

• 2.4 (P) Translate backend/app/api/ — complete (all 4 files; finished in this installment)

  • Translate Chinese docstrings and # comments in __init__.py, graph.py, report.py, simulation.py.
  • Treat any user-facing string-literal Chinese in API responses as out of scope (owned by issue #6).
  • Apply Rules 1–5 from design.md.
  • Re-run the residual scan and confirm backend/app/api/ no longer has Chinese in non-string-literal positions.
  • Re-run the pytest command and confirm exit 0.
  • Observable: zero non-string-literal Chinese remains in backend/app/api/*.py, and the test command exits 0.
  • Requirements: 1.1, 1.2, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 4.5
  • Boundary: backend/app/api/

• 2.5 (P) Translate backend/scripts/ — complete (all 5 files; finished in this installment)

  • Translate Chinese docstrings and # comments in action_logger.py, run_parallel_simulation.py, run_reddit_simulation.py, run_twitter_simulation.py, test_profile_format.py.
  • Apply Rules 1–5 from design.md.
  • Be especially careful with test_profile_format.py: any Chinese in test data string literals is out of scope; only docstrings and # comments are in scope.
  • Re-run the residual scan and confirm backend/scripts/ no longer has Chinese in non-string-literal positions.
  • Re-run the pytest command and confirm exit 0.
  • Observable: zero non-string-literal Chinese remains in backend/scripts/*.py, and the test command exits 0.
  • Requirements: 1.1, 1.2, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 4.5
  • Boundary: backend/scripts/

• 2.6 (P) Translate root backend files

  • Translate Chinese docstrings and # comments in backend/app/__init__.py, backend/app/config.py, and backend/run.py.
  • Apply Rules 1–5 from design.md.
  • Be especially careful with backend/app/config.py: any Chinese in default-value string literals is out of scope; only docstrings and # comments are in scope.
  • Re-run the residual scan and confirm these three files no longer have Chinese in non-string-literal positions.
  • Re-run the pytest command and confirm exit 0.
  • Observable: zero non-string-literal Chinese remains in backend/app/__init__.py, backend/app/config.py, and backend/run.py, and the test command exits 0.
  • Requirements: 1.1, 1.2, 1.4, 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 4.5
  • Boundary: backend/app (root), backend/run.py

Validation

• 3. Final verification and PR preparation

• 3.1 Run the final verification gate — scanner + py_compile pass on all 12 newly-translated files; CJK guard baseline updated (backend/app: 2792 → 307); pytest blocked by pre-existing env issues, see HANDOFF.md

  • Run the residual scan one more time and confirm the only remaining hits are files where the Chinese is in string literals owned by issues #2/#3/#4/#5/#6, plus the intentional Chinese in backend/tests/test_locale*.py.
  • Run cd backend && uv run python -m pytest scripts/test_profile_format.py and confirm exit 0.
  • Run git diff --stat origin/main...HEAD and confirm only in-scope file paths under backend/app/, backend/run.py, and backend/scripts/ are listed.
  • Spot-check three random changed files with git diff <path> and confirm only # lines and docstring lines changed (no executable lines, no string-literal lines).
  • Observable: residual scan, pytest, diff scope, and spot diff all pass.
  • Depends: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
  • Requirements: 1.3, 2.5, 5.1, 5.2, 5.3, 5.4, 6.4

• 3.2 Open PR and reference ticket #7

  • Use /done to commit any remaining changes per Conventional Commits with type docs and scope i18n (e.g. docs(i18n): translate chinese docstrings/comments in backend/<area>), push the branch, and open a PR.
  • The PR body must include Closes #7 and reference the spec at .kiro/specs/i18n-translate-backend-comments/.
  • Verify the PR contains no unrelated changes (no dependency bumps, no config changes, no refactors).
  • Observable: a PR exists on GitHub from docs/i18n-7-translate-backend-comments to main that closes #7 and contains only docstring/comment translation diffs.
  • Depends: 3.1
  • Requirements: 6.1, 6.2, 6.3, 6.4