Skip to content

Commit ec5928d

Browse files
daniel-jones-devdaniel-jones-dev
authored
Merge pull request #9 from DeepLcom/reunify
Reunify the simplified-edits branch with main
2 parents c2afaff + dd13d38 commit ec5928d

File tree

8 files changed

+2023
-15
lines changed

8 files changed

+2023
-15
lines changed

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,14 @@ number is used only for corrections to the OpenAPI specification, for example:
1010
typos, schema fixes, or adding examples.
1111

1212

13+
## [2.12.0] - 2024-02-29
14+
### Added
15+
* Add supported glossary language: Korean (KO).
16+
* Add supported language for text translation: Arabic (AR). Arabic is
17+
currently supported only for text translation; document translation
18+
support for Arabic is coming soon.
19+
20+
1321
## [2.11.0] - 2023-08-03
1422
### Added
1523
* Add supported glossary languages: Portuguese (PT), Russian (RU), and Chinese (ZH).
@@ -109,6 +117,7 @@ typos, schema fixes, or adding examples.
109117
Initial release of the OpenAPI specification.
110118

111119

120+
[2.12.0]: https://github.com/DeepLcom/openapi/compare/v2.11.0...v2.12.0
112121
[2.11.0]: https://github.com/DeepLcom/openapi/compare/v2.10.0...v2.11.0
113122
[2.10.0]: https://github.com/DeepLcom/openapi/compare/v2.9.2...v2.10.0
114123
[2.9.2]: https://github.com/DeepLcom/openapi/compare/v2.9.1...v2.9.2

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
This project contains an [OpenAPI specification][openapi-specification] of the
44
[DeepL API][deepl-api], in [YAML](openapi.yaml) and [JSON](openapi.json)
55
formats.
6+
There is also a [simplified YAML](openapi_gitbook.yaml) with reduced descriptions that is embedded in our [API documentation][deepl-api-docs].
67

78
You can use this specification to explore the API in tools like
89
[Postman][postman], or to auto-generate documentation, SDKs, and code libraries
@@ -19,6 +20,8 @@ requests, please [create an issue][issues].
1920

2021
[deepl-api]: https://www.deepl.com/pro-api
2122

23+
[deepl-api-docs]: https://developers.deepl.com/docs
24+
2225
[issues]: https://github.com/DeepLcom/openapi/issues
2326

2427
[openapi-specification]: https://openapis.org/

‎openapi.json‎

