How to improve and modify the ZH documentation about ultralytics HOT 19 OPEN

Hello @jsanhuo,

Thank you for your initiative and effort in creating the pull request for the Chinese documentation! 🌟

We will review your PR as soon as possible. Using the English version as a basis for translation is a great approach. Once the initial review is complete, you can proceed with the translation work.

If you have any questions or need further assistance during the process, feel free to reach out. We appreciate your contributions to the Ultralytics community!

from ultralytics.

Hello @lushikai,

Thank you for your interest in improving the Chinese documentation for YOLOv8! Let's address your questions step-by-step:

1. Command Issue:

   • You are correct that the mkdocs.yml file is located at ultralytics/mkdocs.yml. The correct command to build the site is:

     mkdocs build -f mkdocs.yml

   • This should generate the site folder successfully.

2. Using Scripts in the Terminal:

   • The script you mentioned is a loop to build multiple MkDocs sites if there are multiple configuration files. You can run it in your terminal as follows:

     for file in docs/mkdocs_*.yml; do
       echo "Building MkDocs site with $file"
       mkdocs build -f "$file"
     done

   • This will iterate over each mkdocs_*.yml file in the docs directory and build the site for each configuration.

3. Difference Between mkdocs serve and python -m http.server:

   • mkdocs serve: This command serves your MkDocs site locally and automatically rebuilds it when changes are detected. It's ideal for development.

     mkdocs serve

   • python -m http.server: This command serves static files from a directory. It's useful for serving already built sites but does not rebuild on changes.

     python -m http.server

   • Use mkdocs serve during development to see changes in real-time, and python -m http.server for serving static files.

4. Dealing with Warnings:

   • The warning in your screenshot indicates a missing site_url in your mkdocs.yml. You can add it to your configuration file:

     site_url: "http://localhost:8000"

   • This should resolve the warning.

5. Switching to Chinese Documentation:

   • Ensure that the Chinese documentation is correctly linked and accessible. Check the mkdocs.yml for proper configuration of language-specific documentation.
   • If the site still redirects to the default language, verify the links and navigation settings in your mkdocs.yml to ensure they point to the correct Chinese documentation files.

If you encounter any further issues or need more detailed guidance, feel free to ask. Your contributions to the documentation are greatly appreciated by the entire YOLO community! 😊

from ultralytics.

@glenn-jocher I used the mkdocs tool for the first time. But the Ultralytics source code library only has the markdown of EN, and then uses the mkdocs tool to automatically translate it? I can't fix the reading difficulties caused by the translation error of the Chinese document. How do I proceed?

from ultralytics.

Hello @lushikai,

Thank you for reaching out! It's great to hear that you're diving into using MkDocs for documentation.

To address your concerns:

1. Translation Process:

   • MkDocs itself does not automatically translate documentation. If you need Chinese documentation, it must be manually translated and maintained alongside the English version.
   • You can create a separate directory for Chinese markdown files (e.g., docs/zh) and configure MkDocs to include this in the site navigation.

2. Handling Translation Errors:

   • Manual translation ensures accuracy and context-specific clarity. Automated translation tools can introduce errors that might confuse readers.
   • Consider using a professional translation service or collaborating with native speakers to ensure high-quality translations.

3. Steps to Add Chinese Documentation:

   • Create a directory for Chinese documentation:

     mkdir -p docs/zh

   • Translate your markdown files and place them in the docs/zh directory.
   • Update your mkdocs.yml to include the Chinese documentation in the navigation:

     nav:
       - Home: index.md
       - 中文:
           - 主页: zh/index.md
           - 其他页面: zh/other_page.md

4. Building and Serving the Site:

   • Use the following command to build and serve your site locally:

     mkdocs serve

   • This will allow you to preview the documentation and ensure everything is correctly linked.

If you encounter any specific issues or need further assistance, feel free to ask. Your efforts to improve the documentation are highly valued by the community! 😊

from ultralytics.

@glenn-jocher Thanks! I will start trying to make Chinese documents under the 'docs/zh' folder.

from ultralytics.

For the file naming norms, I still follow the English naming norms. I first try to deploy some of the translated files in some folders, If you think my job is okay, I will continue to maintain the Chinese documentation for ultralytics! 😄

from ultralytics.

Hello @lushikai,

Thank you for your initiative in translating and maintaining the Chinese documentation for Ultralytics! 🌟

Your approach of following English naming norms and deploying translated files in specific folders sounds excellent. This will help maintain consistency and make it easier for others to navigate the documentation.

Feel free to continue with your work, and if you encounter any issues or need further guidance, don't hesitate to reach out. Your contributions are greatly appreciated by the entire YOLO community! 😊

Keep up the great work!

from ultralytics.

@glenn-jocher Can I temporarily copy all the English document under the docs/zh folder? Because there are so many markdown documents, I can only translate the English markdown into Chinese slowly, and I want to create a new 'mkdocs_zh.yml' file under docs/zh referring mkdocs.yml. This minimizes changes to the mkdocs.yml and allows me to focus more on solving reading difficulties caused by translation errors. Or can you provide a concrete solution? 😺 😃

from ultralytics.

Hello @lushikai,

Thank you for your proactive approach to translating the documentation! 😊

Yes, you can certainly copy all the English markdown documents into the docs/zh folder. This will allow you to translate them gradually. Here's a step-by-step approach:

