The Co-op Translator is a command-line interface (CLI) tool that helps you translate markdown and image files in your project into multiple languages. This section explains how to use the tool, covers the various CLI options, and provides examples for different use cases.
Note
For a complete list of commands and their detailed descriptions, please refer to the Command reference.
Here are a few common use cases for the Co-op Translator, along with the appropriate commands to run.
To translate your entire project (markdown files and images) into a single language, like Korean, use the following command:
translate -l "ko"This command will translate all markdown and image files into Korean, adding new translations without deleting any existing ones.
Tip
Want to see which language codes are available in Co-op Translator? Visit the Supported Languages section in the repository for more details.
In the Phi-3 CookBook, I used the following method to add the Korean translation for the existing markdown files and images.
(.venv) C:\Users\sms79\dev\Phi-3CookBook>translate -l"ko"
Translating images: 100%|███████████████████████████████████████████████████| 276/276 [1:09:56<00:00, 15.37s/it]
Translating markdown files: 100%|████████████████████████████████████████████████| 153/153 [1:43:07<00:00, 241.31s/it]To translate your project into multiple languages (e.g., Spanish, French, and German), use this command:
translate -l "es fr de"This command will translate the project into Spanish, French, and German, adding new translations without overwriting existing ones.
In the Phi-3 CookBook, after pulling the latest changes to reflect the most recent commits, I used the following method to translate newly added markdown files and images.
(.venv) C:\Users\sms79\dev\Phi-3CookBook>translate -l"ko ja zh tw es fr" -a
Translating images: 100%|███████████████████████████████████████████████████| 273/273 [1:09:56<00:00, 15.37s/it]
Translating markdown files: 100%|████████████████████████████████████████████████| 6/6 [24:07<00:00, 241.31s/it]Note
While it's generally recommended to translate one language at a time, in situations like this where specific changes need to be added, translating multiple languages at once can be efficient.
By default, the translator uses the current working directory. If your project is located elsewhere, specify the root directory with the -r option:
translate -l "es fr de" -r "./my_project"This command translates the files in ./my_project into Spanish, French, and German.
The default behavior is to add new translations without deleting existing ones. You can explicitly specify this by using the -a option:
translate -l "ko" -aThis command will add new translations in Korean without affecting the existing translations.
In the Phi-3 CookBook, to update the README.md translations, I first deleted the existing README.md translations and then used the following method to translate the updated content.
(.venv) C:\Users\sms79\dev\Phi-3CookBook>translate -l"ko ja zh tw es fr" -a
Translating markdown files: 100%|████████████████████████████████████████████████| 6/6 [24:07<00:00, 241.31s/it]To update existing translations (i.e., delete the current translations and replace them with new ones), use the -u option. This will delete all existing translations for the specified languages and re-translate them.
translate -l "ko" -uWarning: This command will prompt you for confirmation before proceeding with deleting the existing translations.
In the Phi-3 CookBook, I used the following method to update all translated files in Spanish. I recommend using this method when there are significant changes to the original content across multiple markdown documents. If there are only a few translated markdown files to update, it’s more efficient to manually delete those specific files and then use the -a method to add the updated translations.
(.venv) C:\Users\sms79\dev\Phi-3CookBook>translate -l "es" -u
Warning: The update command will delete all existing translations for 'es' and re-translate everything.
Do you want to continue? Type 'yes' to proceed: yes
Proceeding with update...
Translating images: 100%|████████████████████████████████████████████| 150/150 [43:46<00:00, 15.55s/it]
Translating markdown files: 100%|███████████████████████████████████| 95/95 [1:40:27<00:00, 125.62s/it]To translate only the image files in your project, use the -img option:
translate -l "ko" -imgThis command will translate only the images into Korean, without affecting any markdown files.
To translate only the markdown files in your project, use the -md option:
translate -l "ko" -mdIf you want to check translated files for errors and retry the translation if necessary, use the -chk option:
translate -l "ko" -chkThis command will scan the translated markdown files and retry translation for any files with errors.
In the Phi-3 CookBook, I used the following method to check for translation errors in the Korean files and automatically retry translation for any files with detected issues.
(.venv) C:\Users\sms79\dev\Phi-3CookBook>translate -l"ko" -chk
Checking translated files for errors in ko...
Checking files for ko: 100%|██████████████████████████████████████████████████| 95/95 [00:01<00:00, 65.47file/s]
Retrying vsc-extension-quickstart.md for ko: 0%| | 0/17 [00:00<?, ?file/s] This option checks for translation errors. Currently, if the difference in line breaks between the original and translated files is more than six, the file is flagged as having a translation error. I plan to improve this criterion for greater flexibility in the future.
For example, this method is useful for detecting missing chunks or corrupted translations, and it will automatically retry the translation for those files.
However, if you already know which files are problematic, it’s more efficient to manually delete those files and use the -a option to re-translate them.
To enable detailed logging for troubleshooting, use the -d option:
translate -l "ko" -dThis command will run the translation in debug mode, providing additional logging information that can help you identify issues during the translation process.
In the Phi-3 CookBook, I encountered an issue where translations with many links in markdown files caused formatting errors, such as broken translations and ignored line breaks. To diagnose this problem, I used the -d option to see how the translation process was works.
(.venv) C:\Users\sms79\dev\Phi-3CookBook>translate -l "ko" -d
DEBUG:openai._base_client:Request options: {'method': 'post', 'url': '/chat/completions', 'headers': {'api-key': 'af04e0bea45747d8a7b8c131c1971044'}, 'files': None, 'json_data': {'messages': [{'role': 'user', 'content': "Translate the following text to ko. NEVER ADD ANY EXTRA CONTENT OUTSIDE THE TRANSLATION. TRANSLATE ONLY WHAT IS GIVEN TO YOU.. MAINTAIN MARKDOWN FORMAT\n\n# Phi-3 Cookbook: Hands-On Examples with Microsoft's Phi-3 Models [](https://codespaces.new/microsoft/phi-3cookbook) [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%
...If you want to translate the project into all supported languages, use the all keyword.
Warning
Translating all languages at once can take a significant amount of time depending on the project size. For example, translating the Phi-3 CookBook into Spanish took about 2 hour. Given the scale, it's not practical for one person to handle 20 languages. It's recommended to split the work among multiple contributors, each managing one or two languages, and update translations gradually.
translate -l "all"This command will translate the project into all available languages. If you proceed, the translation may take a significant amount of time depending on the size of the project.