Lines changed: 99 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"name": "DeepL - Contact us",
99
"url": "https://www.deepl.com/contact-us"
1010
},
11-
"version": "2.11.0"
11+
"version": "2.12.0"
1212
},
1313
"externalDocs": {
1414
"description": "DeepL Pro - Plans and pricing",
@@ -35,7 +35,7 @@
3535
},
3636
{
3737
"name": "ManageGlossaries",
38-
"description": "The *glossary* functions allow you to create, inspect, and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter.\nIf you encounter issues, please let us know at [email protected].\n\nThe DeepL API supports glossaries in any combination of two languages from the following list, enabling a total of\n55 possible glossary language pairs:\n\n- DE (German)\n- EN (English)\n- ES (Spanish)\n- FR (French)\n- IT (Italian)\n- JA (Japanese)\n- NL (Dutch)\n- PL (Polish)\n- PT (Portuguese)\n- RU (Russian)\n- ZH (Chinese)\n\nThe maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,\nas well as the name of the glossary, is limited to 1024 UTF-8 bytes.\nA total of 1000 glossaries are allowed per account.\n\nWhen creating a glossary with target language `EN` or `PT`, it's not necessary to specify a variant (e.g. `EN-US`, `EN-GB`, `PT-PT` or `PT-BR`).\nGlossaries with target language `EN` can be used in translations with either English variant.\nSimilarly `PT` glossaries can be used in translations with either Portuguese variant.\n\n\nGlossaries created via the DeepL API are distinct from glossaries created via the DeepL website and DeepL apps.\nThis means API glossaries cannot be used on the website and vice versa.\n\n\n\nNote that glossaries are immutable: once created, the glossary entries for a given glossary ID cannot be modified.\n\nAs a workaround for effectively editable glossaries, we suggest to identify glossaries by name instead of ID in your application\nand then use the following procedure for modifications:\n- [download](https://www.deepl.com/docs-api/glossaries/get-glossary-entries) and store the current glossary's entries,\n- locally modify the glossary entries,\n- [delete](https://www.deepl.com/docs-api/glossaries/delete-glossary) the existing glossary,\n- [create a new glossary](https://www.deepl.com/docs-api/glossaries/create-glossary) with the same name."
38+
"description": "The *glossary* functions allow you to create, inspect, and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter.\nIf you encounter issues, please let us know at [email protected].\n\nThe DeepL API supports glossaries in any combination of two languages from the following list, enabling a total of\n66 possible glossary language pairs:\n\n- DE (German)\n- EN (English)\n- ES (Spanish)\n- FR (French)\n- IT (Italian)\n- JA (Japanese)\n- KO (Korean)\n- NL (Dutch)\n- PL (Polish)\n- PT (Portuguese)\n- RU (Russian)\n- ZH (Chinese)\n\nThe maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,\nas well as the name of the glossary, is limited to 1024 UTF-8 bytes.\nA total of 1000 glossaries are allowed per account.\n\nWhen creating a glossary with target language `EN` or `PT`, it's not necessary to specify a variant (e.g. `EN-US`, `EN-GB`, `PT-PT` or `PT-BR`).\nGlossaries with target language `EN` can be used in translations with either English variant.\nSimilarly `PT` glossaries can be used in translations with either Portuguese variant.\n\n\nGlossaries created via the DeepL API are distinct from glossaries created via the DeepL website and DeepL apps.\nThis means API glossaries cannot be used on the website and vice versa.\n\n\n\nNote that glossaries are immutable: once created, the glossary entries for a given glossary ID cannot be modified.\n\nAs a workaround for effectively editable glossaries, we suggest to identify glossaries by name instead of ID in your application\nand then use the following procedure for modifications:\n- [download](https://www.deepl.com/docs-api/glossaries/get-glossary-entries) and store the current glossary's entries,\n- locally modify the glossary entries,\n- [delete](https://www.deepl.com/docs-api/glossaries/delete-glossary) the existing glossary,\n- [create a new glossary](https://www.deepl.com/docs-api/glossaries/create-glossary) with the same name."
3939
},
4040
{
4141
"name": "MetaInformation",
@@ -72,10 +72,13 @@
7272
}
7373
},
7474
"source_lang": {
75-
"$ref": "#/components/schemas/SourceLanguage"
75+
"$ref": "#/components/schemas/SourceLanguageText"
7676
},
7777
"target_lang": {
78-
"$ref": "#/components/schemas/TargetLanguage"
78+
"$ref": "#/components/schemas/TargetLanguageText"
79+
},
80+
"context": {
81+
"$ref": "#/components/schemas/Context"
7982
},
8083
"split_sentences": {
8184
"$ref": "#/components/schemas/SplitSentencesOption"
@@ -173,10 +176,13 @@
173176
}
174177
},
175178
"source_lang": {
176-
"$ref": "#/components/schemas/SourceLanguage"
179+
"$ref": "#/components/schemas/SourceLanguageText"
177180
},
178181
"target_lang": {
179-
"$ref": "#/components/schemas/TargetLanguage"
182+
"$ref": "#/components/schemas/TargetLanguageText"
183+
},
184+
"context": {
185+
"$ref": "#/components/schemas/Context"
180186
},
181187
"split_sentences": {
182188
"$ref": "#/components/schemas/SplitSentencesOption"
@@ -394,6 +400,10 @@
394400
"type": "string",
395401
"description": "The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition."
396402
},
403+
"output_format": {
404+
"type": "string",
405+
"description": "File extension of desired format of translated file, for example: `docx`. If unspecified, by default the translated file will be in the same format as the input file.\n\nNote: Not all combinations of input file and translation file extensions are permitted. See [Document Format Conversions](https://www.deepl.com/docs-api/documents/format-conversions) for the permitted combinations."
406+
},
397407
"formality": {
398408
"$ref": "#/components/schemas/Formality"
399409
},
@@ -1274,7 +1284,7 @@
12741284
"MetaInformation"
12751285
],
12761286
"summary": "Retrieve Supported Languages",
1277-
"description": "Retrieve the list of languages that are currently supported for translation, either as source or target language, respectively.",
1287+
"description": "Retrieve the list of languages that are currently supported for translation, either as source or target language, respectively.\n\nAs of January 2024, Arabic (AR) is supported as a source and target language for text translation, \nbut it is not yet supported for document translation. Therefore, Arabic has not yet been added to \nthe `/languages` endpoint. We will add Arabic to the `/languages` endpoint after document translation \nsupport is added.",
12781288
"operationId": "getLanguages",
12791289
"parameters": [
12801290
{
@@ -1669,6 +1679,10 @@
16691679
}
16701680
},
16711681
"schemas": {
1682+
"Context": {
1683+
"description": "The `context` parameter makes it possible to include additional context that can influence a translation but is not translated itself. \nThis additional context can potentially improve translation quality when translating short, low-context source texts such \nas product names on an e-commerce website, article headlines on a news website, or UI elements.\n\n\nFor example...\n - When translating a product name, you might pass the product description as context. \n - When translating a news article headline, you might pass the first few sentences or a summary of the article as context.\n\n\nFor best results, we recommend sending a few complete sentences of context. There is no size limit for the `context` parameter itself, but \nthe request body size limit of 128 KiB still applies to all text translation requests. \n\n\nIf you send a request with multiple `text` parameters, the `context` parameter will be applied to each one. \n\n\nThe `context` parameter is an **alpha feature** as defined in section 3.1.5 of our [terms and conditions](https://www.deepl.com/en/pro-license). \nThis means it could be changed or deprecated by DeepL at any point and without advance notice. While the feature is still labeled as \"alpha\", \ncontext will not be counted toward billing (i.e. there is no additional cost for sending context). This is subject to change if the \"alpha\" \nlabel is removed and the feature becomes generally available. If we decide to deprecate the `context` parameter, requests that include it will not \nbreak; the context will simply be ignored. \n\n\nFor these reasons, **the `context` parameter is not intended to be used in production** as long as the alpha label still applies.\n\n\nWe're eager to hear how the `context` parameter is working for you and how we can improve the feature! You can share your feedback \nby emailing [email protected].",
1684+
"type": "string"
1685+
},
16721686
"CreateGlossaryParameters": {
16731687
"type": "object",
16741688
"required": [
@@ -1796,6 +1810,7 @@
17961810
"fr",
17971811
"it",
17981812
"ja",
1813+
"ko",
17991814
"nl",
18001815
"pl",
18011816
"pt",
@@ -1814,6 +1829,7 @@
18141829
"fr",
18151830
"it",
18161831
"ja",
1832+
"ko",
18171833
"nl",
18181834
"pl",
18191835
"pt",
@@ -1894,6 +1910,43 @@
18941910
],
18951911
"example": "EN"
18961912
},
1913+
"SourceLanguageText": {
1914+
"type": "string",
1915+
"description": "Language of the text to be translated. Options currently available:\n * `AR` - Arabic [1]\n * `BG` - Bulgarian\n * `CS` - Czech\n * `DA` - Danish\n * `DE` - German\n * `EL` - Greek\n * `EN` - English\n * `ES` - Spanish\n * `ET` - Estonian\n * `FI` - Finnish\n * `FR` - French\n * `HU` - Hungarian\n * `ID` - Indonesian\n * `IT` - Italian\n * `JA` - Japanese\n * `KO` - Korean\n * `LT` - Lithuanian\n * `LV` - Latvian\n * `NB` - Norwegian (Bokm\u00e5l)\n * `NL` - Dutch\n * `PL` - Polish\n * `PT` - Portuguese (all Portuguese varieties mixed)\n * `RO` - Romanian\n * `RU` - Russian\n * `SK` - Slovak\n * `SL` - Slovenian\n * `SV` - Swedish\n * `TR` - Turkish\n * `UK` - Ukrainian\n * `ZH` - Chinese\n\nIf this parameter is omitted, the API will attempt to detect the language of the text and translate it.\n\n[1] Please note that Arabic has not yet been added to the `/languages` endpoint because it does not \nyet support document translation; only text translation is supported for Arabic at this time. When \ndocument translation support is added for Arabic, we will a) remove this note and b) add Arabic to \nthe `/languages` endpoint.",
1916+
"enum": [
1917+
"AR",
1918+
"BG",
1919+
"CS",
1920+
"DA",
1921+
"DE",
1922+
"EL",
1923+
"EN",
1924+
"ES",
1925+
"ET",
1926+
"FI",
1927+
"FR",
1928+
"HU",
1929+
"ID",
1930+
"IT",
1931+
"JA",
1932+
"KO",
1933+
"LT",
1934+
"LV",
1935+
"NB",
1936+
"NL",
1937+
"PL",
1938+
"PT",
1939+
"RO",
1940+
"RU",
1941+
"SK",
1942+
"SL",
1943+
"SV",
1944+
"TR",
1945+
"UK",
1946+
"ZH"
1947+
],
1948+
"example": "EN"
1949+
},
18971950
"TagHandlingOption": {
18981951
"description": "Sets which kind of tags should be handled. Options currently available:\n * `xml`: Enable XML tag handling; see [XML Handling](https://www.deepl.com/docs-api/xml).\n * `html`: Enable HTML tag handling; see [HTML Handling](https://www.deepl.com/docs-api/html).",
18991952
"type": "string",
@@ -2004,6 +2057,45 @@
20042057
"ZH"
20052058
],
20062059
"example": "DE"
2060+
},
2061+
"TargetLanguageText": {
2062+
"type": "string",
2063+
"description": "The language into which the text should be translated. Options currently available:\n * `AR` - Arabic [1]\n * `BG` - Bulgarian\n * `CS` - Czech\n * `DA` - Danish\n * `DE` - German\n * `EL` - Greek\n * `EN` - English (unspecified variant for backward compatibility; please select `EN-GB` or `EN-US` instead)\n * `EN-GB` - English (British)\n * `EN-US` - English (American)\n * `ES` - Spanish\n * `ET` - Estonian\n * `FI` - Finnish\n * `FR` - French\n * `HU` - Hungarian\n * `ID` - Indonesian\n * `IT` - Italian\n * `JA` - Japanese\n * `KO` - Korean\n * `LT` - Lithuanian\n * `LV` - Latvian\n * `NB` - Norwegian (Bokm\u00e5l)\n * `NL` - Dutch\n * `PL` - Polish\n * `PT` - Portuguese (unspecified variant for backward compatibility; please select `PT-BR` or `PT-PT` instead)\n * `PT-BR` - Portuguese (Brazilian)\n * `PT-PT` - Portuguese (all Portuguese varieties excluding Brazilian Portuguese)\n * `RO` - Romanian\n * `RU` - Russian\n * `SK` - Slovak\n * `SL` - Slovenian\n * `SV` - Swedish\n * `TR` - Turkish\n * `UK` - Ukrainian\n * `ZH` - Chinese (simplified)\n\n [1] Please note that Arabic has not yet been added to the `/languages` endpoint because \n it does not yet support document translation; only text translation is supported for Arabic \n at this time. When document translation support is added for Arabic, we will a) remove this \n note and b) add Arabic to the `/languages` endpoint.",
2064+
"enum": [
2065+
"AR",
2066+
"BG",
2067+
"CS",
2068+
"DA",
2069+
"DE",
2070+
"EL",
2071+
"EN-GB",
2072+
"EN-US",
2073+
"ES",
2074+
"ET",
2075+
"FI",
2076+
"FR",
2077+
"HU",
2078+
"ID",
2079+
"IT",
2080+
"JA",
2081+
"KO",
2082+
"LT",
2083+
"LV",
2084+
"NB",
2085+
"NL",
2086+
"PL",
2087+
"PT-BR",
2088+
"PT-PT",
2089+
"RO",
2090+
"RU",
2091+
"SK",
2092+
"SL",
2093+
"SV",
2094+
"TR",
2095+
"UK",
2096+
"ZH"
2097+
],
2098+
"example": "DE"
20072099
}
20082100
}
20092101
}

0 commit comments

Comments
 (0)