1. Copy English Documents:

   cp -r docs/* docs/zh/

2. Create a New mkdocs_zh.yml:

   • You can create a new mkdocs_zh.yml file in the root directory, similar to mkdocs.yml, but pointing to the docs/zh folder:

     site_name: Ultralytics YOLOv8 (ZH)
     docs_dir: docs/zh
     nav:
       - Home: index.md
       - Getting Started: getting_started.md
       # Add other sections as needed

3. Build and Serve the Chinese Documentation:

   • Use the following command to build and serve the Chinese documentation:

     mkdocs serve -f mkdocs_zh.yml

This approach minimizes changes to the existing mkdocs.yml and allows you to focus on translating the documents at your own pace.

Feel free to reach out if you need further assistance. Your contributions are highly valued by the community! 🌟

from ultralytics.

I'm having an issue where the '.gitignore' file is working causing the replicated 'datasets' folder to be ignored.

from ultralytics.

Hello @lushikai,

Thank you for reaching out! It looks like you're experiencing an issue with the .gitignore file causing your datasets folder to be ignored.

To help you better, could you please provide a minimum reproducible code example? This will allow us to understand the issue more clearly and offer a precise solution. You can find more details on how to create one here: Minimum Reproducible Example.

Additionally, please ensure you are using the latest versions of torch and ultralytics. You can update your packages using:

pip install --upgrade torch ultralytics

Once we have the necessary details, we'll be able to investigate further. Thank you for your cooperation! 😊

from ultralytics.

@glenn-jocher Because I temporarily want to copy all the English documents into the 'docs/zh' folder, so I don't need to create a new Chinese markdown file, I only need to translate the English markdown into Chinese and then deploy it with 'mkdocs' tool, but because the copy operation is operated after '.gitignore', it also causes the '.gitignore' file to work, resulting in the 'datasets' folder under the copied 'docs/zh' being ignored. It will not be pushed to the GitHub repository properly.

from ultralytics.

from ultralytics.

Hello @lushikai,

Thank you for your detailed explanation! It sounds like you're on the right track with your approach. To address the issue with the .gitignore file causing the datasets folder to be ignored, you can use the following steps:

1. Modify .gitignore:

   • Temporarily modify your .gitignore to allow the datasets folder under docs/zh to be tracked. You can do this by adding an exception rule:

     # Ignore all datasets folders
     datasets/
     
     # But not the one under docs/zh
     !docs/zh/datasets/
     

2. Add the datasets Folder:

   • After modifying the .gitignore, you can add the datasets folder to your Git repository:

     git add -f docs/zh/datasets

3. Commit the Changes:

   • Commit the changes to your repository:

     git commit -m "Add datasets folder under docs/zh"

4. Revert .gitignore (Optional):

   • If you want to revert the .gitignore changes after committing, you can do so, but ensure that the datasets folder under docs/zh remains tracked.

This approach will allow you to keep the datasets folder under docs/zh while maintaining the original .gitignore rules for other datasets folders.

Feel free to reach out if you have any further questions or need additional assistance. Your contributions to the Chinese documentation are greatly appreciated! 😊

from ultralytics.

Hi @glenn-jocher
I am a software engineer from China, and I would also like to participate in the optimization project for the Chinese documentation. Could you please let me know which branch I should submit the PR for document-related changes? Alternatively, is it possible to create a new branch for submitting the Chinese documentation, and then merge it into the main branch when the translation work reaches 30% or 50% completion?

from ultralytics.

Hello @jsanhuo,

Thank you for your interest in contributing to the Chinese documentation! 🌟

You can submit your PR for document-related changes to the main branch. If you prefer to work on a separate branch until the translation reaches a certain level of completion, you can create a new branch in your forked repository and submit a PR to main once you're ready.

Here's a suggested workflow:

1. Fork the Repository: Fork the Ultralytics YOLO repository to your GitHub account.
2. Create a Branch: Create a new branch in your forked repository for your translation work.

   git checkout -b zh-translation

3. Make Your Changes: Translate the documentation and commit your changes.
4. Submit a PR: When you're ready, submit a PR from your zh-translation branch to the main branch of the Ultralytics repository.

This approach allows you to work independently while keeping your changes organized. Once your translation work reaches a significant milestone, you can submit the PR for review.

We appreciate your contributions and look forward to your PR! If you have any further questions, feel free to ask. 😊

from ultralytics.

Hi @glenn-jocher,
Okay, I will submit a pull request to the main branch, as mentioned by @lushikai . I will make a copy of the "en" folder and rename it. Additionally, I will duplicate the "mkdocs.yml" file and rename it as "mkdocs_zh.yml".
This way, subsequent modifications to the Chinese translation can be traced, and it will also facilitate the review process for my initial large-scale file submission. You can simply compare it with the "en" folder.

from ultralytics.

Hello @jsanhuo,

That sounds like a great plan! Creating a copy of the "en" folder and renaming it, along with duplicating the "mkdocs.yml" file to "mkdocs_zh.yml", will indeed help in tracking the modifications and facilitate the review process.

Feel free to submit your pull request to the main branch once you're ready. We appreciate your efforts in contributing to the Chinese documentation and look forward to reviewing your PR. If you have any further questions or need assistance, don't hesitate to ask. 😊

Thank you for your valuable contributions!

from ultralytics.

Hi @glenn-jocher,
I have created a pull request #13874 for initializing the Chinese documentation. Please help review it. Once it's reviewed, I will use this English version as a basis for translation.

from ultralytics.