LanguageTranslator

public class LanguageTranslator

IBM Watson™ Language Translator translates text from one language to another. The service offers multiple IBM-provided translation models that you can customize based on your unique terminology and language. Use Language Translator to take news from across the globe and present it in your language, communicate with your customers in their own language, and more.

  • The base URL to use when contacting the service.

    Declaration

    Swift

    public var serviceURL: String?

  • Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-05-01.

    Declaration

    Swift

    public var version: String

  • Service identifiers

    Declaration

    Swift

    public static let defaultServiceName: String

  • The default HTTP headers for all requests to the service.

    Declaration

    Swift

    public var defaultHeaders: [String : String]

  • Undocumented

    Declaration

    Swift

    public let authenticator: Authenticator

  • Create a LanguageTranslator object.

    If an authenticator is not supplied, the initializer will retrieve credentials from the environment or a local credentials file and construct an appropriate authenticator using these credentials. The credentials file can be downloaded from your service instance on IBM Cloud as ibm-credentials.env. Make sure to add the credentials file to your project so that it can be loaded at runtime.

    If an authenticator is not supplied and credentials are not available in the environment or a local credentials file, initialization will fail by throwing an exception. In that case, try another initializer that directly passes in the credentials.

    • serviceName: String = defaultServiceName

  • Create a LanguageTranslator object.

    Declaration

    Swift

    public init(version: String, authenticator: Authenticator)

    Parameters

    version

    Release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. The current version is 2018-05-01.
    authenticator

    The Authenticator object used to authenticate requests to the service

  • Allow network requests to a server without verification of the server certificate. IMPORTANT: This should ONLY be used if truly intended, as it is unsafe otherwise.

    Declaration

    Swift

    public func disableSSLVerification()

  • List supported languages.

    Lists all supported languages for translation. The method returns an array of supported languages with information about each language. Languages are listed in alphabetical order by language code (for example, af, ar). In addition to basic information about each language, the response indicates whether the language is supported_as_source for translation and supported_as_target for translation. It also lists whether the language is identifiable.

    Declaration

    Swift

    public func listLanguages(
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Languages>?, WatsonError?) -> Void)

    Parameters

    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Translate.

    Translates the input text from the source language to the target language. Specify a model ID that indicates the source and target languages, or specify the source and target languages individually. You can omit the source language to have the service attempt to detect the language from the input text. If you omit the source language, the request must contain sufficient input text for the service to identify the source language. You can translate a maximum of 50 KB (51,200 bytes) of text with a single request. All input text must be encoded in UTF-8 format.

    Declaration

    Swift

    public func translate(
    text: [String],
    modelID: String? = nil,
    source: String? = nil,
    target: String? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<TranslationResult>?, WatsonError?) -> Void)

    Parameters

    text

    Input text in UTF-8 encoding. Submit a maximum of 50 KB (51,200 bytes) of text with a single request. Multiple elements result in multiple translations in the response.
    modelID

    The model to use for translation. For example, en-de selects the IBM-provided base model for English-to-German translation. A model ID overrides the source and target parameters and is required if you use a custom model. If no model ID is specified, you must specify at least a target language.
    source

    Language code that specifies the language of the input text. If omitted, the service derives the source language from the input text. The input must contain sufficient text for the service to identify the language reliably.
    target

    Language code that specifies the target language for translation. Required if model ID is not specified.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • List identifiable languages.

    Lists the languages that the service can identify. Returns the language code (for example, en for English or es for Spanish) and name of each language.

    Declaration

    Swift

    public func listIdentifiableLanguages(
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<IdentifiableLanguages>?, WatsonError?) -> Void)

    Parameters

    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Identify language.

    Identifies the language of the input text.

    Declaration

    Swift

    public func identify(
    text: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<IdentifiedLanguages>?, WatsonError?) -> Void)

    Parameters

    text

    Input text in UTF-8 format.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • List models.

    Lists available translation models.

    Declaration

    Swift

    public func listModels(
    source: String? = nil,
    target: String? = nil,
    `default`: Bool? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<TranslationModels>?, WatsonError?) -> Void)

    Parameters

    source

    Specify a language code to filter results by source language.
    target

    Specify a language code to filter results by target language.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Create model.

    Uploads training files to customize a translation model. You can customize a model with a forced glossary or with a parallel corpus:

    • Use a forced glossary to force certain terms and phrases to be translated in a specific way. You can upload only a single forced glossary file for a model. The size of a forced glossary file for a custom model is limited to 10 MB.
    • Use a parallel corpus when you want your custom model to learn from general translation patterns in parallel sentences in your samples. What your model learns from a parallel corpus can improve translation results for input text that the model has not been trained on. You can upload multiple parallel corpora files with a request. To successfully train with parallel corpora, the corpora files must contain a cumulative total of at least 5000 parallel sentences. The cumulative size of all uploaded corpus files for a custom model is limited to 250 MB. Depending on the type of customization and the size of the uploaded files, training time can range from minutes for a glossary to several hours for a large parallel corpus. To create a model that is customized with a parallel corpus and a forced glossary, customize the model with a parallel corpus first and then customize the resulting model with a forced glossary. You can create a maximum of 10 custom models per language pair. For more information about customizing a translation model, including the formatting and character restrictions for data files, see Customizing your model. #### Supported file formats You can provide your training data for customization in the following document formats:
    • TMX (.tmx) - Translation Memory eXchange (TMX) is an XML specification for the exchange of translation memories.
    • XLIFF (.xliff) - XML Localization Interchange File Format (XLIFF) is an XML specification for the exchange of translation memories.
    • CSV (.csv) - Comma-separated values (CSV) file with two columns for aligned sentences and phrases. The first row must have two language codes. The first column is for the source language code, and the second column is for the target language code.
    • TSV (.tsv or .tab) - Tab-separated values (TSV) file with two columns for aligned sentences and phrases. The first row must have two language codes. The first column is for the source language code, and the second column is for the target language code.
    • JSON (.json) - Custom JSON format for specifying aligned sentences and phrases.
    • Microsoft Excel (.xls or .xlsx) - Excel file with the first two columns for aligned sentences and phrases. The first row contains the language code. You must encode all text data in UTF-8 format. For more information, see Supported document formats for training data. #### Specifying file formats You can indicate the format of a file by including the file extension with the file name. Use the file extensions shown in Supported file formats. Alternatively, you can omit the file extension and specify one of the following content-type specifications for the file:
    • TMX - application/x-tmx+xml
    • XLIFF - application/xliff+xml
    • CSV - text/csv
    • TSV - text/tab-separated-values
    • JSON - application/json

    • Microsoft Excel - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet For example, with curl, use the following content-type specification to indicate the format of a CSV file named glossary: --form "forced_glossary=@glossary;type=text/csv".

    Declaration

    Swift

    public func createModel(
    baseModelID: String,
    forcedGlossary: Data? = nil,
    parallelCorpus: Data? = nil,
    name: String? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<TranslationModel>?, WatsonError?) -> Void)

    Parameters

    baseModelID

    The ID of the translation model to use as the base for customization. To see available models and IDs, use the List models method. Most models that are provided with the service are customizable. In addition, all models that you create with parallel corpora customization can be further customized with a forced glossary.
    forcedGlossary

    A file with forced glossary terms for the source and target languages. The customizations in the file completely overwrite the domain translation data, including high frequency or high confidence phrase translations. You can upload only one glossary file for a custom model, and the glossary can have a maximum size of 10 MB. A forced glossary must contain single words or short phrases. For more information, see Supported file formats in the method description. With curl, use --form forced_glossary=@{filename}..
    parallelCorpus

    A file with parallel sentences for the source and target languages. You can upload multiple parallel corpus files in one request by repeating the parameter. All uploaded parallel corpus files combined must contain at least 5000 parallel sentences to train successfully. You can provide a maximum of 500,000 parallel sentences across all corpora. A single entry in a corpus file can contain a maximum of 80 words. All corpora files for a custom model can have a cumulative maximum size of 250 MB. For more information, see Supported file formats in the method description. With curl, use --form parallel_corpus=@{filename}..
    name

    An optional model name that you can use to identify the model. Valid characters are letters, numbers, dashes, underscores, spaces, and apostrophes. The maximum length of the name is 32 characters.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Delete model.

    Deletes a custom translation model.

    Declaration

    Swift

    public func deleteModel(
    modelID: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<DeleteModelResult>?, WatsonError?) -> Void)

    Parameters

    modelID

    Model ID of the model to delete.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Get model details.

    Gets information about a translation model, including training status for custom models. Use this API call to poll the status of your customization request. A successfully completed training has a status of available.

    Declaration

    Swift

    public func getModel(
    modelID: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<TranslationModel>?, WatsonError?) -> Void)

    Parameters

    modelID

    Model ID of the model to get.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • List documents.

    Lists documents that have been submitted for translation.

    Declaration

    Swift

    public func listDocuments(
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<DocumentList>?, WatsonError?) -> Void)

    Parameters

    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Translate document.

    Submit a document for translation. You can submit the document contents in the file parameter, or you can reference a previously submitted document by document ID. The maximum file size for document translation is

    • 20 MB for service instances on the Standard, Advanced, and Premium plans

    • 2 MB for service instances on the Lite plan.

    Declaration

    Swift

    public func translateDocument(
    file: Data,
    filename: String,
    fileContentType: String? = nil,
    modelID: String? = nil,
    source: String? = nil,
    target: String? = nil,
    documentID: String? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<DocumentStatus>?, WatsonError?) -> Void)

    Parameters

    file

    The contents of the source file to translate. The maximum file size for document translation is 20 MB for service instances on the Standard, Advanced, and Premium plans, and 2 MB for service instances on the Lite plan. For more information, see Supported file formats (Beta).
    filename

    The filename for file.
    fileContentType

    The content type of file.
    modelID

    The model to use for translation. For example, en-de selects the IBM-provided base model for English-to-German translation. A model ID overrides the source and target parameters and is required if you use a custom model. If no model ID is specified, you must specify at least a target language.
    source

    Language code that specifies the language of the source document. If omitted, the service derives the source language from the input text. The input must contain sufficient text for the service to identify the language reliably.
    target

    Language code that specifies the target language for translation. Required if model ID is not specified.
    documentID

    To use a previously submitted document as the source for a new translation, enter the document_id of the document.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Get document status.

    Gets the translation status of a document.

    Declaration

    Swift

    public func getDocumentStatus(
    documentID: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<DocumentStatus>?, WatsonError?) -> Void)

    Parameters

    documentID

    The document ID of the document.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Delete document.

    Deletes a document.

    Declaration

    Swift

    public func deleteDocument(
    documentID: String,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Void>?, WatsonError?) -> Void)

    Parameters

    documentID

    Document ID of the document to delete.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error

  • Get translated document.

    Gets the translated document associated with the given document ID.

    Declaration

    Swift

    public func getTranslatedDocument(
    documentID: String,
    accept: String? = nil,
    headers: [String: String]? = nil,
    completionHandler: @escaping (WatsonResponse<Data>?, WatsonError?) -> Void)

    Parameters

    documentID

    The document ID of the document that was submitted for translation.
    accept

    The type of the response: application/powerpoint, application/mspowerpoint, application/x-rtf, application/json, application/xml, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.oasis.opendocument.spreadsheet, application/vnd.oasis.opendocument.presentation, application/vnd.oasis.opendocument.text, application/pdf, application/rtf, text/html, text/json, text/plain, text/richtext, text/rtf, or text/xml. A character encoding can be specified by including a charset parameter. For example, ‘text/html;charset=utf-8’.
    headers

    A dictionary of request headers to be sent with this request.
    completionHandler

    A function executed when the request completes with a successful result or error