Skip to content

docs: add the customizations object to POST /v2/translate #438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lawl-dev wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add the customizations object to POST /v2/translate #438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions api-reference/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -838,6 +838,67 @@
"example": "Use a friendly, diplomatic tone"
}
},
"customizations": {
"description": "All customizations of the request in one object: glossaries, a style rule list, custom\ninstructions, a translation memory and example documents. For new integrations we recommend\nthis object over the individual customization parameters. Each field behaves like the\nparameter it corresponds to.\n\nCannot be used together with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`,\n`translation_memory_threshold` or `custom_instructions`. A request that combines them is rejected\nwith `400 Bad Request` naming the conflicting parameter. Accepted in JSON request bodies only.\n\nAvailable for accounts that have it enabled. Contact your DeepL representative to request access.",
"type": "object",
"properties": {
"glossary_ids": {
"description": "Up to 5 glossaries to use for the translation, in the order they should be applied. Corresponds to\n`glossary_ids`: requires `source_lang`, and every listed glossary must contain a dictionary for the\nrequested language pair.",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
}
},
"style_rule_id": {
"description": "The [style rule list](/docs/customize/using-style-rules) to use for the translation. Corresponds to\n`style_id`: the target language has to match the language of the style rule list.",
"type": "string",
"format": "uuid",
"example": "7ff9bfd6-cd85-4190-8503-d6215a321519"
},
"custom_instructions": {
"description": "Up to 10 instructions of at most 300 characters each. Corresponds to `custom_instructions`,\nincluding its target language restriction.",
"type": "array",
"items": {
"type": "string",
"example": "Use a friendly, diplomatic tone"
}
},
"translation_memories": {
"description": "The translation memory to use for the translation, with an optional matching threshold. Corresponds\nto `translation_memory_id` and `translation_memory_threshold`. Currently one entry is supported;\na request with more is rejected with `400 Bad Request`.",
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/TranslationMemoryId"
},
"threshold": {
"description": "The minimum matching percentage required for a translation memory segment to be applied,\nbetween 50 and 100. Defaults to 75. A value outside this range is rejected with\n`400 Bad Request`.",
"type": "integer",
"minimum": 50,
"maximum": 100,
"default": 75,
"example": 75
}
}
}
},
"example_document_ids": {
"description": "Up to 10 example documents whose translations the model adapts to, in the order they should be\napplied. A document must be fully imported and written in the target language; a document that\ndoes not fit the request's language pair is left out. An ID your account cannot access is rejected\nwith `404 Not Found`.\n\nAvailable for accounts with example documents enabled.",
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"example": "9e7b41c2-58da-4a03-b6f1-3c85e0d97a26"
}
}
}
},
"tag_handling": {
"$ref": "#/components/schemas/TagHandlingOption"
},
Expand Down
75 changes: 75 additions & 0 deletions api-reference/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -665,6 +665,81 @@ paths:
items:
type: string
example: "Use a friendly, diplomatic tone"
customizations:
description: |-
All customizations of the request in one object: glossaries, a style rule list, custom
instructions, a translation memory and example documents. For new integrations we recommend
this object over the individual customization parameters. Each field behaves like the
parameter it corresponds to.

Cannot be used together with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`,
`translation_memory_threshold` or `custom_instructions`. A request that combines them is rejected
with `400 Bad Request` naming the conflicting parameter. Accepted in JSON request bodies only.

Available for accounts that have it enabled. Contact your DeepL representative to request access.
type: object
properties:
glossary_ids:
description: |-
Up to 5 glossaries to use for the translation, in the order they should be applied. Corresponds to
`glossary_ids`: requires `source_lang`, and every listed glossary must contain a dictionary for the
requested language pair.
type: array
items:
type: string
format: uuid
example: def3a26b-3e84-45b3-84ae-0c0aaf3525f7
style_rule_id:
description: |-
The [style rule list](/docs/customize/using-style-rules) to use for the translation. Corresponds to
`style_id`: the target language has to match the language of the style rule list.
type: string
format: uuid
example: 7ff9bfd6-cd85-4190-8503-d6215a321519
custom_instructions:
description: |-
Up to 10 instructions of at most 300 characters each. Corresponds to `custom_instructions`,
including its target language restriction.
type: array
items:
type: string
example: "Use a friendly, diplomatic tone"
translation_memories:
description: |-
The translation memory to use for the translation, with an optional matching threshold. Corresponds
to `translation_memory_id` and `translation_memory_threshold`. Currently one entry is supported;
a request with more is rejected with `400 Bad Request`.
type: array
items:
type: object
required:
- id
properties:
id:
$ref: '#/components/schemas/TranslationMemoryId'
threshold:
description: |-
The minimum matching percentage required for a translation memory segment to be applied,
between 50 and 100. Defaults to 75. A value outside this range is rejected with
`400 Bad Request`.
type: integer
minimum: 50
maximum: 100
default: 75
example: 75
example_document_ids:
description: |-
Up to 10 example documents whose translations the model adapts to, in the order they should be
applied. A document must be fully imported and written in the target language; a document that
does not fit the request's language pair is left out. An ID your account cannot access is rejected
with `404 Not Found`.

Available for accounts with example documents enabled.
type: array
items:
type: string
format: uuid
example: 9e7b41c2-58da-4a03-b6f1-3c85e0d97a26
tag_handling:
$ref: '#/components/schemas/TagHandlingOption'
tag_handling_version:
Expand Down
2 changes: 2 additions & 0 deletions docs/customize/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ DeepL's customization features let you control terminology, style, and consisten

Glossaries, style rules, custom instructions, and translation memories work with both [text translation](/docs/translate/translate-text-quickstart) and [document translation](/docs/translate/translate-documents-quickstart), support all `model_type` values, and can be combined in a single request. Spoken terms apply to [Voice API](/docs/voice/overview) sessions, where they can be combined with glossaries.

On the text translation endpoint you can also send all of them in one [`customizations` object](/api-reference/translate/request-translation#body-customizations) instead of the individual parameters. We recommend the object for new integrations.

<Warning>
Glossaries and style rules are unique to each of DeepL's global data centers and are not shared between them. Clients using [regional endpoints](/docs/getting-started/regional-endpoints) can't access glossaries or style rules created in the UI at this time.
</Warning>
Expand Down
Loading