DeepL Python库：简单高效的自然语言翻译工具

DeepL Python库简介

DeepL Python库是DeepL公司官方推出的Python客户端库,旨在为开发者提供一种便捷的方式与DeepL API进行交互。DeepL作为业界领先的机器翻译服务提供商,其API允许其他计算机程序将文本和文档发送到DeepL的服务器并接收高质量的翻译。这为开发者开启了无限可能,任何你能想象到的翻译产品现在都可以基于DeepL一流的翻译技术构建。

该库支持DeepL API的所有功能,包括文本翻译、文档翻译、术语表管理等。虽然新功能可能会在添加到API后才被添加到库中,但DeepL团队致力于保持库的全面性和及时更新。

获取认证密钥

要使用DeepL Python库,您首先需要获取一个API认证密钥。您可以通过创建DeepL账户来获得密钥。值得一提的是,使用DeepL API Free账户,您每月可以免费翻译多达500,000个字符。

获取密钥后,请务必妥善保管,不要在分享源代码时泄露您的密钥。

安装

DeepL Python库可以通过pip从PyPI安装:

pip install --upgrade deepl

如果您需要修改源代码,可以使用poetry安装依赖:

poetry install

系统要求

该库已在Python 3.6到3.11版本中进行了测试。它使用requests模块来执行HTTP请求,最低要求为2.0版本。

需要注意的是,从2024年开始,DeepL将不再支持已达到官方生命周期终止的旧Python版本。为了继续使用这个库,建议您更新到Python 3.8+版本。

基本用法

首先,导入包并构造一个Translator对象。第一个参数是包含您的API认证密钥的字符串:

import deepl

auth_key = "f63c02c5-f056-..."  # 替换为您的密钥
translator = deepl.Translator(auth_key)

result = translator.translate_text("Hello, world!", target_lang="FR")
print(result.text)  # "Bonjour, le monde !"

请注意,这个例子仅用于演示目的。在生产代码中,认证密钥不应硬编码,而应从配置文件或环境变量中获取。

Translator对象还接受其他选项,可以参考配置部分了解更多信息。

翻译文本

要翻译文本,调用translate_text()方法。第一个参数是包含要翻译的文本的字符串,或者如果要翻译多个文本,可以是字符串列表。

source_lang和target_lang参数分别指定源语言和目标语言代码。source_lang是可选的,如果未指定,源语言将被自动检测。

语言代码是不区分大小写的ISO 639-1字符串,例如'DE', 'FR', 'JA'。某些目标语言还包括根据ISO 3166-1的区域变体,例如'EN-US'或'PT-BR'。

# 将文本翻译成目标语言,在这个例子中是法语:
result = translator.translate_text("Hello, world!", target_lang="FR")
print(result.text)  # "Bonjour, le monde !"

# 将多个文本翻译成英式英语
result = translator.translate_text(
    ["お元気ですか？", "¿Cómo estás?"], target_lang="EN-GB"
)
print(result[0].text)  # "How are you?"
print(result[0].detected_source_lang)  # "JA" 日语的语言代码
print(result[1].text)  # "How are you?"
print(result[1].detected_source_lang)  # "ES" 西班牙语的语言代码

# 使用不同程度的正式性翻译成德语:
print(
    translator.translate_text(
        "How are you?", target_lang="DE", formality="less"
    )
)  # 'Wie geht es dir?'
print(
    translator.translate_text(
        "How are you?", target_lang="DE", formality="more"
    )
)  # 'Wie geht es Ihnen?'

translate_text()方法返回一个TextResult对象,或者对应于您输入文本的TextResult对象列表。TextResult有两个属性:text是翻译后的文本,detected_source_lang是检测到的源语言代码。

翻译文档

要翻译文档,您可以调用translate_document()方法使用文件IO对象,或者使用translate_document_from_filepath()方法使用文件路径。对于这两个函数,第一个和第二个参数分别对应输入和输出文件。

与translate_text()函数一样,source_lang和target_lang参数指定源语言和目标语言代码。

# 将一份正式文档从英语翻译成德语
input_path = "/path/to/Instruction Manual.docx"
output_path = "/path/to/Bedienungsanleitung.docx"
try:
    # 使用translate_document_from_filepath()和文件路径 
    translator.translate_document_from_filepath(
        input_path,
        output_path,
        target_lang="DE",
        formality="more"
    )

    # 或者您可以使用translate_document()和文件IO对象
    with open(input_path, "rb") as in_file, open(output_path, "wb") as out_file:
        translator.translate_document(
            in_file,
            out_file,
            target_lang="DE",
            formality="more"
        )

except deepl.DocumentTranslationException as error:
    # 如果在文档已上传后的文档翻译过程中发生错误,
    # 会抛出DocumentTranslationException。
    # document_handle属性包含可用于稍后从服务器检索文档或联系DeepL支持的文档句柄。
    doc_id = error.document_handle.id
    doc_key = error.document_handle.key
    print(f"Error after uploading ${error}, id: ${doc_id} key: ${doc_key}")
