deepl-rb 2.5.3 → 3.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (86) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/add_issues_to_kanban.yml +16 -0
  3. data/.gitlab-ci.yml +135 -0
  4. data/.rubocop.yml +27 -0
  5. data/CHANGELOG.md +34 -0
  6. data/CODE_OF_CONDUCT.md +132 -0
  7. data/CONTRIBUTING.md +37 -0
  8. data/Gemfile +3 -1
  9. data/LICENSE.md +1 -0
  10. data/README.md +115 -5
  11. data/Rakefile +7 -5
  12. data/SECURITY.md +58 -0
  13. data/VERSION +1 -1
  14. data/deepl-rb.gemspec +36 -20
  15. data/lib/deepl/api.rb +11 -1
  16. data/lib/deepl/configuration.rb +34 -3
  17. data/lib/deepl/document_api.rb +120 -0
  18. data/lib/deepl/exceptions/authorization_failed.rb +3 -0
  19. data/lib/deepl/exceptions/bad_request.rb +3 -0
  20. data/lib/deepl/exceptions/document_translation_error.rb +15 -0
  21. data/lib/deepl/exceptions/error.rb +6 -0
  22. data/lib/deepl/exceptions/limit_exceeded.rb +7 -0
  23. data/lib/deepl/exceptions/not_found.rb +3 -0
  24. data/lib/deepl/exceptions/not_supported.rb +3 -0
  25. data/lib/deepl/exceptions/quota_exceeded.rb +3 -0
  26. data/lib/deepl/exceptions/request_entity_too_large.rb +3 -0
  27. data/lib/deepl/exceptions/request_error.rb +4 -2
  28. data/lib/deepl/exceptions/server_error.rb +18 -0
  29. data/lib/deepl/glossary_api.rb +3 -0
  30. data/lib/deepl/requests/base.rb +89 -34
  31. data/lib/deepl/requests/document/download.rb +44 -0
  32. data/lib/deepl/requests/document/get_status.rb +44 -0
  33. data/lib/deepl/requests/document/upload.rb +64 -0
  34. data/lib/deepl/requests/glossary/create.rb +15 -1
  35. data/lib/deepl/requests/glossary/destroy.rb +8 -1
  36. data/lib/deepl/requests/glossary/entries.rb +8 -1
  37. data/lib/deepl/requests/glossary/find.rb +8 -1
  38. data/lib/deepl/requests/glossary/language_pairs.rb +9 -2
  39. data/lib/deepl/requests/glossary/list.rb +9 -2
  40. data/lib/deepl/requests/languages.rb +9 -2
  41. data/lib/deepl/requests/translate.rb +33 -11
  42. data/lib/deepl/requests/usage.rb +9 -2
  43. data/lib/deepl/resources/base.rb +3 -0
  44. data/lib/deepl/resources/document_handle.rb +57 -0
  45. data/lib/deepl/resources/document_translation_status.rb +54 -0
  46. data/lib/deepl/resources/glossary.rb +3 -0
  47. data/lib/deepl/resources/language.rb +3 -0
  48. data/lib/deepl/resources/language_pair.rb +3 -0
  49. data/lib/deepl/resources/text.rb +3 -0
  50. data/lib/deepl/resources/usage.rb +3 -0
  51. data/lib/deepl/utils/backoff_timer.rb +46 -0
  52. data/lib/deepl/utils/exception_builder.rb +18 -13
  53. data/lib/deepl.rb +47 -0
  54. data/lib/http_client_options.rb +22 -0
  55. data/license_checker.sh +8 -0
  56. data/spec/api/api_spec.rb +8 -4
  57. data/spec/api/configuration_spec.rb +92 -18
  58. data/spec/api/deepl_spec.rb +225 -86
  59. data/spec/fixtures/vcr_cassettes/deepl_document.yml +95 -0
  60. data/spec/fixtures/vcr_cassettes/deepl_document_download.yml +1214 -0
  61. data/spec/fixtures/vcr_cassettes/deepl_glossaries.yml +812 -23
  62. data/spec/fixtures/vcr_cassettes/deepl_languages.yml +28 -17
  63. data/spec/fixtures/vcr_cassettes/deepl_translate.yml +161 -53
  64. data/spec/fixtures/vcr_cassettes/deepl_usage.yml +93 -3
  65. data/spec/fixtures/vcr_cassettes/glossaries.yml +1237 -15
  66. data/spec/fixtures/vcr_cassettes/languages.yml +159 -44
  67. data/spec/fixtures/vcr_cassettes/translate_texts.yml +9742 -12
  68. data/spec/fixtures/vcr_cassettes/usage.yml +134 -2
  69. data/spec/integration_tests/document_api_spec.rb +143 -0
  70. data/spec/integration_tests/integration_test_utils.rb +170 -0
  71. data/spec/requests/glossary/create_spec.rb +23 -13
  72. data/spec/requests/glossary/destroy_spec.rb +33 -17
  73. data/spec/requests/glossary/entries_spec.rb +31 -17
  74. data/spec/requests/glossary/find_spec.rb +31 -17
  75. data/spec/requests/glossary/language_pairs_spec.rb +17 -7
  76. data/spec/requests/glossary/list_spec.rb +21 -11
  77. data/spec/requests/languages_spec.rb +31 -21
  78. data/spec/requests/translate_spec.rb +125 -131
  79. data/spec/requests/usage_spec.rb +17 -7
  80. data/spec/resources/glossary_spec.rb +15 -12
  81. data/spec/resources/language_pair_spec.rb +10 -7
  82. data/spec/resources/language_spec.rb +21 -18
  83. data/spec/resources/text_spec.rb +10 -7
  84. data/spec/resources/usage_spec.rb +16 -13
  85. data/spec/spec_helper.rb +63 -6
  86. metadata +32 -9
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d0f4d3d2ddeeb7156fd35df3906d1a176d9e66b64c8d936ff2fb7fc3681cb437
4
- data.tar.gz: 2d15451265aed72177fdf9692e44a5ca5f19750db4c620a009e482a708232ddf
3
+ metadata.gz: aac8ae68e851fd09ed5a981e7ff9b796efbccbb7df0abdea0cf9bffe218ab71d
4
+ data.tar.gz: aeca955e569454056d75b54285c2a91d953d3bbd35ee38c1df7fb59bc92fec69
5
5
  SHA512:
