Co-op Translator

Keep multilingual GitHub documentation current as your source evolves.

Co-op Translator detects changed source content, updates stale translations, and preserves the links and structure of Markdown, Jupyter notebooks, and images.

Translate Markdown and notebooks with Azure OpenAI, OpenAI, or Anthropic. Azure is optional for text translation; translating text inside images additionally requires Azure AI Vision.

Python 3.11–3.14

Get started · See real repositories · Read the documentation

See the result, then try it

See Co-op Translator in use in AI Agents for Beginners: the same README section in English and Korean.

English	Korean

English source · Korean translation

Try the small translation example: preview two Markdown files without credentials, translate them, edit the source, and inspect the translation diff and review results.

The CLI updates changed files and skips unchanged translations.

Why Co-op Translator?

Translation is not finished when a model returns text. Repository-scale documentation needs to stay complete, navigable, and synchronized after every source change.

Problem	How Co-op Translator helps
Source content keeps changing	Source hashes and language-scoped metadata identify stale files and skip unchanged translations.
Long documents do not fit one reliable model response	Markdown is split into manageable chunks, with retry and re-chunking for failed sections.
Models can alter Markdown structure or destinations	Structure checks and parser-based protection preserve Markdown URLs, code, and Markdown structure.
Links must follow the translated repository tree	Relative links for Markdown, notebooks, images, and README files are rewritten for `translations/<lang>/...`.
A repository contains more than prose	One workflow can handle Markdown, Jupyter notebooks, image text, and repository-level review.

See Co-op Translator in real repositories

Co-op Translator has been used in Microsoft open-source learning repositories that combine lessons, code samples, links, notebooks, and supporting assets.

Repository	Translations
AI Agents for Beginners	Browse translations
Generative AI for Beginners	Browse translations
MCP for Beginners	Browse translations

Explore more multilingual Microsoft learning repositories

Get started

Install Co-op Translator and preview the work without configuring provider credentials:

pip install co-op-translator
translate -l "ko" -md --dry-run

Configure Azure OpenAI, OpenAI, or Anthropic credentials, then run the translation and deterministic review:

translate -l "ko" -md
co-op-review -l "ko"

For a first run, start with Choose your workflow. It compares local translation, Python automation, GitHub Actions, containers, and agent or editor integration.

Want a translation pull request first? Follow Your first README translation PR: choose one language, preview the work, then generate and review a README translation before merging. No image service setup is needed.

How it works

Plan: scan the repository, normalize language codes, and identify new or outdated source content.
Translate: process Markdown, notebook cells, and image text with configured providers. MCP host agents can translate Markdown and notebook chunks.
Preserve structure: protect code and URL destinations, then rewrite relative paths for the translated repository tree.
Track and review: save language-scoped metadata so later runs can skip unchanged files and report missing, stale, or structurally incomplete translations.

Translated content remains in the repository, where it can be reviewed, versioned, and updated with the source.

Language-scoped metadata tracks translation freshness; read more about managing translations as versioned software artifacts.

Choose your interface

Interface	Best for	Guide
CLI	Local repository work and scripts	CLI reference
Python API	Applications and custom automation	Python API
MCP server	Agent and editor workflows, including host-agent translation of Markdown and notebook chunks	MCP server
GitHub Actions	Repository translation in CI	GitHub Actions
Container	Isolated or repeatable CLI runs	Quick run

Container

Container quick run with Bash or Zsh:

docker run --rm -it --env-file .env -v "${PWD}:/work" ghcr.io/azure/co-op-translator:latest -l "ko" -md

Container quick run with PowerShell:

docker run --rm -it --env-file .env -v ${PWD}:/work ghcr.io/azure/co-op-translator:latest -l "ko" -md

Featured by Microsoft

Microsoft's The Future of AI series: Unlock Global Collaboration with Co-op Translator: Automate Markdown and Image Translations Using Azure AI Foundry
Open at Microsoft: Unlocking Multilingual Accessibility with Co-op Translator: A Case Study on Phi-3 Cookbook
Microsoft Reactor: Unlocking Multilingual Mastery: Dive into Co-op Translator with Azure

Case studies and engineering deep dives

Case studies

Engineering deep dives

Documentation

Microsoft-specific guide

Updating the “other courses” list

Supported languages and cloning

Co-op Translator supports 50+ language and locale codes. Expand this section to browse translated README files and see how to clone the repository without translation assets.

View supported languages and sparse-checkout instructions

Prefer to Clone Locally?

This repository includes 50+ language translations which significantly increases the download size. To clone without translations, use sparse checkout:

Bash / macOS / Linux:
git clone --filter=blob:none --sparse https://github.com/Azure/co-op-translator.git
cd co-op-translator
git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'
CMD (Windows):
git clone --filter=blob:none --sparse https://github.com/Azure/co-op-translator.git
cd co-op-translator
git sparse-checkout set --no-cone "/*" "!translations" "!translated_images"
This gives you everything you need to complete the course with a much faster download.

