From f64595f4f9eb8ba694e081a216ffb4c2d87654a3 Mon Sep 17 00:00:00 2001 From: Surya Balakrishnan Date: Sun, 12 Oct 2025 10:36:06 +0000 Subject: [PATCH 1/4] Add translation guidelines and issue template --- .github/ISSUE_TEMPLATE/i8n.md | 44 ++++++++++++++++++++++ docs/README.md | 4 ++ docs/TRANSLATING.md | 70 +++++++++++++++++++++++++++++++++++ 3 files changed, 118 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/i8n.md create mode 100644 docs/TRANSLATING.md diff --git a/.github/ISSUE_TEMPLATE/i8n.md b/.github/ISSUE_TEMPLATE/i8n.md new file mode 100644 index 000000000..849ae0574 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/i8n.md @@ -0,0 +1,44 @@ +--- +name: 🌐 Translating a new language? +about: Start a new translation effort in your language +title: '[i18n-] Translating docs to ' +labels: WIP +assignees: '' + +--- + + + +Hi! + +Let's bring the documentation to all the -speaking community 🌐 (currently 0 out of 21 complete) + +Who would want to translate? Please follow the đŸ€— [TRANSLATING guide](https://github.com/huggingface/smolagents/blob/main/docs/TRANSLATING.md). Here is a list of the files ready for translation. Let us know in this issue if you'd like to translate any, and we'll add your name to the list. + +Some notes: + +* Please translate using an informal tone (imagine you are talking with a friend about smolagents đŸ€—). +* Please translate in a gender-neutral way. +* Add your translations to the folder called `` inside the [source folder](https://github.com/huggingface/smolagents/tree/main/docs/source). +* Register your translation in `/_toctree.yml`; please follow the order of the [English version](https://github.com/huggingface/transformers/blob/main/docs/source/en/_toctree.yml). +* Once you're finished, open a pull request and tag this issue by including #issue-number in the description, where issue-number is the number of this issue. Please ping @albertvillanova for review. +* 🙋 If you'd like others to help you with the translation, you can also post in the đŸ€— [forums](https://discuss.huggingface.co/). + +## Get Started section + +- [ ] [index.md](https://github.com/huggingface/smolagents/blob/main/docs/source/en/index.md) https://github.com/huggingface/transformers/pull/20180 +- [ ] [quicktour.md](https://github.com/huggingface/smolagents/blob/main/docs/source/en/guided_tour.md) (waiting for initial PR to go through) +- [ ] [installation.md](https://github.com/huggingface/smolagents/blob/main/docs/source/en/installation.md). + +## Tutorial section +- [ ] [building_good_agents.md](https://github.com/huggingface/smolagents/blob/main/docs/source/en/tutorials/building_good_agents.md) +- [ ] [inspect_runs.md](https://github.com/huggingface/smolagents/blob/main/docs/source/en/tutorials/inspect_runs.md) +- [ ] [memory.md](https://github.com/huggingface/smolagents/blob/main/docs/source/en/tutorials/memory.md) +- [ ] [secure_code_execution.md](https://github.com/huggingface/smolagents/blob/main/docs/source/en/tutorials/secure_code_execution.md) +- [ ] [tools.md](https://github.com/huggingface/smolagents/blob/main/docs/source/en/tutorials/tools.md) + + \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index af4b61c6c..56bfe7083 100644 --- a/docs/README.md +++ b/docs/README.md @@ -121,6 +121,10 @@ Adding a new tutorial or section is done in two steps: Make sure to put your new file under the proper section. If you have a doubt, feel free to ask in a Github Issue or PR. +### Translating + +When translating, refer to the guide at [./TRANSLATING.md](https://github.com/huggingface/smolagents/blob/main/docs/TRANSLATING.md). + ### Writing source documentation Values that should be put in `code` should either be surrounded by backticks: \`like so\`. Note that argument names diff --git a/docs/TRANSLATING.md b/docs/TRANSLATING.md new file mode 100644 index 000000000..bef1bb1b8 --- /dev/null +++ b/docs/TRANSLATING.md @@ -0,0 +1,70 @@ +# Translating the Smolagents documentation into your language + +As part of our mission to democratize machine learning, we aim to make the Smolagents library available in many more languages! Follow the steps below to help translate the documentation into your language. + +## Open an Issue + +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. + +## Fork the Repository + +1. First, fork the Smolagents repo by clicking the Fork button in the top-right corner. +2. Clone your fork to your local machine for editing with the following command: + + ```bash + git clone https://github.com/YOUR-USERNAME/smolagents.git + ``` + + Replace `YOUR-USERNAME` with your GitHub username. + +## Copy-paste the English version with a new language code + +The documentation files are organized in the following directory: + +- **docs/source**: This contains all documentation materials organized by language. + +To copy the English version to your new language directory: + +1. Navigate to your fork of the repository: + + ```bash + cd ~/path/to/smolagents/docs + ``` + + Replace `~/path/to` with your actual path. + +2. Run the following command: + + ```bash + cp -r source/en source/LANG-ID + ``` + + Replace `LANG-ID` with the appropriate ISO 639-1 or ISO 639-2 language code (see [this table](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for reference). + +## Start translating + +Begin translating the text! + +1. Start with the `_toctree.yml` file that corresponds to your documentation chapter. This file is essential for rendering the table of contents on the website. + + - 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. + + Here’s an example structure for the `_toctree.yml` file: + + ```yaml + - sections: + - local: guided_tour # Keep this name for your .md file + title: Guided tour # Translate this + ... + title: Tutorials # Translate this + ``` + +2. Once you’ve translated the `_toctree.yml`, move on to translating the associated MD files. + +## 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 From 287106c2d7e113d3d831a804cd9e725d18cee1ed Mon Sep 17 00:00:00 2001 From: Surya Balakrishnan Date: Thu, 16 Oct 2025 09:34:23 +0000 Subject: [PATCH 2/4] =?UTF-8?q?Change=20=E2=80=99=20to=20ASCII=20apostroph?= =?UTF-8?q?e=20'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/TRANSLATING.md | 6 ++--- .../en/conceptual_guides/intro_agents.md | 6 ++--- docs/source/en/examples/text_to_sql.md | 26 +++++++++---------- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/TRANSLATING.md b/docs/TRANSLATING.md index bef1bb1b8..9c93ca33d 100644 --- a/docs/TRANSLATING.md +++ b/docs/TRANSLATING.md @@ -7,7 +7,7 @@ As part of our mission to democratize machine learning, we aim to make the Smola 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. +4. Post a comment indicating which chapters you'd like to work on, and we'll add your name to the list. ## Fork the Repository @@ -53,7 +53,7 @@ Begin translating the text! - 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. - Here’s an example structure for the `_toctree.yml` file: + Here's an example structure for the `_toctree.yml` file: ```yaml - sections: @@ -63,7 +63,7 @@ Begin translating the text! title: Tutorials # Translate this ``` -2. Once you’ve translated the `_toctree.yml`, move on to translating the associated MD files. +2. Once you've translated the `_toctree.yml`, move on to translating the associated MD files. ## Collaborate and share diff --git a/docs/source/en/conceptual_guides/intro_agents.md b/docs/source/en/conceptual_guides/intro_agents.md index 27c8867bb..427c3bfcf 100644 --- a/docs/source/en/conceptual_guides/intro_agents.md +++ b/docs/source/en/conceptual_guides/intro_agents.md @@ -32,7 +32,7 @@ while llm_should_continue(memory): # this loop is the multi-step part memory += [action, observations] ``` -This agentic system runs in a loop, executing a new action at each step (the action can involve calling some pre-determined *tools* that are just functions), until its observations make it apparent that a satisfactory state has been reached to solve the given task. Here’s an example of how a multi-step agent can solve a simple math question: +This agentic system runs in a loop, executing a new action at each step (the action can involve calling some pre-determined *tools* that are just functions), until its observations make it apparent that a satisfactory state has been reached to solve the given task. Here's an example of how a multi-step agent can solve a simple math question:
@@ -41,7 +41,7 @@ This agentic system runs in a loop, executing a new action at each step (the act ## ✅ When to use agents / ⛔ when to avoid them -Agents are useful when you need an LLM to determine the workflow of an app. But they’re often overkill. The question is: do I really need flexibility in the workflow to efficiently solve the task at hand? +Agents are useful when you need an LLM to determine the workflow of an app. But they're often overkill. The question is: do I really need flexibility in the workflow to efficiently solve the task at hand? If the pre-determined workflow falls short too often, that means you need more flexibility. Let's take an example: say you're making an app that handles customer requests on a surfing trip website. @@ -102,4 +102,4 @@ Writing actions in code rather than JSON-like snippets provides better: - **Composability:** could you nest JSON actions within each other, or define a set of JSON actions to re-use later, the same way you could just define a python function? - **Object management:** how do you store the output of an action like `generate_image` in JSON? - **Generality:** code is built to express simply anything you can have a computer do. -- **Representation in LLM training data:** plenty of quality code actions are already included in LLMs’ training data which means they’re already trained for this! +- **Representation in LLM training data:** plenty of quality code actions are already included in LLMs' training data which means they're already trained for this! diff --git a/docs/source/en/examples/text_to_sql.md b/docs/source/en/examples/text_to_sql.md index 130fe8963..816100484 100644 --- a/docs/source/en/examples/text_to_sql.md +++ b/docs/source/en/examples/text_to_sql.md @@ -2,7 +2,7 @@ [[open-in-colab]] -In this tutorial, we’ll see how to implement an agent that leverages SQL using `smolagents`. +In this tutorial, we'll see how to implement an agent that leverages SQL using `smolagents`. > Let's start with the golden question: why not keep it simple and use a standard text-to-SQL pipeline? @@ -10,7 +10,7 @@ A standard text-to-sql pipeline is brittle, since the generated SQL query can be 👉 Instead, an agent system is able to critically inspect outputs and decide if the query needs to be changed or not, thus giving it a huge performance boost. -Let’s build this agent! đŸ’Ș +Let's build this agent! đŸ’Ș Run the line below to install required dependencies: ```bash @@ -69,9 +69,9 @@ insert_rows_into_table(rows, receipts) ### Build our agent -Now let’s make our SQL table retrievable by a tool. +Now let's make our SQL table retrievable by a tool. -The tool’s description attribute will be embedded in the LLM’s prompt by the agent system: it gives the LLM information about how to use the tool. This is where we want to describe the SQL table. +The tool's description attribute will be embedded in the LLM's prompt by the agent system: it gives the LLM information about how to use the tool. This is where we want to describe the SQL table. ```py inspector = inspect(engine) @@ -89,7 +89,7 @@ Columns: - tip: FLOAT ``` -Now let’s build our tool. It needs the following: (read [the tool doc](../tutorials/tools) for more detail) +Now let's build our tool. It needs the following: (read [the tool doc](../tutorials/tools) for more detail) - A docstring with an `Args:` part listing arguments. - Type hints on both inputs and output. @@ -120,9 +120,9 @@ def sql_engine(query: str) -> str: Now let us create an agent that leverages this tool. -We use the `CodeAgent`, which is smolagents’ main agent class: an agent that writes actions in code and can iterate on previous output according to the ReAct framework. +We use the `CodeAgent`, which is smolagents' main agent class: an agent that writes actions in code and can iterate on previous output according to the ReAct framework. -The model is the LLM that powers the agent system. `InferenceClientModel` allows you to call LLMs using HF’s Inference API, either via Serverless or Dedicated endpoint, but you could also use any proprietary API. +The model is the LLM that powers the agent system. `InferenceClientModel` allows you to call LLMs using HF's Inference API, either via Serverless or Dedicated endpoint, but you could also use any proprietary API. ```py from smolagents import CodeAgent, InferenceClientModel @@ -136,9 +136,9 @@ agent.run("Can you give me the name of the client who got the most expensive rec ### Level 2: Table joins -Now let’s make it more challenging! We want our agent to handle joins across multiple tables. +Now let's make it more challenging! We want our agent to handle joins across multiple tables. -So let’s make a second table recording the names of waiters for each receipt_id! +So let's make a second table recording the names of waiters for each receipt_id! ```py table_name = "waiters" @@ -158,7 +158,7 @@ rows = [ ] insert_rows_into_table(rows, waiters) ``` -Since we changed the table, we update the `SQLExecutorTool` with this table’s description to let the LLM properly leverage information from this table. +Since we changed the table, we update the `SQLExecutorTool` with this table's description to let the LLM properly leverage information from this table. ```py updated_description = """Allows you to perform SQL queries on the table. Beware that this tool's output is a string representation of the execution output. @@ -175,7 +175,7 @@ for table in ["receipts", "waiters"]: print(updated_description) ``` -Since this request is a bit harder than the previous one, we’ll switch the LLM engine to use the more powerful [Qwen/Qwen2.5-Coder-32B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-32B-Instruct)! +Since this request is a bit harder than the previous one, we'll switch the LLM engine to use the more powerful [Qwen/Qwen2.5-Coder-32B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-32B-Instruct)! ```py sql_engine.description = updated_description @@ -187,11 +187,11 @@ agent = CodeAgent( agent.run("Which waiter got more total money from tips?") ``` -It directly works! The setup was surprisingly simple, wasn’t it? +It directly works! The setup was surprisingly simple, wasn't it? This example is done! We've touched upon these concepts: - Building new tools. - Updating a tool's description. - Switching to a stronger LLM helps agent reasoning. -✅ Now you can go build this text-to-SQL system you’ve always dreamt of! ✹ +✅ Now you can go build this text-to-SQL system you've always dreamt of! ✹ From d999a6fbc85d17e83e2339f40e7c3ee07ca41af2 Mon Sep 17 00:00:00 2001 From: Surya Balakrishnan Date: Thu, 16 Oct 2025 09:36:47 +0000 Subject: [PATCH 3/4] Change _toctree.yml copy instructions --- docs/TRANSLATING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/TRANSLATING.md b/docs/TRANSLATING.md index 9c93ca33d..9118056ee 100644 --- a/docs/TRANSLATING.md +++ b/docs/TRANSLATING.md @@ -50,7 +50,8 @@ Begin translating the text! 1. Start with the `_toctree.yml` file that corresponds to your documentation chapter. This file is essential for rendering the table of contents on the website. - - If the `_toctree.yml` file doesn't exist for your language, create one by copying the English version and removing unrelated sections. + - 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. Here's an example structure for the `_toctree.yml` file: From 69eff3837bdb9f7bf886587a1f18a9599777eb91 Mon Sep 17 00:00:00 2001 From: Surya Balakrishnan Date: Thu, 16 Oct 2025 09:56:49 +0000 Subject: [PATCH 4/4] Change wording and remove Albert's name. Replace with maintainers --- .github/ISSUE_TEMPLATE/i8n.md | 2 +- docs/TRANSLATING.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/i8n.md b/.github/ISSUE_TEMPLATE/i8n.md index 849ae0574..53c40163e 100644 --- a/.github/ISSUE_TEMPLATE/i8n.md +++ b/.github/ISSUE_TEMPLATE/i8n.md @@ -23,7 +23,7 @@ Some notes: * Please translate in a gender-neutral way. * Add your translations to the folder called `` inside the [source folder](https://github.com/huggingface/smolagents/tree/main/docs/source). * Register your translation in `/_toctree.yml`; please follow the order of the [English version](https://github.com/huggingface/transformers/blob/main/docs/source/en/_toctree.yml). -* Once you're finished, open a pull request and tag this issue by including #issue-number in the description, where issue-number is the number of this issue. Please ping @albertvillanova for review. +* Once you're finished, open a pull request and tag this issue by including #issue-number in the description, where issue-number is the number of this issue. Please ping the maintainers for review. * 🙋 If you'd like others to help you with the translation, you can also post in the đŸ€— [forums](https://discuss.huggingface.co/). ## Get Started section diff --git a/docs/TRANSLATING.md b/docs/TRANSLATING.md index 9118056ee..ae81edde0 100644 --- a/docs/TRANSLATING.md +++ b/docs/TRANSLATING.md @@ -64,8 +64,8 @@ Begin translating the text! title: Tutorials # Translate this ``` -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. ## 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 +If you'd like assistance with your translation, open an issue and tag the maintainers. Feel free to share resources or glossaries to ensure consistent terminology. \ No newline at end of file