co-op-translator
Co-op Translator: Automate the Translation of Educational Documentation Effortlessly
Easily automate the translation of your documentation into multiple languages to reach a global audience.
Language Support Powered by Co-op Translator
[!NOTE] These are the current translations of this repository’s content. For a complete list of languages supported by Co-op Translator, please see the Language Support section.
Overview: Streamline Your Educational Content Translation
Language barriers significantly hinder access to valuable educational resources and technical knowledge for learners and developers worldwide. This limits participation and slows down the pace of global innovation and learning.
Co-op Translator was born from the need to address the inefficient manual translation process for Microsoft’s own large-scale educational series (like the “For Beginners” guides). It has evolved into an easy-to-use, powerful tool designed to break down these barriers for everyone. By providing high-quality automated translations via CLI and GitHub Actions, Co-op Translator empowers educators, students, researchers, and developers globally to share and access knowledge without language constraints.
See how Co-op Translator organizes translated educational content:
Markdown files and image text are automatically translated and neatly organized into language-specific folders.
Unlock global access to your educational content with Co-op Translator today!
Supporting Global Access for Microsoft’s Learning Resources
Co-op Translator helps bridge the language gap for key Microsoft educational initiatives, automating the translation process for repositories that serve a global developer community. Examples currently using Co-op Translator include:
Key Features
- Automated Translations: Translate text into multiple languages effortlessly.
- GitHub Actions Integration: Automate translations as part of your CI/CD pipeline.
- Markdown Preservation: Maintain correct Markdown syntax during translation.
- Image Text Translation: Extract and translate text within images.
- Advanced LLM Technology: Use cutting-edge language models for high-quality translations.
- Easy Integration: Seamlessly integrate with your existing project setup.
- Simplify Localization: Streamline the process of localizing your project for international markets.
How It Works
Co-op Translator takes Markdown files and images from your project folder and processes them as follows:
- Text Extraction: Extracts text from Markdown files and, if configured (e.g., with Azure AI Vision), text embedded within images.
- AI Translation: Sends the extracted text to the configured LLM (Azure OpenAI, OpenAI, etc.) for translation.
- Result Saving: Saves the translated Markdown files and images (with translated text) into language-specific folders, preserving the original formatting.
Getting Started
Get started quickly with the CLI or set up full automation with GitHub Actions. Choose the approach that best fits your workflow:
- Command Line (CLI) - For one-time translations or manual control
- GitHub Actions - For automated translations on every push
[!NOTE] While this tutorial focuses on Azure resources, you can use any supported language model.
Language Support
Co-op Translator supports a wide range of languages to help you reach a global audience. Here’s what you need to know:
Quick Reference
| Language | Code | Language | Code | Language | Code |
|---|---|---|---|---|---|
| Arabic | ar | Bengali | bn | Bulgarian | bg |
| Burmese (Myanmar) | my | Chinese (Simplified) | zh | Chinese (Traditional, HK) | hk |
| Chinese (Traditional, Macau) | mo | Chinese (Traditional, TW) | tw | Croatian | hr |
| Czech | cs | Danish | da | Dutch | nl |
| Finnish | fi | French | fr | German | de |
| Greek | el | Hebrew | he | Hindi | hi |
| Hungarian | hu | Indonesian | id | Italian | it |
| Japanese | ja | Korean | ko | Malay | ms |
| Marathi | mr | Nepali | ne | Norwegian | no |
| Persian (Farsi) | fa | Polish | pl | Portuguese (Brazil) | br |
| Portuguese (Portugal) | pt | Punjabi (Gurmukhi) | pa | Romanian | ro |
| Russian | ru | Serbian (Cyrillic) | sr | Slovak | sk |
| Slovenian | sl | Spanish | es | Swahili | sw |
| Swedish | sv | Tagalog (Filipino) | tl | Thai | th |
| Turkish | tr | Ukrainian | uk | Urdu | ur |
| Vietnamese | vi | — | — | — | — |
Using Language Codes
When using Co-op Translator, you’ll need to specify languages using their codes. For example:
# Translate to French, Spanish, and German
translate -l "fr es de"
# Translate to Chinese (Simplified) and Japanese
translate -l "zh ja"
[!NOTE] For detailed technical information about language support, including:
- Font specifications for each language
- Known issues
- How to add new languages
See our Supported Languages Documentation.
Supported Models and Services
| Type | Name |
|---|---|
| Language Model |   |
| AI Vision |  |
[!NOTE] If a AI vision service is not available, the co-op translator will switch to Markdown-only mode.
Initial Setup
Before you begin, you’ll need to set up the following resources:
- Language Model Resource (Required):
- Azure OpenAI (Recommended) - Provides high-quality translations with enterprise-grade reliability
- OpenAI - Alternative option if you don’t have Azure access
- For detailed information about supported models, see Supported Models and Services
- AI Vision Resource (Optional):
- Azure AI Vision - Enables translation of text within images
- If not configured, the translator will automatically use Markdown-only mode
- Recommended for projects with images containing text that needs translation
- Configuration Steps:
- Follow our Azure AI setup guide for detailed instructions
- Create a
.envfile with your API keys and endpoints (see Quick Start section) - Ensure you have the necessary permissions and quotas for your chosen services
Project Setup Before Translation
Before starting the translation process, follow these steps to prepare your project:
- Prepare Your README:
- Add a translations table to your README.md to link to translated versions
-
Example format:
### 🌐 Multi-Language Support [French](/co-op-translator/translations/fr/) | [Spanish](/co-op-translator/translations/es/) | [German](/co-op-translator/translations/de/) | [Russian](/co-op-translator/translations/ru/) | [Arabic](/co-op-translator/translations/ar/) | [Persian (Farsi)](/co-op-translator/translations/fa/) | [Urdu](/co-op-translator/translations/ur/) | [Chinese (Simplified)](/co-op-translator/translations/zh/) | [Chinese (Traditional, Macau)](/co-op-translator/translations/mo/) | [Chinese (Traditional, Hong Kong)](/co-op-translator/translations/hk/) | [Chinese (Traditional, Taiwan)](/co-op-translator/translations/tw/) | [Japanese](/co-op-translator/translations/ja/) | [Korean](/co-op-translator/translations/ko/) | [Hindi](/co-op-translator/translations/hi/) | [Bengali](/co-op-translator/translations/bn/) | [Marathi](/co-op-translator/translations/mr/) | [Nepali](/co-op-translator/translations/ne/) | [Punjabi (Gurmukhi)](/co-op-translator/translations/pa/) | [Portuguese (Portugal)](/co-op-translator/translations/pt/) | [Portuguese (Brazil)](/co-op-translator/translations/br/) | [Italian](/co-op-translator/translations/it/) | [Polish](/co-op-translator/translations/pl/) | [Turkish](/co-op-translator/translations/tr/) | [Greek](/co-op-translator/translations/el/) | [Thai](/co-op-translator/translations/th/) | [Swedish](/co-op-translator/translations/sv/) | [Danish](/co-op-translator/translations/da/) | [Norwegian](/co-op-translator/translations/no/) | [Finnish](/co-op-translator/translations/fi/) | [Dutch](/co-op-translator/translations/nl/) | [Hebrew](/co-op-translator/translations/he/) | [Vietnamese](/co-op-translator/translations/vi/) | [Indonesian](/co-op-translator/translations/id/) | [Malay](/co-op-translator/translations/ms/) | [Tagalog (Filipino)](/co-op-translator/translations/tl/) | [Swahili](/co-op-translator/translations/sw/) | [Hungarian](/co-op-translator/translations/hu/) | [Czech](/co-op-translator/translations/cs/) | [Slovak](/co-op-translator/translations/sk/) | [Romanian](/co-op-translator/translations/ro/) | [Bulgarian](/co-op-translator/translations/bg/) | [Serbian (Cyrillic)](/co-op-translator/translations/sr/) | [Croatian](/co-op-translator/translations/hr/) | [Slovenian](/co-op-translator/translations/sl/) | [Ukrainian](/co-op-translator/translations/uk/) | [Burmese (Myanmar)](/co-op-translator/translations/my/)
- Clean Up Existing Translations (if needed):
- Remove any existing translation folders (e.g.,
translations/) - Delete any old translation files to start fresh
- This ensures no conflicts with the new translation process
- Remove any existing translation folders (e.g.,
Quick Start: Command Line
For a fast start using the command line:
-
Create a virtual environment:
python -m venv .venv -
Activate the virtual environment:
- On Windows:
.venv\scripts\activate- On Linux/macOS:
source .venv/bin/activate -
Install the package:
pip install co-op-translator -
Configure Credentials:
- Create a
.envfile in your project’s root directory. - Copy the contents from the .env.template file into your new
.envfile. - Fill in the required API keys and endpoint information in your
.envfile.
- Create a
-
Run Translation:
- Navigate to your project’s root directory in your terminal.
- Execute the translate command, specifying target languages with the
-lflag:
translate -l "ko ja fr"(Replace
"ko ja fr"with your desired space-separated language codes)
Detailed Usage Guides
Choose the approach that best fits your workflow:
1. Using the Command Line (CLI)
- Best for: One-time translations, manual control, or integration into custom scripts.
- Requires: Local installation of Python and the
co-op-translatorpackage. - Guide: Command Line Guide
2. Using GitHub Actions (Automation)
- Best for: Automatically translating content whenever changes are pushed to your repository. Keeps translations consistently up-to-date.
- Requires: Setting up a workflow file (
.github/workflows) in your repository. No local installation needed. - Guides:
- GitHub Actions Guide (Public Repositories & Standard Secrets) - Use this for most public or personal repositories relying on standard repository secrets.
- GitHub Actions Guide (Microsoft Organization Repos & Org-Level Setups) - Use this guide if you are working within the Microsoft GitHub organization or need to leverage organization-level secrets or runners.
Troubleshooting and Tips
Additional Resources
- Command Reference: Detailed guide to all available commands and options.
- Supported Languages: Check the list of supported languages and instructions for adding new ones.
- Markdown-Only Mode: How to translate text only, without image translation.
Video Presentations
Learn more about Co-op Translator through our presentations (Click the image below to watch on YouTube.):
-
Open at Microsoft: A brief 18-minute introduction and quick guide on how to use Co-op Translator.
Support Us and Foster Global Learning
Join us in revolutionizing how educational content is shared globally! Give Co-op Translator a ⭐ on GitHub and support our mission to break down language barriers in learning and technology. Your interest and contributions make a significant impact! Code contributions and feature suggestions are always welcome.
Contributing
This project welcomes contributions and suggestions. Interested in contributing to Azure Co-op Translator? Please see our CONTRIBUTING.md for guidelines on how you can help make Co-op Translator more accessible.
Contributors
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 any 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.