except deepl.DeepLException as error:
    # 上传过程中的错误会引发DeepLException
    print(error)

translate_document()和translate_document_from_filepath()是包装了多个API调用的便捷函数:上传、轮询状态直到翻译完成,以及下载。如果您的应用程序需要单独执行这些步骤,您可以直接使用以下函数:

• translate_document_upload()
• translate_document_get_status() (或 translate_document_wait_until_done())
• translate_document_download()

术语表

术语表允许您使用用户定义的术语来自定义翻译。多个术语表可以存储在您的账户中,每个术语表都有一个用户指定的名称和一个唯一分配的ID。

创建术语表

您可以使用create_glossary()方法创建带有所需术语和名称的术语表。每个术语表适用于单个源语言-目标语言对。请注意:术语表仅支持某些语言对,有关更多信息,请参阅列出可用的术语表语言。条目应指定为字典。

如果成功,术语表将创建并存储在您的DeepL账户中,并返回一个GlossaryInfo对象,包括ID、名称、语言和条目数。

# 创建一个包含两个术语的英语到德语术语表:
entries = {"artist": "Maler", "prize": "Gewinn"}
my_glossary = translator.create_glossary(
    "My glossary",
    source_lang="EN",
    target_lang="DE",
    entries=entries,
)
print(
    f"Created '{my_glossary.name}' ({my_glossary.glossary_id}) "
    f"{my_glossary.source_lang}->{my_glossary.target_lang} "
    f"containing {my_glossary.entry_count} entries"
)
# 示例输出: Created 'My glossary' (559192ed-8e23-...) EN->DE containing 2 entries

您还可以使用create_glossary_from_csv()从DeepL网站下载的术语表上传。不是将条目作为字典提供,而是将CSV数据指定为csv_data,可以是类文件对象、字符串或包含文件内容的字节:

# 打开CSV文件,假设使用UTF-8编码。如果您的文件包含BOM,
# 请考虑使用encoding='utf-8-sig'。
with open('/path/to/glossary_file.csv', 'r',  encoding='utf-8') as csv_file:
    csv_data = csv_file.read()  # 将文件内容读取为字符串
    my_csv_glossary = translator.create_glossary_from_csv(
        "CSV glossary",
        source_lang="EN",
        target_lang="DE",
        csv_data=csv_data,
    )

使用存储的术语表

您可以通过将glossary参数设置为术语表ID或GlossaryInfo对象来使用存储的术语表进行文本翻译。您还必须指定source_lang参数(使用术语表时需要):

text = "The artist was awarded a prize."
with_glossary = translator.translate_text(
    text, source_lang="EN", target_lang="DE", glossary=my_glossary,
)
print(with_glossary)  # "Der Maler wurde mit einem Gewinn ausgezeichnet."

# 作为比较,不使用术语表的结果:
without_glossary = translator.translate_text(text, target_lang="DE")
print(without_glossary)  # "Der Künstler wurde mit einem Preis ausgezeichnet."

使用存储的术语表进行文档翻译的方法相同:设置glossary参数并指定source_lang参数:

translator.translate_document(
    in_file, out_file, source_lang="EN", target_lang="DE", glossary=my_glossary,
)

translate_document(), translate_document_from_filepath()和translate_document_upload()函数都支持glossary参数。

检查账户使用情况

要检查账户使用情况,使用get_usage()函数:

usage = translator.get_usage()
if usage.any_limit_reached:
    print('Translation limit reached.')
if usage.character.valid:
    print(
        f"Character usage: {usage.character.count} of {usage.character.limit}")
if usage.document.valid:
    print(f"Document usage: {usage.document.count} of {usage.document.limit}")

返回的Usage对象包含三个使用子类型:character, document和team_document。根据您的账户类型,某些使用子类型可能无效;这可以使用valid属性进行检查。对于API账户:

• usage.character.valid为True
• usage.document.valid和usage.team_document.valid为False

每个有效的使用子类型都有count和limit属性,分别给出已使用的数量和最大数量,以及limit_reached属性,用于检查使用量是否达到限制。顶级Usage对象有any_limit_reached属性来检查所有使用子类型。

列出可用语言

您可以使用get_source_languages()和get_target_languages()函数请求DeepL支持的文本和文档语言列表。它们都返回一个Language对象列表。

name属性给出英语中的语言名称,code属性给出语言代码。supports_formality属性仅出现在目标语言中,表示目标语言是否支持可选的formality参数。

print("Source languages:")
for language in translator.get_source_languages():
    print(f"{language.name} ({language.code})")  # 示例: "German (DE)"

print("Target languages:")
for language in translator.get_target_languages():
    if language.supports_formality:
        print(f"{language.name} ({language.code}) supports formality")
        # 示例: "Italian (IT) supports formality"
    else:
        print(f"{language.name} ({language.code})")
        # 示例: "Lithuanian (LT)"

高级配置

日志记录

可以启用日志记录以查看库发送的HTTP请求和收到的响应。使用Python的logging模块启用和控制日志记录,例如:

import logging

logging.basicConfig()
logging.getLogger('deepl').setLevel(logging.DEBUG)