6
- metadata.gz: c949370aa698d2c891c8961e17c94b914e7a7f9942584ca2ef8664cad22dcf03169d5512d5caa2d43d3c2ee65a9d19a9eb2231d1b7766eab444430a18d84c75b
7
- data.tar.gz: aa188f9969cfdbd0b0355d2f58afb828358be8078487e52f2c2ac3bdc518e9a6d5c718c8652461c612a9cf39dba15ff4b157b5335fd3282a570f425bd245ade4
6
+ metadata.gz: a86b786b98936c4a21e3a1d5ee7ed2a5b468c8d35b26b7af43b1ecb7609393b4abbd035bee6d69a39f9b52b38a707fac3d413dabdddee126605dd3d66baf22e7
7
+ data.tar.gz: 48c99a192c395dd34bd08bd3cc32ebb481bb5c8d96625365e6974af436e7ff44e78617343eb3403c1057bafe1fcb3774c7cd651e94364316e025ccc7be3f20b3
@@ -0,0 +1,16 @@
1
+ name: Add bugs to bugs project
2
+
3
+ on:
4
+ issues:
5
+ types:
6
+ - opened
7
+
8
+ jobs:
9
+ add-to-project:
10
+ name: Add issue to project
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/add-to-project@v0.5.0
14
+ with:
15
+ project-url: https://github.com/orgs/DeepLcom/projects/1
16
+ github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
data/.gitlab-ci.yml ADDED
@@ -0,0 +1,135 @@
1
+ # Note: This GitLab CI configuration is used for internal testing, users can ignore it.
2
+ include:
3
+ - project: '${CI_PROJECT_NAMESPACE}/ci-libs-for-client-libraries'
4
+ file:
5
+ - '/${CI_PROJECT_NAME}/.gitlab-ci.yml'
6
+ - project: 'deepl/ops/ci-cd-infrastructure/gitlab-ci-lib'
7
+ file:
8
+ - '/templates/.buildkit.yml'
9
+ - '/templates/.secret-detection.yml'
10
+
11
+ # Global --------------------------
12
+
13
+ workflow:
14
+ rules:
15
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
16
+ - if: $CI_COMMIT_TAG
17
+ - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
18
+
19
+ stages:
20
+ - install
21
+ - check
22
+ - test
23
+ # - publish
24
+
25
+
26
+ before_script:
27
+ - ruby --version
28
+ - bundle install
29
+
30
+ # stage: install ----------------------
31
+
32
+ package:
33
+ stage: install
34
+ parallel:
35
+ matrix:
36
+ - DOCKER_IMAGE: 'ruby:2.7'
37
+ - DOCKER_IMAGE: 'ruby:3.2'
38
+ - DOCKER_IMAGE: 'ruby:3.3'
39
+ image:
40
+ name: ${DOCKER_IMAGE}
41
+ entrypoint: ['/builds/deepl/backend/oss-client-libs/deepl-ruby']
42
+ script:
43
+ - bundle exec rake build
44
+ artifacts:
45
+ paths:
46
+ - pkg/
47
+
48
+ # stage: check ----------------------
49
+
50
+ .rubocop_base:
51
+ stage: check
52
+ image:
53
+ name: ruby:2.7
54
+ entrypoint: ['/builds/deepl/backend/oss-client-libs/deepl-ruby']
55
+ script: bundle exec rubocop
56
+
57
+ rubocop_scheduled:
58
+ extends: .rubocop_base
59
+ rules:
60
+ - if: $CI_PIPELINE_SOURCE == "schedule"
61
+ retry: 2
62
+
63
+ rubocop_manual:
64
+ extends: .rubocop_base
65
+ rules:
66
+ - if: $CI_PIPELINE_SOURCE != "schedule"
67
+
68
+ secret_detection:
69
+ extends: .secret-detection
70
+ stage: check
71
+ image: !reference [.secret-detection, image]
72
+ before_script:
73
+ - echo "overriding default before_script..."
74
+ rules:
75
+ - if: $CI_MERGE_REQUEST_ID
76
+
77
+ license_check:
78
+ stage: check
79
+ before_script:
80
+ - echo "overriding default before_script..."
81
+ script:
82
+ - ./license_checker.sh '*.rb' | tee license_check_output.txt
83
+ - '[ ! -s license_check_output.txt ]'
84
+
85
+
86
+ # stage: test ----------------------
87
+
88
+ .test_base:
89
+ stage: test
90
+ extends: .test
91
+ parallel:
92
+ matrix:
93
+ - DOCKER_IMAGE: 'ruby:2.7'
94
+ - DOCKER_IMAGE: 'ruby:3.2'
95
+ - DOCKER_IMAGE: 'ruby:3.3'
96
+ - DOCKER_IMAGE: 'ruby:2.7'
97
+ USE_MOCK_SERVER: "use mock server"
98
+ - DOCKER_IMAGE: 'ruby:3.2'
99
+ USE_MOCK_SERVER: "use mock server"
100
+ - DOCKER_IMAGE: 'ruby:3.3'
101
+ USE_MOCK_SERVER: "use mock server"
102
+ image:
103
+ name: ${DOCKER_IMAGE}
104
+ entrypoint: ['/builds/deepl/backend/oss-client-libs/deepl-ruby']
105
+ script:
106
+ - >
107
+ if [[ ! -z "${USE_MOCK_SERVER}" ]]; then
108
+ echo "Using mock server"
109
+ export DEEPL_SERVER_URL=http://deepl-mock:3000
110
+ export DEEPL_MOCK_SERVER_PORT=3000
111
+ export DEEPL_PROXY_URL=http://deepl-mock:3001
112
+ export DEEPL_MOCK_PROXY_SERVER_PORT=3001
113
+ fi
114
+ - bundle exec rake test
115
+ - bundle exec rspec --format RspecJunitFormatter --out rspec.xml
116
+ artifacts:
117
+ reports:
118
+ coverage_report:
119
+ coverage_format: cobertura
120
+ path: coverage/coverage.xml
121
+ junit:
122
+ - rspec.xml
123
+ when: always
124
+
125
+ test_scheduled:
126
+ extends: .test_base
127
+ rules:
128
+ - if: $CI_PIPELINE_SOURCE == "schedule"
129
+ retry: 2
130
+
131
+ test_manual:
132
+ stage: test
133
+ extends: .test_base
134
+ rules:
135
+ - if: $CI_PIPELINE_SOURCE != "schedule"
data/.rubocop.yml CHANGED
@@ -1,11 +1,15 @@
1
1
  # Custom rubocop configuration
