Fix #890 by adjusting the guardrail document page (#903)

This pull request resolves #890 and enables the translation script to
accept a file to work on.

Author: seratch

docs/guardrails.md

@@ -23,7 +23,7 @@ Input guardrails run in 3 steps:
 
 Output guardrails run in 3 steps:
 
-1. First, the guardrail receives the same input passed to the agent.
+1. First, the guardrail receives the output produced by the agent.
 2. Next, the guardrail function runs to produce a [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput], which is then wrapped in an [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult]
 3. Finally, we check if [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] is true. If true, an [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] exception is raised, so you can appropriately respond to the user or handle the exception.
 

docs/ja/guardrails.md

@@ -4,44 +4,44 @@ search:
 ---
 # ガードレール
 
-ガードレールは エージェント と _並列_ に実行され、 ユーザー入力 のチェックとバリデーションを行います。たとえば、顧客からのリクエストを支援するために非常に賢い (そのため遅く / 高価な) モデルを使うエージェントがあるとします。悪意のある ユーザー がモデルに数学の宿題を手伝わせようとするのは避けたいですよね。その場合、 高速 / 低コスト のモデルでガードレールを実行できます。ガードレールが悪意のある利用を検知した場合、即座にエラーを送出して高価なモデルの実行を停止し、時間と費用を節約できます。
+ガードレールは エージェント と _並行して_ 実行され、ユーザー入力のチェックとバリデーションを行えます。例えば、とても賢い（つまり遅く/高価な）モデルを使用してカスタマーリクエストを処理するエージェントがあるとします。悪意のある ユーザー がモデルに数学の宿題を手伝わせようとするのは避けたいでしょう。そこで、速く/安価なモデルで動くガードレールを実行できます。ガードレールが悪意のある利用を検知すると、直ちにエラーを送出して高価なモデルの実行を停止し、時間とコストを節約できます。
 
-ガードレールには 2 種類あります。
+ガードレールには 2 種類あります:
 
-1. Input ガードレールは最初の ユーザー入力 に対して実行されます  
-2. Output ガードレールは最終的なエージェント出力に対して実行されます  
+1. 入力ガードレール は初期 ユーザー 入力に対して実行されます  
+2. 出力ガードレール は最終的なエージェント出力に対して実行されます  
 
-## Input ガードレール
+## 入力ガードレール
 
-Input ガードレールは 3 つのステップで実行されます。
+入力ガードレールは 3 ステップで実行されます:
 
 1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。  
-2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] でラップされます。  
-3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるので、 ユーザー への適切な応答や例外処理を行えます。  
+2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`InputGuardrailResult`][agents.guardrail.InputGuardrailResult] にラップされます。  
+3. 最後に [.tripwire_triggered][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered] 例外が送出されるので、適切に ユーザー に応答したり例外を処理できます。  
 
 !!! Note
 
-    Input ガードレールは ユーザー入力 に対して実行されることを想定しているため、エージェントのガードレールが実行されるのはそのエージェントが *最初* のエージェントである場合だけです。「なぜ `guardrails` プロパティがエージェントにあり、 `Runner.run` に渡さないのか？」と思うかもしれません。ガードレールは実際の エージェント に密接に関連する場合が多く、エージェントごとに異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上するからです。
+    入力ガードレールは ユーザー 入力に対して実行されることを意図しているため、ガードレールは *最初* のエージェントでのみ実行されます。「なぜ `guardrails` プロパティがエージェントにあり、`Runner.run` に渡さないのか」と疑問に思うかもしれません。これは、ガードレールが実際の エージェント と密接に関連していることが多いからです。異なるエージェントには異なるガードレールを実行するため、コードを同じ場所に置くことで可読性が向上します。
 
-## Output ガードレール
+## 出力ガードレール
 
-Output ガードレールは 3 つのステップで実行されます。
+出力ガードレールは 3 ステップで実行されます:
 
