Translate, edit, and review a small project¶
Start with two short Markdown files and one target language. You will see where translations are written, what happens when the source changes, and how to check the result.
Recorded results¶
The example was run on September 19, 2026 with Co-op Translator 0.21.0 and Azure OpenAI (gpt-5-mini). The unmodified CLI commands were invoked through Click's CliRunner using the built wheel and existing Python dependencies.
| Step | Result |
|---|---|
| Preview | Exit 0; no model translation requested |
| Initial translation | Exit 0; 27.36 seconds |
| Initial review | Exit 0 |
| Edit README and review | Exit 1; stale translation detected |
| Update translation | Exit 0; 22.17 seconds |
| Review after update | Exit 0; no errors or warnings |
| Unchanged guide | Identical bytes before and after README update |
| Run again | Exit 0; identical hashes for all translation files |
These are individual run measurements, not performance guarantees. Setup time is excluded; provider billing was not measured. An unchanged run can still perform a provider health check.
Inspect the initial translation, updated translation, complete translation diff, stale review, final review, and run details. Full-file translation may change other wording, as the captured diff shows. Both text artifacts retain the generated disclaimer.
Human review still matters: the captured update uses [사용 가이드](guide.md)을; the Korean particle should be [사용 가이드](guide.md)를. The text artifacts keep this output intact rather than presenting an edited translation as model output. The structural review passes despite this wording issue.
1. Prepare a small folder¶
Use Python 3.11–3.14 and the virtual environment setup. The pin below reproduces the recorded 0.21.0 example; it is not the recommended version for a new project. For a new setup, follow the configuration guide. Agent workflows require 0.22.0 or later.
To reproduce this example, install its recorded version:
Download README.txt and guide.txt into this folder, saving them as README.md and guide.md. They are small fictional project documents; no application installation is needed.
The README includes a code block and a link to guide.md. Its final sentence is:
Keep only these two source documents in this folder. All following commands run inside translation-demo and work in Bash and PowerShell.
2. Preview without credentials¶
The preview estimates translation work without calling a model or writing translations. Token estimates are not a billing quote. The first run should identify both Markdown files as new work.
3. Choose a provider and translate¶
Configure one provider using the configuration guide: Azure OpenAI, OpenAI, or Anthropic. OpenAI and Anthropic text translation do not require an Azure account. Image services are not needed for this example.
If you use a local .env file, add .env to this folder's .gitignore. Translation calls use your provider account and may incur charges.
Open translations/ko/README.md and translations/ko/guide.md. Check the Korean wording, the code block, and the link from the translated README to the translated guide. Output wording varies by model.
co-op-review checks freshness, structure, and local links. A passing result does not certify linguistic accuracy. Resolve any reported errors before continuing.
Record the successful baseline with Git (configure your Git identity first if needed):
4. Change the source¶
In README.md, replace Notes are saved locally. with:
Leave guide.md unchanged. Then run:
The review should report the README translation as stale and exit unsuccessfully. This is the expected intermediate state. The preview should identify work for the changed README.
5. Update and inspect the diff¶
translate -l "ko" -md
git diff -- README.md translations/ko/README.md
git diff -- translations/ko/guide.md
co-op-review -l "ko"
Inspect the real diff: the default CLI retranslates the changed file, so the model can also revise other wording in that file. The unchanged guide should have no diff. The review should no longer report the README as stale; investigate any other findings rather than ignoring them.
Block-level preservation of human Markdown edits requires an optional translation state provider in the Python API. It is not enabled by these CLI commands.
6. Run again without changes¶
Commit the updated source and translation:
git add README.md translations
git commit -m "Update Korean translation after source edit"
translate -l "ko" -md
git diff --exit-code -- translations
With current translations and unchanged configuration, the translator skips the files. The final Git command should produce no diff and exit successfully.