DeepL.cr

Crystal library for the DeepL language translation API.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     deepl:
       github: kojix2/deepl.cr

2. Run shards install

Usage

require "deepl"

# Translate text
t = DeepL::Translator.new(auth_key: "YOUR_AUTH_KEY")
result = t.translate_text("こんにちは、世界！", target_lang: "EN")
puts result.first.text # => "Hello, world!"

# Translate document
t = DeepL::Translator.new(auth_key: "YOUR_AUTH_KEY")
t.translate_document("path/to/document.pdf", target_lang: "EN")
# Save to file (default: "path/to/document_EN.pdf")

# Rephrase text (improve writing)
t = DeepL::Translator.new(auth_key: "YOUR_AUTH_KEY")
result = t.rephrase_text("I have went to the store yesterday.")
puts result[0].text # => "I went to the store yesterday."

# Voice realtime (v3 surface)
t = DeepL::Translator.new(auth_key: "YOUR_AUTH_KEY")
voice = t.get_voice_streaming_url(
  source_media_content_type: "audio/ogg; codecs=opus",
  source_language: "en",
  source_language_mode: "auto",
  target_languages: ["de", "fr"]
)
puts voice.streaming_url

See documentation.

Environment Variables

Name	Description
DEEPL_AUTH_KEY	DeepL API authentication key
DEEPL_TARGET_LANG	Default target language
DEEPL_USER_AGENT	User-Agent

• When the environment variable DEEPL_TARGET_LANG is set, the method DeepL::Translator#guess_target_language will prioritize the language defined in DEEPL_TARGET_LANG.
• However, please note that this does not directly affect translation methods like translate_text.

Development

• Pull requests are welcome.

• If you want to take over the project and become the owner, please submit your request with a pull request.

• DeepL OpenAPI Specification

API version selection (current behavior)

This library currently supports both v2 and v3 API families.

• The API surface is selected at compile time by either -Ddeepl_v2 / -Ddeepl_v3 or DEEPL_API_VERSION=v2 / DEEPL_API_VERSION=v3.
• In the v2 surface, translation, document, usage, language, rephrase, admin, and glossary methods use v2 endpoints.
• In the v3 surface, translation, document, usage, language, rephrase, and admin methods remain on v2 endpoints, while multilingual glossary, style rules, and voice realtime use v3 endpoints.

In short, the current v3 surface is hybrid: v2 for core translation flows, plus v3 for newer glossary, style-rule, and voice realtime features.

Run tests (v2 / v3)

• v2 (compile-time flag):

  crystal spec -Ddeepl_v2

• v3 (compile-time flag):

  crystal spec -Ddeepl_v3

• v2 (environment variable):

  DEEPL_API_VERSION=v2 crystal spec

• v3 (environment variable):

  DEEPL_API_VERSION=v3 crystal spec

Note: The library surface is also switched by the same conditions.

Use case

• DeepL CLI

Contributing

1. Fork it (https://github.com/kojix2/deepl.cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

MIT