2
2
 
3
+ require:
4
+ - rubocop-rspec
5
+
3
6
  AllCops:
4
7
  DisplayCopNames: true
5
8
  NewCops: enable
6
9
  Exclude:
7
10
  - deepl-rb.gemspec
8
11
  - vendor/**/*
12
+ TargetRubyVersion: 2.7.5
9
13
 
10
14
  Metrics/BlockLength:
11
15
  Exclude:
@@ -17,6 +21,29 @@ Metrics/ParameterLists:
17
21
  Layout/LineLength:
18
22
  Max: 100
19
23
 
24
+ RSpec/ExampleLength:
25
+ Max: 10
26
+ CountAsOne: ['heredoc']
27
+
28
+ RSpec/MessageSpies:
29
+ EnforcedStyle: 'receive'
30
+
31
+ RSpec/MultipleExpectations:
32
+ Max: 8
33
+
34
+ RSpec/MultipleMemoizedHelpers:
35
+ Max: 7
36
+
37
+ RSpec/NestedGroups:
38
+ Max: 4
39
+
40
+ RSpec/SpecFilePathSuffix:
41
+ Enabled: false
42
+
43
+ RSpec/SpecFilePathFormat:
44
+ CustomTransform:
45
+ DeepL: ''
46
+
20
47
  Style/Documentation:
