textra-api-wrapper 0.4.0

textraの翻訳APIラッパー

textra-api-wrapper

本APIラッパーは、みんなの自動翻訳＠TexTra®を利用してテキスト翻訳を行うためのPythonラッパーです。

特徴

• 簡単にAPIを利用して翻訳を実行できます。
• Wikipediaやオープンソースソフトウェアのドキュメントの翻訳に適しています。

注意事項

• 本APIラッパーは「みんなの自動翻訳＠TexTra®」の利用規約に基づき、商用目的での利用を禁止しています。
• 不適切な利用が発見された場合、APIの利用が制限されることがあります。
• 利用回数に上限が設けられる場合があります。
• サービス提供期間は保証されていません。
• 入力されたテキストや用語はNICTのサーバーに記録されることがあります。個人情報や機密情報を入力しないようお願いします。

インストール

pip install textra-api-wrapper

Usage

環境変数の設定

利用の前に以下の環境変数を設定してください。

• TEXTRA_LOGIN_ID: ログインID
• TEXTRA_API_KEY: API_KEY
• TEXTRA_API_SECRET: API_SECRET

ターミナルから設定する例を示します。

export TEXTRA_LOGIN_ID='your_login_id'
export TEXTRA_API_KEY='your_api_key'
export TEXTRA_API_SECRET='your_api_secret'

利用中のOSやシェルによって設定方法は異なりますのでご注意ください。

使用例

テストコードをご参照ください。

from textra_api_wrapper import APIClient


def test_client():
    client = APIClient()
    text = "Hello everyone. My name is ｟John.｠"
    res = client.translate(text)

    expected = "皆さんこんにちは、John.と申します。"
    assert res.text == expected
    assert res.original_text == text
    assert res.information["text-s"] == text
    assert res.information["text-t"] == expected
    assert (
        res.request_url
        == "https://mt-auto-minhon-mlt.ucri.jgn-x.jp/"
    )

• APIClient()により生成されるインスタンスは、英語から日本語への翻訳となります。
• 翻訳不要記号で囲むことで原文をそのまま出力します。例: ｟John.｠
• 言語の指定はAPIClient(source_lang="ja", target_lang="en")などとします。

def test_ja_to_en():
    client = APIClient(source_lang="ja", target_lang="en")
    text = "こんにちは、皆さん。私の名前は｟タロー｠です"
    res = client.translate(text)

    expected = "Hi everyone. My name is タロー."
    assert res.text == expected
    assert res.original_text == text
    assert (
        res.request_url
        == "https://mt-auto-minhon-mlt.ucri.jgn-x.jp/api/mt/generalNT_ja_en/"
    )

ファイル翻訳

ファイル翻訳APIは3つのエンドポイントがあります。登録 (set)、確認 (status)、取得 (get) です。set を行うと API サーバで翻訳が実行されますが、ファイル単位なのである程度の時間がかかります。そのため、登録時には PID のみが返ります。status は翻訳状況の確認、get でファイルを取得できます。

set_file(path)

path で翻訳元のファイルパスを指定します。実行時点では処理が完了していない可能性があります。 APIResponseParserのインスタンスが返ります。

APIの仕様により、ファイルの拡張子は限定されています。サポート外の拡張子は内部で.txtに変換されます。

client = APIClient()
original_filepath = "tests/example_file.cfg"
sample = client.set_file(original_filepath)

sample.get("pid") # 12345
sample.request["title"] # "example_file"

titleはファイル名から拡張子を除いたものになります。

file_status()

ファイル翻訳の状況を確認できます。state は状態を表します。

• -2: 失敗
• 0: 待機中
• 1: 処理中
• 2: 完了

client = APIClient()
sample = client.file_status()
sample.get('list')
# Example
# [
#     {
#         'id': 71204,
#         'register': '2024-07-15 09:49:24',
#         'state': 2,
#         'title': 'test_file',
#     },
#     {
#         'id': 71181,
#         'register': '2024-07-14 15:19:50',
#         'state': 2,
#         'title': 'README_en_t',
#     },
# ]

sample.get_status({"id": 71204})
# {
#     'id': 71204,
#     'register': '2024-07-15 09:49:24',
#     'state': 2,
#     'title': 'test_file',
# }

get_file(pid, encoding="utf-8", path=None)

API サーバから翻訳済みのファイルを取得して内容を返します。path を指定すると保存します。

• pid: ファイル翻訳ID
• encoding (オプション): デフォルトでは utf-8
• path (オプション): 翻訳後のファイルを保存する場所

def test_get_file():
    client = APIClient()
    path = "tests/test_file_result.txt"
    res = client.get_file(pid=71204, path=path)

# Example:
# "ハイテク大手、革新的なAIツールを発表"

translate_files(files, output_dir=None, sleep=15, encoding="utf-8", extension="txt")

複数ファイルを一括で翻訳し、指定されたディレクトリに保存します。登録から取得の間ではサーバーの処理が終了するまで待機する必要があるため、sleepオプションを短くしても処理が速くなるわけではありません。

引数

• files (list): 翻訳元ファイルのパスをリスト形式で指定します。例: ["path/to/file1.txt", "path/to/file2.txt"]
• output_dir (str, オプション): 翻訳されたファイルを保存するディレクトリ。指定しない場合、翻訳されたファイルは保存されません。
• sleep (int, オプション): リクエスト間で待機する秒数。デフォルトは15秒です。
• encoding (str, オプション): ファイルのエンコーディング。デフォルトは "utf-8" です。
• extension (str, オプション): 翻訳されたファイルの拡張子。デフォルトは "txt" です。

使用例

from textra_api_wrapper import APIClient

def test_translate_files(tmpdir):
    client = APIClient()
    files = ["tests/text_en.cfg", "tests/text_en02.txt"]
    res = client.translate_files(files, output_dir=tmpdir, extension="csv")
    print(res)
    # 出力例:
    # [
    #   "ハイテク大手、革新的なAIツールを発表...",
    #   "太陽光発電でグリーンエネルギーのマイルストーンを達成..."
    # ]

注意事項

• サーバー処理の待機: sleepオプションを短く設定しても処理速度は変わりません。サーバーの処理が終了するまで待機する必要があります。
• ファイル拡張子: Textraの仕様により、翻訳できるファイルの拡張子は限定されています。サポート外の拡張子は内部的にtxtに変更されるため、元の拡張子に戻すにはextensionを指定する必要があります。

オプションの詳細

• output_dirを指定しない場合、翻訳されたファイルは保存されません。出力結果は関数の戻り値として取得します。
• encodingのデフォルト値は"utf-8"ですが、他のエンコーディングを使用する場合は適宜指定してください。
• extensionのデフォルト値は"txt"です。必要に応じて"csv"や他の拡張子を指定してください。

License

本APIラッパーはMITライセンスにより提供されますが、利用にはみんなの自動翻訳＠TexTra®の利用規約に従う必要がありますのでご注意ください。
詳細についてはLICENSEファイルを参照してください。