-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Add translation guidelines and issue template #1811
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you, that seems very clear!
PR quality check failed with errors unrelated to this PR. Those should be fixed in #1809. Merged this branch with |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks! Some comments/suggestions/questions below.
docs/TRANSLATING.md
Outdated
1. Navigate to the Issues page of this repository. | ||
2. Check if anyone has already opened an issue for your language. | ||
3. If not, create a new issue by selecting the "Translation template" from the "New issue" button. | ||
4. Post a comment indicating which chapters you’d like to work on, and we’ll add your name to the list. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For consistency with the rest of the docs, I would recommend to use the ASCII character for the apostrophe through all the docs:
4. Post a comment indicating which chapters you’d like to work on, and we’ll add your name to the list. | |
4. Post a comment indicating which chapters you'd like to work on, and we'll add your name to the list. |
There are other cases in this PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Replaced all non ASCII apostrophes in TRANSLATING.md
, intro_agents.md
and text_to_sql.md
docs/TRANSLATING.md
Outdated
- If the `_toctree.yml` file doesn't exist for your language, create one by copying the English version and removing unrelated sections. | ||
- Ensure it is placed in the `docs/source/LANG-ID/` directory. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Instead of removing unrelated section, I would recommend commenting out them: this will prevent Git merge conflicts when adding the translation of other sections in other PRs. Note that many users contributing to docs might not have the technical skills to resolve Git merge conflicts, so better avoiding them.
Maybe something like:
- If the `_toctree.yml` file doesn't exist for your language, create one by copying the English version and removing unrelated sections. | |
- Ensure it is placed in the `docs/source/LANG-ID/` directory. | |
- If the `_toctree.yml` file doesn't exist for your language, create one by copying the English version and commenting out unrelated sections (instead of deleting them) to avoid potential merge conflicts with other PRs. | |
- If the `_toctree.yml` file already exists for your language, open it and uncomment the sections that apply to the chapter you're translating. | |
- Ensure it is placed in the `docs/source/LANG-ID/` directory. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point! It will make it easier for documentation contributors
docs/TRANSLATING.md
Outdated
title: Tutorials # Translate this | ||
``` | ||
2. Once you’ve translated the `_toctree.yml`, move on to translating the associated MD files. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
2. Once you’ve translated the `_toctree.yml`, move on to translating the associated MD files. | |
2. Once you've set up and translated the `_toctree.yml`, proceed to translate the associated Markdown (`.md`) files. |
|
||
### Translating | ||
|
||
When translating, refer to the guide at [./TRANSLATING.md](https://github.com/huggingface/smolagents/blob/main/docs/TRANSLATING.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should locate the TRANSLATING.md
file at the root of the repo, what do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I copied the file location from the transformers repo (/docs)
One reason for them placing it in the docs folder could be that all documentation and instructions for contributing to the docs are located there. (e.g., /docs/README.md). So it is an intuitive location, but I don't have any strong opinions. I’m fine with moving it to the root of the repository if that’s what you prefer.
docs/TRANSLATING.md
Outdated
## Collaborate and share | ||
If you'd like assistance with your translation, open an issue and tag `@albertvillanova`. Feel free to share resources or glossaries to ensure consistent terminology. No newline at end of file |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure about personalizing the tag. What about something more general like:
If you'd like assistance with your translation, open an issue and tag `@albertvillanova`. Feel free to share resources or glossaries to ensure consistent terminology. | |
If you'd like assistance with your translation, open an issue and tag the documentation maintainers. Feel free to share resources or glossaries to ensure consistent terminology. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Copied it from the transformers
repo, I think they have a dedicated documentation maintainer
https://github.com/huggingface/transformers/blob/main/docs/TRANSLATING.md#collaborate-and-share
Changed it to maintainers
in this PR
@albertvillanova Thanks for the review. I've made the suggested changes. I have one clarification, Please take a look when you are free |
More details discussed in #1810
This PR adds guidelines to translate the documentation and a corresponding github issue template