{
"openapi": "3.1.0",
"info": {
"title": "Translation API",
"description": "This API allows 3rd party developers to translate item titles and item descriptions.",
"contact": {
"name": "eBay Inc,"
},
"license": {
"name": "eBay API License Agreement",
"url": "https://developer.ebay.com/join/api-license-agreement"
},
"version": "v1_beta.1.6"
},
"servers": [
{
"url": "https://api.ebay.com{basePath}",
"description": "Production",
"variables": {
"basePath": {
"default": "/commerce/translation/v1_beta"
}
}
}
],
"security": [
{}
],
"paths": {
"/translate": {
"post": {
"tags": [
"language"
],
"description": "This method translates listing title and listing description text from one language into another. For a full list of supported language translations, see the table.",
"operationId": "translate",
"parameters": [
{
"name": "Content-Type",
"in": "header",
"description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TranslateRequest"
},
"examples": {
"translate-example": {
"summary": "Translate an item title from English to German",
"value": {
"from": "en",
"to": "de",
"text": [
"Bernina 790e Pro Embroidery Long Arm Sewing Machine"
],
"translationContext": "ITEM_TITLE"
}
}
}
}
},
"required": true,
"description": "The request payload containing the text and language settings for translation."
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TranslateResponse"
},
"examples": {
"translate-response": {
"summary": "Successful translation response",
"value": {
"from": "en",
"to": "de",
"translations": [
{
"originalText": "Bernina 790e Pro Embroidery Long Arm Sewing Machine",
"translatedText": "Bernina 790e Pro Stickerei Langarm N?hmaschine"
}
]
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"110000": {
"domain": "API_TRANSLATION",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
},
"110001": {
"domain": "API_TRANSLATION",
"category": "REQUEST",
"description": "From language is invalid, missing or not supported. For more information, see the API call reference documentation."
},
"110002": {
"domain": "API_TRANSLATION",
"category": "REQUEST",
"description": "To language is invalid, missing or not supported. For more information, see the API call reference documentation."
},
"110003": {
"domain": "API_TRANSLATION",
"category": "REQUEST",
"description": "Context is not supported. For more information, see the API call reference documentation."
},
"110004": {
"domain": "API_TRANSLATION",
"category": "REQUEST",
"description": "Maximum number of input text reached. For more information, see the API call reference documentation."
},
"110005": {
"domain": "API_TRANSLATION",
"category": "REQUEST",
"description": "Maximum length of input text reached. For more information, see the API call reference documentation."
},
"110006": {
"domain": "API_TRANSLATION",
"category": "REQUEST",
"description": "Unsupported from and to combination."
},
"110007": {
"domain": "API_TRANSLATION",
"category": "REQUEST",
"description": "Markups are not supported in input texts for title translation context."
},
"110008": {
"domain": "API_TRANSLATION",
"category": "REQUEST",
"description": "Input text missing."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"110000": {
"domain": "API_TRANSLATION",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
],
"summary": "Translate text from one language to another"
},
"summary": "Translate listing content"
}
},
"components": {
"schemas": {
"Error": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "Identifies the type of error."
},
"domain": {
"type": "string",
"description": "Name for the primary system where the error occurred. This is relevant for application errors."
},
"errorId": {
"type": "integer",
"description": "A unique number to identify the error.",
"format": "int32"
},
"inputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"longMessage": {
"type": "string",
"description": "A more detailed explanation of the error."
},
"message": {
"type": "string",
"description": "Information on how to correct the problem, in the end user's terms and language where applicable."
},
"outputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
}
},
"description": "This type defines the fields that can be returned in an error."
},
"ErrorParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The object of the error.",
"examples": [
"categoryId"
]
},
"value": {
"type": "string",
"description": "The value of the object.",
"examples": [
"1234"
]
}
},
"description": "Used to specify information relevant to the end user/client."
},
"LanguageEnum": {
"type": "string",
"description": "This enumeration type lists the languages that are currently supported for either input or output text. For a full list of supported language translations, see the Supported languages table. | - **de**: Indicates the language of the input or output text is German. - **en**: Indicates the language of the input or output text is English. - **es**: Indicates the language of the input or output text is Spanish. - **fr**: Indicates the language of the input or output text is French. - **it**: Indicates the language of the input or output text is Italian. - **ja**: Indicates the language of the input or output text is Japanese. - **pl**: Indicates the language of the input or output text is Polish. - **pt**: Indicates the language of the input or output text is Portuguese. - **ru**: Indicates the language of the input or output text is Russian. - **zh**: Indicates the language of the input or output text is Chinese.",
"enum": [
"de",
"en",
"es",
"fr",
"it",
"ja",
"pl",
"pt",
"ru",
"zh"
]
},
"TranslateRequest": {
"type": "object",
"properties": {
"from": {
"description": "The language of the input text to be translated. Not all LanguageEnum values are supported in this field. For a full list of supported language pairings, see the Supported languages table.",
"$ref": "#/components/schemas/LanguageEnum",
"allOf": [
{
"$ref": "#/components/schemas/LanguageEnum"
}
],
"examples": [
"en"
]
},
"text": {
"type": "array",
"description": "The input text to translate. The maximum number of characters permitted is determined by the translationContext value:ITEM_TITLE: 1000 characters maximumITEM_DESCRIPTION: 20,000 characters maximum.
Note: When translating ITEM_DESCRIPTION text, HTML/CSS markup and links can be included and will not count toward this 20,000 character limit.
Note: Currently, only one input string can be translated per API call. Support for multiple continuous text strings are expected in the future.",
"items": {
"type": "string",
"description": "A text string to be translated."
}
},
"to": {
"description": "The target language for the translation of the input text. Not all LanguageEnum values are supported in this field. For a full list of supported language pairings, see the Supported languages table.",
"$ref": "#/components/schemas/LanguageEnum",
"allOf": [
{
"$ref": "#/components/schemas/LanguageEnum"
}
],
"examples": [
"de"
]
},
"translationContext": {
"description": "Input the listing entity to be translated.
Valid Values: ITEM_TITLE and ITEM_DESCRIPTION",
"$ref": "#/components/schemas/TranslationContextEnum",
"allOf": [
{
"$ref": "#/components/schemas/TranslationContextEnum"
}
],
"examples": [
"ITEM_TITLE"
]
}
},
"description": "This is the base type of the translate method request payload.",
"required": [
"from",
"text",
"to",
"translationContext"
]
},
"TranslateResponse": {
"type": "object",
"properties": {
"from": {
"description": "The enumeration value indicates the language of the input text.",
"$ref": "#/components/schemas/LanguageEnum",
"allOf": [
{
"$ref": "#/components/schemas/LanguageEnum"
}
],
"examples": [
"en"
]
},
"to": {
"description": "The enumeration value indicates the language of the translated text.",
"$ref": "#/components/schemas/LanguageEnum",
"allOf": [
{
"$ref": "#/components/schemas/LanguageEnum"
}
],
"examples": [
"de"
]
},
"translations": {
"type": "array",
"description": "An array showing the input and translated text. Only one input string can be translated at this time. Support for multiple continuous text strings are expected in the future.",
"items": {
"$ref": "#/components/schemas/Translation"
}
}
},
"description": "This is the base type of the translate method response payload.",
"required": [
"from",
"to",
"translations"
]
},
"Translation": {
"type": "object",
"properties": {
"originalText": {
"type": "string",
"description": "The original text, in the language specified in the from field, that was input into the text field in the request.",
"examples": [
"Bernina 790e Pro Embroidery Long Arm Sewing Machine"
]
},
"translatedText": {
"type": "string",
"description": "The translation of the original text into the language specified in the to field.",
"examples": [
"Bernina 790e Pro Stickerei Langarm N?hmaschine"
]
}
},
"description": "This type is used by the translations array, which shows the original text supplied by the user in the request payload, and the text translated by eBay.
Only one input string can be translated at this time. Support for multiple continuous text strings are expected in the future.",
"required": [
"originalText",
"translatedText"
]
},
"TranslationContextEnum": {
"type": "string",
"description": "This enumeration type indicates the listing entities that may be translated with the Translation API. | - **ITEM_TITLE**: This value is input into the translationContext input field if the user wishes to translate a listing title. - **ITEM_DESCRIPTION**: This value is input into the translationContext input field if the user wishes to translate a listing description.",
"enum": [
"ITEM_TITLE",
"ITEM_DESCRIPTION"
]
}
},
"securitySchemes": {
"api_auth": {
"type": "oauth2",
"description": "The security definitions for this API. Please check individual operations for applicable scopes.",
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"scopes": {
"https://api.ebay.com/oauth/api_scope": "View public data from eBay"
}
}
}
},
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
},
"tags": [
{
"name": "language",
"description": "Operations for translating listing content."
}
]
}