co-op-translator 0.8.4

Easily automate multilingual translations for your projects with co-op-translator, powered by advanced LLM technology.

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.

[!TIP]

Powerful Automation: Now with GitHub Actions support! Automatically translate your documentation when changes are made to your repository, keeping everything up-to-date effortlessly. Learn more.

Supported Models and Services

Type	Name
Language Model
Computer Vision

[!NOTE] If a computer vision service is not available, the co-op translator will switch to Markdown-only mode.

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:

1. Text Extraction: Extracts text from Markdown files and, if configured (e.g., with Azure Computer Vision), text embedded within images.
2. AI Translation: Sends the extracted text to the configured LLM (Azure OpenAI, OpenAI, etc.) for translation.
3. 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.

Quick Start: Command Line

For a fast start using the command line:

1. Install the package:

   pip install co-op-translator
   

2. Configure Credentials:

• Create a .env file in your project's root directory.
• Copy the contents from the .env.template file into your new .env file.
• Fill in the required API keys and endpoint information in your .env file.

3. Run Translation:

• Navigate to your project's root directory in your terminal.
• Execute the translate command, specifying target languages with the -l flag:

  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-translator package.
• 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.

[!NOTE] While this tutorial focuses on Azure resources, you can use any supported language model from the supported models and services list.

Troubleshooting and Tips

• Troubleshooting Guide

Additional Resources

• Command Reference: Detailed guide to all available commands and options.
• Multi-language Support Setup: How to add a table linking to translated versions in your README.
• 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.

  

• Microsoft Reactor: A one-hour detailed step-by-step guide covering everything from understanding what Co-op Translator is, setting up the tool, and using it effectively, to a live demo showcasing its capabilities in action.

  

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 [e-mail] 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.