21
48
  Enabled: false
22
49
 
data/CHANGELOG.md ADDED
@@ -0,0 +1,34 @@
1
+ # Changelog
2
+ All notable changes to this project will be documented in this file.
3
+
4
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
5
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+
8
+ ## [Unreleased]
9
+ Beginning with version 3, deepl-rb is officially supported by DeepL, and maintained together with [Daniel Herzog](mailto:info@danielherzog.es) the developer of earlier versions of this library.
10
+ The change in major version is only due to the change in maintainership, there is no migration necessary from v2 to v3.
11
+ ### Added
12
+ * Added rubocop-rspec linting for rspec test files
13
+ * Added document translation to the ruby CL
14
+ * Added possibility to use one HTTP session for multiple calls
15
+ * Added platform and ruby version information to the user-agent string that is sent with API calls, along with an opt-out
16
+ * Added support for logging of HTTP requests
17
+ * Added support for using a proxy and a custom certificate file
18
+ * Added a gitlab CI pipeline
19
+ ### Changed
20
+ * HTTP requests to the DeepL API now use `application/json`, rather than `application/www-form-unencoded`
21
+ * HTTP requests now automatically retry on transient failures, using exponential backoff
22
+ ### Deprecated
23
+ ### Removed
24
+ * Removed CircleCI and CodeCov upload
25
+ ### Fixed
26
+ ### Security
27
+
28
+ ## [2.5.3] - 2022-09-26
29
+ ### Fixed
30
+ * Make RequestEntityTooLarge error message more clear
31
+
32
+
33
+ [Unreleased]: https://github.com/DeepLcom/deepl-rb/compare/v2.5.3...HEAD
34
+ [2.5.3]: https://github.com/DeepLcom/deepl-rb/compare/v2.5.2...v2.5.3
@@ -0,0 +1,132 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ We as members, contributors, and leaders pledge to make participation in our
6
+ community a harassment-free experience for everyone, regardless of age, body
7
+ size, visible or invisible disability, ethnicity, sex characteristics, gender
8
+ identity and expression, level of experience, education, socio-economic status,
9
+ nationality, personal appearance, race, caste, color, religion, or sexual
10
+ identity and orientation.
11
+
12
+ We pledge to act and interact in ways that contribute to an open, welcoming,
13
+ diverse, inclusive, and healthy community.
14
+
15
+ ## Our Standards
16
+
17
+ Examples of behavior that contributes to a positive environment for our
18
+ community include:
19
+
20
+ * Demonstrating empathy and kindness toward other people
21
+ * Being respectful of differing opinions, viewpoints, and experiences
22
+ * Giving and gracefully accepting constructive feedback
23
+ * Accepting responsibility and apologizing to those affected by our mistakes,
24
+ and learning from the experience
25
+ * Focusing on what is best not just for us as individuals, but for the overall
26
+ community
27
+
28
+ Examples of unacceptable behavior include:
29
+
30
+ * The use of sexualized language or imagery, and sexual attention or advances of
31
+ any kind
32
+ * Trolling, insulting or derogatory comments, and personal or political attacks
33
+ * Public or private harassment
34
+ * Publishing others' private information, such as a physical or email address,
35
+ without their explicit permission
36
+ * Other conduct which could reasonably be considered inappropriate in a
37
+ professional setting
38
+
39
+ ## Enforcement Responsibilities
40
+
41
+ Community leaders are responsible for clarifying and enforcing our standards of
42
+ acceptable behavior and will take appropriate and fair corrective action in
43
+ response to any behavior that they deem inappropriate, threatening, offensive,
44
+ or harmful.
45
+
46
+ Community leaders have the right and responsibility to remove, edit, or reject
47
+ comments, commits, code, wiki edits, issues, and other contributions that are
48
+ not aligned to this Code of Conduct, and will communicate reasons for moderation
49
+ decisions when appropriate.
50
+
51
+ ## Scope
52
+
53
+ This Code of Conduct applies within all community spaces, and also applies when
54
+ an individual is officially representing the community in public spaces.
55
+ Examples of representing our community include using an official e-mail address,
56
+ posting via an official social media account, or acting as an appointed
57
+ representative at an online or offline event.
58
+
59
+ ## Enforcement
60
+
61
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
62
+ reported to the community leaders responsible for enforcement at
63
+ [open-source@deepl.com](mailto:open-source@deepl.com).
64
+ All complaints will be reviewed and investigated promptly and fairly.
65
+
66
+ All community leaders are obligated to respect the privacy and security of the
67
+ reporter of any incident.
68
+
69
+ ## Enforcement Guidelines
70
+
71
+ Community leaders will follow these Community Impact Guidelines in determining
72
+ the consequences for any action they deem in violation of this Code of Conduct:
73
+
74
+ ### 1. Correction
75
+
76
+ **Community Impact**: Use of inappropriate language or other behavior deemed
77
+ unprofessional or unwelcome in the community.
78
+
79
+ **Consequence**: A private, written warning from community leaders, providing
80
+ clarity around the nature of the violation and an explanation of why the
81
+ behavior was inappropriate. A public apology may be requested.
82
+
83
+ ### 2. Warning
84
+
85
+ **Community Impact**: A violation through a single incident or series of
86
+ actions.
87
+
88
+ **Consequence**: A warning with consequences for continued behavior. No
89
+ interaction with the people involved, including unsolicited interaction with
90
+ those enforcing the Code of Conduct, for a specified period of time. This
91
+ includes avoiding interactions in community spaces as well as external channels
92
+ like social media. Violating these terms may lead to a temporary or permanent
93
+ ban.
94
+
95
+ ### 3. Temporary Ban
96
+
97
+ **Community Impact**: A serious violation of community standards, including
98
+ sustained inappropriate behavior.
99
+
100
+ **Consequence**: A temporary ban from any sort of interaction or public
101
+ communication with the community for a specified period of time. No public or
102
+ private interaction with the people involved, including unsolicited interaction
103
+ with those enforcing the Code of Conduct, is allowed during this period.
104
+ Violating these terms may lead to a permanent ban.
105
+
106
+ ### 4. Permanent Ban
107
+
108
+ **Community Impact**: Demonstrating a pattern of violation of community
109
+ standards, including sustained inappropriate behavior, harassment of an
110
+ individual, or aggression toward or disparagement of classes of individuals.
111
+
112
+ **Consequence**: A permanent ban from any sort of public interaction within the
113
+ community.
114
+
115
+ ## Attribution
116
+
117
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118
+ version 2.1, available at
119
+ [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120
+
121
+ Community Impact Guidelines were inspired by
122
+ [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123
+
124
+ For answers to common questions about this code of conduct, see the FAQ at
125
+ [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126
+ [https://www.contributor-covenant.org/translations][translations].
127
+
128
+ [homepage]: https://www.contributor-covenant.org
129
+ [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
130
+ [Mozilla CoC]: https://github.com/mozilla/diversity
131
+ [FAQ]: https://www.contributor-covenant.org/faq
132
+ [translations]: https://www.contributor-covenant.org/translations
data/CONTRIBUTING.md ADDED
@@ -0,0 +1,37 @@
1
+ # Contributing guidelines
2
+
3
+ * [Code of Conduct](#code-of-conduct)
4
+ * [Issues](#issues)
5
+ * [Pull Requests](#pull-requests)
6
+
7
+ ## Code of Conduct
8
+
9
+ This project has a [Code of Conduct](CODE_OF_CONDUCT.md) to which all
10
+ contributors must adhere when participating in the project. Instances of
11
+ abusive, harassing, or otherwise unacceptable behavior may be reported by
12
+ contacting [open-source@deepl.com](mailto:open-source@deepl.com) and/or a
13
+ project maintainer.
14
+
15
+ ## Issues
16
+
17
+ If you experience problems using the library, or would like to request a new
18
+ feature, please open an [issue][issues].
19
+
20
+ Please provide as much context as possible when you open an issue. The
21
+ information you provide must be comprehensive enough for us to reproduce the
22
+ issue.
23
+
24
+ ## Pull Requests
25
+
26
+ You are welcome to contribute code and/or documentation in order to fix a bug or
27
+ to implement a new feature. Before beginning work, you should create an issue
28
+ describing the changes you plan to contribute, to avoid wasting or duplicating
29
+ effort. We will then let you know whether we would accept the changes.
30
+
31
+ Contributions must be licensed under the same license as the project:
32
+ [MIT License](LICENSE.md).
33
+
34
+ Currently automated testing is implemented internally at DeepL, however we plan
35
+ to implement publicly visible testing soon.
36
+
37
+ [issues]: https://www.github.com/DeepLcom/deepl-rb/issues
data/Gemfile CHANGED
@@ -13,10 +13,12 @@ end
13
13
 
14
14
  group :test do
15
15
  # Test
16
- gem 'codecov', require: false
17
16
  gem 'rspec'
17
+ gem 'rspec_junit_formatter'
18
18
  gem 'rubocop'
19
+ gem 'rubocop-rspec'
19
20
  gem 'simplecov'
21
+ gem 'simplecov-cobertura'
20
22
  gem 'vcr'
21
23
  gem 'webmock'
22
24
  end
data/LICENSE.md CHANGED
@@ -2,6 +2,7 @@ The MIT License (MIT)
2
2
  =====================
3
3
 
4
4
  Copyright © `2018` `Daniel Herzog`
5
+ Copyright © `2024` `DeepL SE (https://www.deepl.com)`
5
6
 
6
7
  Permission is hereby granted, free of charge, to any person
7
8
  obtaining a copy of this software and associated documentation
data/README.md CHANGED
@@ -1,8 +1,14 @@
1
- [![Gem Version](https://badge.fury.io/rb/deepl-rb.svg)](https://badge.fury.io/rb/deepl-rb) [![CircleCI](https://circleci.com/gh/wikiti/deepl-rb.svg?style=shield)](https://circleci.com/gh/wikiti/deepl-rb) [![CodeCov](https://codecov.io/gh/wikiti/deepl-rb/branch/master/graph/badge.svg?token=SHLgQNlZ4o)](https://codecov.io/gh/wikiti/deepl-rb)
1
+ [![Gem Version](https://badge.fury.io/rb/deepl-rb.svg)](https://badge.fury.io/rb/deepl-rb)
2
2
 
3
- # DeepL for ruby
3
+ # DeepL Ruby Library
4
4
 
5
- A simple ruby wrapper for the [DeepL translation API (v2)](https://www.deepl.com/api.html).
5
+ The [DeepL API](https://developers.deepl.com/docs/api-reference/translate) is a language translation API that allows other computer programs to send texts and documents to DeepL's servers and receive high-quality translations. This opens a whole universe of opportunities for developers: any translation product you can imagine can now be built on top of DeepL's best-in-class translation technology.
6
+
7
+ The DeepL Ruby library offers a convenient way for applications written in Ruby to interact with the DeepL API. We intend to support all API functions with the library, though support for new features may be added to the library after they’re added to the API.
8
+
9
+ ## Getting an authentication key
10
+
11
+ To use the DeepL Ruby Library, you'll need an API authentication key. To get a key, [please create an account here](https://www.deepl.com/pro?utm_source=github&utm_medium=github-ruby-readme#developer). With a DeepL API Free account you can translate up to 500,000 characters/month for free.
6
12
 
7
13
  ## Installation
8
14
 
@@ -71,7 +77,7 @@ puts DeepL.languages(type: :target).count
71
77
  ```
72
78
 
73
79
  All languages are also defined on the
74
- [official API documentation](https://www.deepl.com/docs-api/translating-text/).
80
+ [official API documentation](https://developers.deepl.com/docs/api-reference/translate).
75
81
 
76
82
  Note that target languages may include the `supports_formality` flag, which may be checked
77
83
  using the `DeepL::Resources::Language#supports_formality?`.
@@ -241,6 +247,22 @@ puts usage.character_limit
241
247
  # => 1250000
242
248
  ```
243
249
 
250
+ ### Translate documents
251
+
252
+ To translate a document, use the `document.translate_document` method. Example:
253
+
254
+ ```rb
255
+ DeepL.document.translate_document('/path/to/spanish_document.pdf', 'ES', 'EN', '/path/to/translated_document.pdf')
256
+ ```
257
+
258
+ The lower level `upload`, `get_status` and `download` methods are also exposed, as well as the convenience method `wait_until_document_translation_finished` on the `DocumentHandle` object, which would replace `get_status`:
259
+ ```rb
260
+ doc_handle = DeepL.document.upload('/path/to/spanish_document.pdf', 'ES', 'EN')
261
+ doc_status = doc_handle.wait_until_document_translation_finished # alternatively poll `DeepL.document.get_status`
262
+ # until the `doc_status.successful?`
263
+ DeepL.document.download(doc_handle, '/path/to/translated_document.pdf') unless doc_status.error?
264
+ ```
265
+
244
266
  ### Handle exceptions
245
267
 
246
268
  You can capture and process exceptions that may be raised during API calls. These are all the possible exceptions:
@@ -249,10 +271,13 @@ You can capture and process exceptions that may be raised during API calls. Thes
249
271
  | --------------- | ----------- |
250
272
  | `DeepL::Exceptions::AuthorizationFailed` | The authorization process has failed. Check your `auth_key` value. |
251
273
  | `DeepL::Exceptions::BadRequest` | Something is wrong in your request. Check `exception.message` for more information. |
274
+ | `DeepL::Exceptions::DocumentTranslationError` | An error occured during document translation. Check `exception.message` for more information. |
252
275
  | `DeepL::Exceptions::LimitExceeded` | You've reached the API's call limit. |
253
276
  | `DeepL::Exceptions::QuotaExceeded` | You've reached the API's character limit. |
254
277
  | `DeepL::Exceptions::RequestError` | An unkown request error. Check `exception.response` and `exception.request` for more information. |
255
278
  | `DeepL::Exceptions::NotSupported` | The requested method or API endpoint is not supported. |
279
+ | `DeepL::Exceptions::RequestEntityTooLarge` | Your request is too large, reduce the amount of data you are sending. The API has a request size limit of 128 KiB. |
280
+ | `DeepL::Exceptions::ServerError` | An error occured in the DeepL API, wait a short amount of time and retry. |
256
281
 
257
282
  An exampling of handling a generic exception:
258
283
 
@@ -267,6 +292,75 @@ rescue DeepL::Exceptions::RequestError => e
267
292
  end
268
293
  ```
269
294
 
295
+ ### Logging
296
+
297
+ To enable logging, pass a suitable logging object (e.g. the default `Logger` from the Ruby standard library) when configuring the library. The library logs HTTP requests to `INFO` and debug information to `DEBUG`. Example:
298
+
299
+ ```rb
300
+ require 'logger'
301
+
302
+ logger = Logger.new(STDOUT)
303
+ logger.level = Logger::INFO
304
+
305
+ deepl.configure do |config|
306
+ config.auth_key = configuration.auth_key
307
+ config.logger = logger
308
+ end
309
+ ```
310
+
311
+ ### Proxy configuration
312
+
313
+ To use HTTP proxies, a session needs to be used. The proxy can then be configured as part of the HTTP client options:
314
+
315
+ ```rb
316
+ client_options = HTTPClientOptions.new({ 'proxy_addr' => 'http://localhost', 'proxy_port' => 80 })
317
+ deepl.with_session(client_options) do |session|
318
+ # ...
319
+ end
320
+ ```
321
+
322
+ ### Anonymous platform information
323
+
324
+ By default, we send some basic information about the platform the client library is running on with each request, see [here for an explanation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). This data is completely anonymous and only used to improve our product, not track any individual users. If you do not wish to send this data, you can opt-out by setting the `send_platform_info` flag in the configuration to `false` like so:
325
+
326
+ ```rb
327
+ deepl.configure({}, nil, nil, false) do |config|
328
+ # ...
329
+ end
330
+ ```
331
+
332
+ You can also complete customize the `User-Agent` header like so:
333
+
334
+ ```rb
335
+ deepl.configure do |config|
336
+ config.user_agent = 'myCustomUserAgent'
337
+ end
338
+ ```
339
+
340
+ ### Sending multiple requests
341
+
342
+ When writing an application that send multiple requests, using a HTTP session will give better performance through [HTTP Keep-Alive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive). You can use it by simply wrapping your requests in a `with_session` block:
343
+
344
+ ```rb
345
+ deepl.with_session do |session|
346
+ deepl.translate(sentence1, 'DE', 'EN-GB')
347
+ deepl.translate(sentence2, 'DE', 'EN-GB')
348
+ deepl.translate(sentence3, 'DE', 'EN-GB')
349
+ end
350
+ ```
351
+
352
+ ### Writing a plugin
353
+
354
+ If you use this library in an application, please identify the application by setting the name and version of the plugin:
355
+
356
+ ```rb
357
+ deepl.configure({}, 'MyTranslationPlugin', '1.0.1') do |config|
358
+ # ...
359
+ end
360
+ ```
361
+
362
+ This information is passed along when the library makes calls to the DeepL API. Both name and version are required. Please note that setting the `User-Agent` header via `deepl.configure` will override this setting, if you need to use this, please manually identify your Application in the `User-Agent` header.
363
+
270
364
  ## Integrations
271
365
 
272
366
  ### Ruby on Rails
@@ -295,7 +389,7 @@ backend services to translate content.
295
389
  Clone the repository, and install its dependencies:
296
390
 
297
391
  ```sh
298
- git clone https://github.com/wikiti/deepl-rb
392
+ git clone https://github.com/DeepLcom/deepl-rb
299
393
  cd deepl-rb
300
394
  bundle install
301
395
  ```
@@ -305,3 +399,19 @@ To run tests (rspec and rubocop), use
305
399
  ```
306
400
  bundle exec rake test
307
401
  ```
402
+
403
+ ### Caution: Changing VCR Tests
404
+
405
+ If you need to rerecord some of the VCR tests, simply setting `record: :new_episodes` and rerunning `rspec` won't be enough in some cases, specifically around document translation (due to its statefulness) and glossaries (since a glossary ID is associated with a specific API account).
406
+ For example, there are document translations tests that split up the `upload`, `get_status` and `download` calls into separate test cases. You need to first rerecord the `upload` call, you can do execute a single test like this (the line should be where the `it` block of the test starts):
407
+
408
+ ```sh
409
+ rspec ./spec/api/deepl_spec.rb:152
410
+ ```
411
+
412
+ This will return a `document_id` and a `document_key`, you will need to update the values in the `get_status` and `download` tests accordingly. You can find examples for this in the git history.
413
+ Similarly, for the glossary tests you will need to delete the recorded HTTP requests for certain glossary IDs so that `rspec` will create the glossaries on your account instead. Feel free to reach out on our discord if you run into any trouble here.
414
+
415
+ ## Acknowledgements
416
+
417
+ This library was originally developed by [Daniel Herzog](mailto:info@danielherzog.es), we are grateful for his contributions. Beginning with v3.0.0, DeepL took over development and officially supports and maintains the library together with Daniel.
data/Rakefile CHANGED
@@ -16,15 +16,17 @@ require 'juwelier'
16
16
 
17
17
  Juwelier::Tasks.new do |gem|
18
18
  gem.name = 'deepl-rb'
19
- gem.homepage = 'http://github.com/wikiti/deepl-rb'
19
+ gem.homepage = 'https://github.com/DeepLcom/deepl-rb'
20
20
  gem.license = 'MIT'
21
- gem.summary = 'A simple ruby wrapper for the DeepL API'
21
+ gem.summary = 'Official Ruby library for the DeepL language translation API.'
22
22
  gem.description =
23
- 'A simple ruby wrapper for the DeepL translation API (v1). ' \
23
+ 'Official Ruby library for the DeepL language translation API (v2). ' \
24
24
  'For more information, check this: https://www.deepl.com/docs/api-reference.html'
25
25
 
26
- gem.email = 'info@danielherzog.es'
27
- gem.authors = ['Daniel Herzog']
26
+ gem.email = 'open-source@deepl.com'
27
+ gem.authors = ['DeepL SE']
28
+ gem.files.exclude '.github'
29
+ gem.files.exclude '.circleci'
28
30
  end
29
31
 
30
32
  Juwelier::RubygemsDotOrgTasks.new