Contributing

Know a language and noticed a translation problem? Make your first contribution without coding by sharing an example or reviewing a suggested correction.

See CONTRIBUTING.md for development setup, coding conventions, and pull request guidance.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with additional questions or comments.

Responsible AI

Microsoft is committed to helping our customers use our AI products responsibly, sharing our learnings, and building trust-based partnerships through tools like Transparency Notes and Impact Assessments. Many of these resources can be found at https://aka.ms/RAI. Microsoft's approach to responsible AI is grounded in our AI principles of fairness, reliability and safety, privacy and security, inclusiveness, transparency, and accountability.

Large-scale natural language, image, and speech models - like the ones used in this sample - can potentially behave in ways that are unfair, unreliable, or offensive, in turn causing harms. Please consult the Azure OpenAI service Transparency note to be informed about risks and limitations.

The recommended approach to mitigating these risks is to include a safety system in your architecture that can detect and prevent harmful behavior. Azure AI Content Safety provides an independent layer of protection, able to detect harmful user-generated and AI-generated content in applications and services. Azure AI Content Safety includes text and image APIs that allow you to detect material that is harmful. We also have an interactive Content Safety Studio that allows you to view, explore and try out sample code for detecting harmful content across different modalities. The following quickstart documentation guides you through making requests to the service.

Another aspect to take into account is the overall application performance. With multi-modal and multi-models applications, we consider performance to mean that the system performs as you and your users expect, including not generating harmful outputs. It's important to assess the performance of your overall application using generation quality and risk and safety metrics.

You can evaluate your AI application in your development environment using the prompt flow SDK. Given either a test dataset or a target, your generative AI application generations are quantitatively measured with built-in evaluators or custom evaluators of your choice. To get started with the prompt flow sdk to evaluate your system, you can follow the quickstart guide. Once you execute an evaluation run, you can visualize the results in Azure AI Studio.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Getting help

For project problems, open a GitHub issue. For questions about building AI applications, use the Microsoft Foundry community channels:

Metadata

Release files for co-op-translator 0.22.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for co-op-translator 0.22.0
File	Size	Uploaded
co_op_translator-0.22.0.tar.gz	16.2 MB	Oct 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for co-op-translator 0.22.0
File	Interpreter	ABI	Platform	Reset
co_op_translator-0.22.0-py3-none-any.whl 16.3 MB Oct 2, 2026	Python 3	none	any	Details

Total release size: 32.5 MB

Release files / co_op_translator-0.22.0.tar.gz

Download URL	co_op_translator-0.22.0.tar.gz
Size	16.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`040a286d087b44d51ec8a3332ecdd5a30189c793fc4c004fcfec94f2839046e5`
BLAKE2b-256 checksum How to use checksums	`40f3b9a59f396a03f94b50c0953492cdff290654ef4f1adada4edc7d9591e73e`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Azure/co-op-translator
Publishing commit: github.com/Azure/co-op-translator/tree/25532bb0a066eacd284800c1fea15a9bb126b2e9

Workflow

Publishing configuration: github.com/Azure/co-op-translator/blob/25532bb0a066eacd284800c1fea15a9bb126b2e9/.github/workflows/python-publish.yml
Publishing logs: github.com/Azure/co-op-translator/actions/runs/37077711461/attempts/1

Artifact

Subject: co_op_translator-0.22.0.tar.gz
SHA-256 checksum: 040a286d087b44d51ec8a3332ecdd5a30189c793fc4c004fcfec94f2839046e5 Verifying attestations

Release files / co_op_translator-0.22.0-py3-none-any.whl

Download URL	co_op_translator-0.22.0-py3-none-any.whl
Size	16.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`743a0a66a6ad630a1ad32fb4678724c4d72b0b4ecb033855663d631a216077b5`
BLAKE2b-256 checksum How to use checksums	`dd218f0586236d949d320ba6d4c3e8fd98ecfe38734c82ab36fc5a3caaa0cd24`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Azure/co-op-translator
Publishing commit: github.com/Azure/co-op-translator/tree/25532bb0a066eacd284800c1fea15a9bb126b2e9

Workflow

Publishing configuration: github.com/Azure/co-op-translator/blob/25532bb0a066eacd284800c1fea15a9bb126b2e9/.github/workflows/python-publish.yml
Publishing logs: github.com/Azure/co-op-translator/actions/runs/37077711461/attempts/1

Artifact

Subject: co_op_translator-0.22.0-py3-none-any.whl
SHA-256 checksum: 743a0a66a6ad630a1ad32fb4678724c4d72b0b4ecb033855663d631a216077b5 Verifying attestations