mirror of
https://github.com/Azure/co-op-translator
synced 2026-08-09 12:00:08 +00:00
Docs: Add workflow chooser guide (#435)
This commit is contained in:
Minseok Song
+1
-1
@@ -9,7 +9,7 @@ The stable public Python API is exported from `co_op_translator.api`. Most integ
|
||||
|
||||
Most lower-level modules under `core`, `config`, `review`, and `utils` are implementation details used by these API entry points.
|
||||
|
||||
MCP clients use the same public API through the [MCP Server](mcp.md). Use this page when calling Python directly, and the MCP guide when exposing Co-op Translator to an agent or editor.
|
||||
MCP clients use the same public API through the [MCP Server](mcp.md). Use this page when calling Python directly, and the MCP guide when exposing Co-op Translator to an agent or editor. If you are deciding between CLI, Python API, and MCP, start with [Choose Your Workflow](workflows.md).
|
||||
|
||||
## First-Time API Flow
|
||||
|
||||
|
||||
@@ -10,6 +10,8 @@ Co-op Translator installs these command-line entry points:
|
||||
|
||||
The `translate`, `evaluate`, `migrate-links`, and `co-op-review` commands dispatch through `co_op_translator.__main__`, which selects the command implementation based on the invoked script name. The MCP server uses `co_op_translator.mcp.server` directly.
|
||||
|
||||
If you are deciding between CLI, Python API, and MCP, start with [Choose Your Workflow](workflows.md).
|
||||
|
||||
## First-Time CLI Flow
|
||||
|
||||
Start here if you are using Co-op Translator from a terminal:
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@
|
||||
Translator from the CLI, Python API, or MCP server to translate and review
|
||||
project content as the source changes.
|
||||
</p>
|
||||
<a class="home-link" href="cli/">Start with the CLI -></a>
|
||||
<a class="home-link" href="workflows/">Choose your workflow -></a>
|
||||
</section>
|
||||
|
||||
## Quick start
|
||||
|
||||
@@ -4,6 +4,8 @@ Co-op Translator includes a Model Context Protocol server for agents, editors, a
|
||||
|
||||
For the default local setup, users do not keep a separate server running by hand. They configure their MCP client, and the client starts `co-op-translator-mcp` automatically over `stdio` when it needs Co-op Translator tools.
|
||||
|
||||
If you are deciding between CLI, Python API, and MCP, start with [Choose Your Workflow](workflows.md).
|
||||
|
||||
Use MCP when an agent or editor should call Co-op Translator directly:
|
||||
|
||||
| User goal | MCP tools |
|
||||
|
||||
@@ -0,0 +1,170 @@
|
||||
# Choose Your Workflow
|
||||
|
||||
Co-op Translator can be used in three ways: the CLI, the Python API, and the MCP server. They share the same translation capabilities, but each one fits a different workflow.
|
||||
|
||||
Use this page when you are deciding where to start.
|
||||
|
||||
## Quick Decision
|
||||
|
||||
| If you want to... | Use | Start here |
|
||||
| --- | --- | --- |
|
||||
| Translate or review a repository from a terminal | CLI | [CLI Reference](cli.md) |
|
||||
| Add translation to a Python script, service, notebook, or CI job | Python API | [Python API](api.md) |
|
||||
| Let an agent, editor, or MCP-compatible client translate content for you | MCP Server | [MCP Server](mcp.md) |
|
||||
| Translate one Markdown document, notebook, or image that your app already loaded | Python API or MCP Server | [Python API](api.md) or [MCP Server](mcp.md) |
|
||||
| Translate an entire repository with standard output folders and metadata | CLI or `run_translation` | [CLI Reference](cli.md) or [Python API](api.md) |
|
||||
|
||||
## Use the CLI when
|
||||
|
||||
Choose the CLI when a person or CI job is driving repository translation from a shell.
|
||||
|
||||
The CLI is the most direct path when you want Co-op Translator to discover project files, create translated outputs, preserve the project layout, update metadata, and run review commands.
|
||||
|
||||
```bash
|
||||
translate -l "ko" -md --dry-run
|
||||
translate -l "ko" -md -nb -img
|
||||
co-op-review -l "ko" -md -nb
|
||||
migrate-links -l "ko" --dry-run
|
||||
```
|
||||
|
||||
Good fits:
|
||||
|
||||
- You are translating a repository from your terminal.
|
||||
- You want a repeatable command for CI or release workflows.
|
||||
- You want built-in project discovery, output paths, metadata, cleanup, and review.
|
||||
- You prefer a command interface over writing Python code.
|
||||
|
||||
## Use the Python API when
|
||||
|
||||
Choose the Python API when your own code should control the workflow.
|
||||
|
||||
The API is useful for applications, automation scripts, notebooks, services, and custom pipelines. It lets you call low-level content translation APIs for individual files, or run the same repository-level orchestration used by the CLI.
|
||||
|
||||
Translate one Markdown document and decide where to save it:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from pathlib import Path
|
||||
|
||||
from co_op_translator.api import rewrite_markdown_paths, translate_markdown_content
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
source_path = Path("docs/guide.md")
|
||||
target_path = Path("translations/ko/docs/guide.md")
|
||||
|
||||
translated = await translate_markdown_content(
|
||||
source_path.read_text(encoding="utf-8"),
|
||||
"ko",
|
||||
{"source_path": source_path},
|
||||
)
|
||||
|
||||
rewritten = rewrite_markdown_paths(
|
||||
translated,
|
||||
source_path=source_path,
|
||||
target_path=target_path,
|
||||
)
|
||||
|
||||
target_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
target_path.write_text(rewritten, encoding="utf-8")
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
Run a repository translation from Python:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
from co_op_translator.api import run_translation
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
await run_translation(
|
||||
language_codes=["ko"],
|
||||
translate_markdown=True,
|
||||
translate_notebooks=True,
|
||||
translate_images=False,
|
||||
dry_run=True,
|
||||
)
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
Good fits:
|
||||
|
||||
- Your application already reads files, buffers, notebooks, or image bytes.
|
||||
- You need custom validation, storage, logging, retries, or approval flows.
|
||||
- You want to translate one document, notebook, or image without processing a whole repository.
|
||||
- You want repository translation, but from Python automation instead of a shell command.
|
||||
|
||||
## Use the MCP Server when
|
||||
|
||||
Choose the MCP server when an agent, editor, or MCP-compatible client should call Co-op Translator tools.
|
||||
|
||||
In the normal local setup, the user does not manually keep a server running. The MCP client starts `co-op-translator-mcp` over `stdio` when it needs the tools.
|
||||
|
||||
Example user requests an agent could handle:
|
||||
|
||||
- "Translate this Markdown file to Korean and keep the links correct."
|
||||
- "Translate the text in this image to Japanese and save the result."
|
||||
- "Dry-run a repository translation to Spanish and tell me what would change."
|
||||
- "Review whether the Korean translation output is up to date."
|
||||
|
||||
MCP Markdown tool call shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "translate_markdown_content",
|
||||
"arguments": {
|
||||
"document": "# Setup\n\nInstall Co-op Translator first.",
|
||||
"language_code": "ko",
|
||||
"options": {
|
||||
"source_path": "docs/setup.md"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
MCP image tool call shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "translate_image_content",
|
||||
"arguments": {
|
||||
"image_path": "assets/architecture.png",
|
||||
"language_code": "ko",
|
||||
"output_path": "translated_images/ko/assets/architecture.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Repository translation is dry-run by default through MCP:
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "run_translation",
|
||||
"arguments": {
|
||||
"language_codes": ["ko"],
|
||||
"translate_markdown": true,
|
||||
"translate_notebooks": true,
|
||||
"translate_images": false,
|
||||
"dry_run": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Good fits:
|
||||
|
||||
- You want natural-language translation workflows inside an agent or editor.
|
||||
- You want the agent to translate selected content instead of an entire repository.
|
||||
- You want an approval step before repository-wide writes.
|
||||
- You want one interface that exposes Markdown, notebook, image, review, and path-rewriting tools.
|
||||
|
||||
## How They Fit Together
|
||||
|
||||
The CLI is the best default for humans translating repositories. The Python API is best when your code owns the workflow. The MCP server is best when an agent or editor owns the workflow.
|
||||
|
||||
All three paths use the same public Co-op Translator API, so you can start with the CLI, automate with Python later, and expose the same capabilities to MCP clients when you need agent-driven workflows.
|
||||
+2
-1
@@ -77,8 +77,9 @@ markdown_extensions:
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Choose Your Workflow: workflows.md
|
||||
- Configuration: configuration.md
|
||||
- CLI Reference: cli.md
|
||||
- Python API: api.md
|
||||
- MCP Server: mcp.md
|
||||
- CLI Reference: cli.md
|
||||
- Maintainer Guide: maintainer-guide.md
|
||||
|
||||
Reference in New Issue
Block a user