62 lines
4.3 KiB
Markdown
62 lines
4.3 KiB
Markdown
# Handoff — `i18n-translate-backend-comments` (Issue #7)
|
|
|
|
## Status
|
|
**Partial completion.** This is the first installment of the ticket-#7 cleanup. The ticket explicitly allows splitting the work across multiple small PRs ("Low-risk, high-volume mechanical task; can be split across multiple small PRs"). This PR ships translations for the smaller files; the larger service and API files remain for follow-up PRs.
|
|
|
|
## Completed in this PR (23 files)
|
|
All translated to English with no behavior or string-literal changes:
|
|
|
|
- **Root**: `backend/app/__init__.py`, `backend/app/config.py`, `backend/run.py`
|
|
- **API package init**: `backend/app/api/__init__.py`
|
|
- **Models** (full package): `backend/app/models/__init__.py`, `project.py`, `task.py`
|
|
- **Utils** (full package): `backend/app/utils/__init__.py`, `file_parser.py`, `llm_client.py`, `locale.py` (no docstring/comment Chinese to begin with), `logger.py`, `retry.py`, `zep_paging.py`
|
|
- **Services** (partial): `backend/app/services/__init__.py`, `graph_builder.py`, `ontology_generator.py`, `simulation_ipc.py`, `simulation_manager.py`, `text_processor.py`, `zep_entity_reader.py`
|
|
- **Scripts** (partial): `backend/scripts/action_logger.py`, `backend/scripts/test_profile_format.py`
|
|
|
|
## Remaining for follow-up PRs (12 files)
|
|
Per the AST-aware scanner used in this PR (`/tmp/scan_chinese.py`), the residual in-scope work totals **2,235 hits** (1,203 docstring lines + 1,032 inline-comment lines) across these files:
|
|
|
|
| File | Approx in-scope hits | Approx LOC |
|
|
| --- | --- | --- |
|
|
| `backend/app/api/graph.py` | ~50 | 665 |
|
|
| `backend/app/api/report.py` | ~80 | 1020 |
|
|
| `backend/app/api/simulation.py` | ~250 | 2712 |
|
|
| `backend/app/services/oasis_profile_generator.py` | ~230 | 1195 |
|
|
| `backend/app/services/report_agent.py` | ~520 | 2572 |
|
|
| `backend/app/services/simulation_config_generator.py` | ~150 | 991 |
|
|
| `backend/app/services/simulation_runner.py` | ~330 | 1768 |
|
|
| `backend/app/services/zep_graph_memory_updater.py` | ~110 | 544 |
|
|
| `backend/app/services/zep_tools.py` | ~280 | 1741 |
|
|
| `backend/scripts/run_parallel_simulation.py` | ~150 | 1699 |
|
|
| `backend/scripts/run_reddit_simulation.py` | ~50 | 769 |
|
|
| `backend/scripts/run_twitter_simulation.py` | ~50 | 780 |
|
|
|
|
(Counts are approximate and exclude string-literal Chinese, which is owned by adjacent tickets #2/#3/#4/#5/#6.)
|
|
|
|
## Suggested follow-up split
|
|
|
|
Three additional PRs of similar size to this one would complete the ticket:
|
|
|
|
1. **PR 2 — `services/{oasis_profile_generator, simulation_config_generator, simulation_runner, zep_graph_memory_updater, zep_tools}`**
|
|
2. **PR 3 — `services/report_agent.py`** (single big file; isolating it keeps the diff reviewable)
|
|
3. **PR 4 — `api/{graph,report,simulation}.py` + `scripts/run_{parallel,reddit,twitter}_simulation.py`**
|
|
|
|
## Verification methodology used
|
|
The AST-aware scanner (`/tmp/scan_chinese.py` — also kept in commit context) classifies every Chinese-containing line into one of three buckets: `DOCSTRING` (in scope), `COMMENT` (in scope), `STRING_VALUE` (out of scope, owned by adjacent tickets). Each translated file was verified with:
|
|
|
|
1. `python -m py_compile <file>` — syntactic validity.
|
|
2. The scanner returning `{'DOCSTRING': 0, 'COMMENT': 0}` for that file.
|
|
3. `git diff <file>` review — only `#` lines and docstring lines change; no executable lines.
|
|
|
|
## Test environment caveat
|
|
The repo's `uv sync` requires building `tiktoken` from source, which needs Rust. The sandbox running this implementation pass does not have Rust, so `cd backend && uv run python -m pytest scripts/test_profile_format.py` (the verification command in the spec) cannot be executed end-to-end here; the test command also fails on import for unrelated reasons (missing `graphiti_core`, etc.) before any of this PR's changes touched the tree. Because the change set is comments-and-docstrings-only, runtime behavior cannot be affected; the syntactic-validity check stands in for the test run in this environment.
|
|
|
|
A developer with the project's normal dev environment (Rust toolchain installed, full `uv sync` succeeded) should re-run `cd backend && uv run python -m pytest scripts/test_profile_format.py` against this branch before merging to confirm.
|
|
|
|
## What is NOT changed
|
|
- No string literal anywhere in the touched files.
|
|
- No executable Python statement.
|
|
- No symbol renamed.
|
|
- No file added or removed.
|
|
- No dependency added or version-bumped.
|