-1. まず、ガードレールはエージェントに渡されたものと同じ入力を受け取ります。  
-2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] でラップされます。  
-3. 最後に [`.tripwire_triggered`][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出されるので、 ユーザー への適切な応答や例外処理を行えます。  
+1. まず、ガードレールはエージェントが生成した出力を受け取ります。  
+2. 次に、ガードレール関数が実行され [`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を生成し、それが [`OutputGuardrailResult`][agents.guardrail.OutputGuardrailResult] にラップされます。  
+3. 最後に [.tripwire_triggered][agents.guardrail.GuardrailFunctionOutput.tripwire_triggered] が true かどうかを確認します。true の場合、[`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] 例外が送出されるので、適切に ユーザー に応答したり例外を処理できます。  
 
 !!! Note
 
-    Output ガードレールは最終的なエージェント出力に対して実行されることを想定しているため、エージェントのガードレールが実行されるのはそのエージェントが *最後* のエージェントである場合だけです。Input ガードレール同様、ガードレールは実際の エージェント に密接に関連するため、コードを同じ場所に置くことで可読性が向上します。
+    出力ガードレールは最終的なエージェント出力に対して実行されることを意図しているため、ガードレールは *最後* のエージェントでのみ実行されます。入力ガードレールの場合と同様、ガードレールが実際の エージェント と密接に関連していることが多いため、コードを同じ場所に置くことで可読性が向上します。
 
-## トリップワイヤ
+## トリップワイヤー
 
-入力または出力がガードレールに失敗した場合、ガードレールはトリップワイヤを用いてそれを通知できます。ガードレールがトリップワイヤを発火したことを検知すると、ただちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出してエージェントの実行を停止します。
+入力または出力がガードレールを通過できなかった場合、ガードレールはトリップワイヤーでそれを示すことができます。トリップワイヤーがトリガーされたガードレールを検知した時点で、直ちに `{Input,Output}GuardrailTripwireTriggered` 例外を送出し、エージェントの実行を停止します。
 
 ## ガードレールの実装
 
-入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を用意する必要があります。次の例では、内部で エージェント を実行してこれを行います。
+入力を受け取り、[`GuardrailFunctionOutput`][agents.guardrail.GuardrailFunctionOutput] を返す関数を提供する必要があります。この例では、内部で エージェント を実行してこれを行います。
 
 ```python
 from pydantic import BaseModel
@@ -94,12 +94,12 @@ async def main():
         print("Math homework guardrail tripped")
 ```
 
-1. この エージェント をガードレール関数内で使用します。  
-2. これはエージェントの入力 / コンテキストを受け取り、結果を返すガードレール関数です。  
+1. このエージェントをガードレール関数内で使用します。  
+2. これはエージェントの入力/コンテキストを受け取り、結果を返すガードレール関数です。  
 3. ガードレール結果に追加情報を含めることができます。  
 4. これはワークフローを定義する実際のエージェントです。  
 
-Output ガードレールも同様です。
+出力ガードレールも同様です。
 
 ```python
 from pydantic import BaseModel
@@ -155,4 +155,4 @@ async def main():
 1. これは実際のエージェントの出力型です。  
 2. これはガードレールの出力型です。  
 3. これはエージェントの出力を受け取り、結果を返すガードレール関数です。  
-4. これはワークフローを定義する実際のエージェントです。
+4. これはワークフローを定義する実際のエージェントです。  

docs/scripts/translate_docs.py

@@ -1,5 +1,7 @@
 # ruff: noqa
 import os
+import sys
+import argparse
 from openai import OpenAI
 from concurrent.futures import ThreadPoolExecutor
 
@@ -263,24 +265,45 @@ def translate_single_source_file(file_path: str) -> None:
 
 
 def main():
-    # Traverse the source directory
-    for root, _, file_names in os.walk(source_dir):
-        # Skip the target directories
-        if any(lang in root for lang in languages):
-            continue
-        # Increasing this will make the translation faster; you can decide considering the model's capacity
-        concurrency = 6
-        with ThreadPoolExecutor(max_workers=concurrency) as executor:
-            futures = []
-            for file_name in file_names:
-                filepath = os.path.join(root, file_name)
-                futures.append(executor.submit(translate_single_source_file, filepath))
-                if len(futures) >= concurrency:
-                    for future in futures:
-                        future.result()
-                    futures.clear()
-
-    print("Translation completed.")
+    parser = argparse.ArgumentParser(description="Translate documentation files")
+    parser.add_argument("--file", type=str, help="Specific file to translate (relative to docs directory)")
+    args = parser.parse_args()
+
+    if args.file:
+        # Translate a single file
+        # Handle both "foo.md" and "docs/foo.md" formats
+        if args.file.startswith("docs/"):
+            # Remove "docs/" prefix if present
+            relative_file = args.file[5:]
+        else:
+            relative_file = args.file
+
+        file_path = os.path.join(source_dir, relative_file)
+        if os.path.exists(file_path):
+            translate_single_source_file(file_path)
+            print(f"Translation completed for {relative_file}")
+        else:
+            print(f"Error: File {file_path} does not exist")
+            sys.exit(1)
+    else:
+        # Traverse the source directory (original behavior)
+        for root, _, file_names in os.walk(source_dir):
+            # Skip the target directories
+            if any(lang in root for lang in languages):
+                continue
+            # Increasing this will make the translation faster; you can decide considering the model's capacity
+            concurrency = 6
+            with ThreadPoolExecutor(max_workers=concurrency) as executor:
+                futures = []
+                for file_name in file_names:
+                    filepath = os.path.join(root, file_name)
+                    futures.append(executor.submit(translate_single_source_file, filepath))
+                    if len(futures) >= concurrency:
+                        for future in futures:
+                            future.result()
+                        futures.clear()
+
+        print("Translation completed.")
 
 
 if __name__ == "__main__":