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.
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" -u
Warning: 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" -img
This 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" -md
If you want to check translated files for errors and retry the translation if necessary, use the -chk option:
translate -l "ko" -chk
This 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" -d
This 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.
[!TIP]
Manually Deleting Translated Files (Optional)
Translated files are now automatically detected and cleaned up when a source file is updated.
However, if you want to manually update a translation - for example, to redo a specific file or override the system behavior - you can use the following command to delete all versions of the file across language folders.
On Windows:
- Using Command Prompt:
- Open Command Prompt.
- Navigate to the folder where the files are located using the
cdcommand.- Use the following command to delete files:
del /s *filename*Replace
filenamewith the specific part of the file name you’re looking for. The/soption searches subdirectories as well.- Using PowerShell:
- Open PowerShell.
- Run this command:
Get-ChildItem -Path "C:\YourPath" -Filter "*filename*" -Recurse | Remove-Item -ForceReplace
"C:\YourPath"with the folder path andfilenamewith the specific name.On macOS/Linux:
- Using Terminal:
- Open Terminal.
- Navigate to the directory with
cd.- Use the
findcommand:find . -type f -name "*filename*" -deleteReplace
filenamewith the specific name.Always double-check the files before deleting to avoid accidental loss.
Once you have deleted the files which need to be replace simply rerun your
translate -lcommand to update the most recent file changes.