# Translation processing modes


When translating documents, you can use two different translation processing modes: real-time translation or asynchronous batch processing. The mode you use is based on the size and type of the target documents and affects how you submit the translation job and view its results.
+ [Real-time translation](sync.md) – You make a synchronous request to translate a small amount of text (or a text file) and Amazon Translate responds immediately with the translated text.
+ [Asynchronous batch processing](async.md) – You put a collection of documents in an Amazon Simple Storage Service (Amazon S3) location and start an asynchronous processing job to translate them. Amazon Translate sends the translated output documents to a specified Amazon S3 location.

# Real-time translation
Real-time translation

Amazon Translate provides real-time document and text translation operations that immediately return the translations. You can use the console or the API to perform real-time translations.

**Topics**
+ [

# Real-time translation using the console
](sync-console.md)
+ [

# Real-time translation using the API
](sync-api.md)

# Real-time translation using the console
Real-time translation (console)

To use the console for real-time translations, paste input text into the **Source language** text box or provide the input text as a file. Optionally, you can set features such as the desired formality level, profanity masking, brevity, and custom terminology. 

You can use auto language detection with real-time translations, but you may incur a charge. For more information, see [Automatic language detection](how-it-works.md#how-to-auto).

**Topics**
+ [

## Translate text
](#sync-console-text)
+ [

## Translate a document
](#sync-console-document)
+ [

## View equivalent API request and response data
](#sync-console-output)
+ [

## Use translation features
](#sync-console-features)

## Translate text


Use the Amazon Translate console to translate up to 10,000 bytes of text.

1. Open the [Amazon Translate console](https://console.aws.amazon.com/translate/home).

1. In the navigation menu on the left, choose **Real-time translation**.

1. For **Source language**, select the language of the source text, or keep the value as **Auto** for auto detection.

1. For **Target language**, select a language.

1. Enter or paste text into the **Source language** text box. The console displays the translated text in the **Target language** text box.  
![\[The translate text page of the Amazon Translate console.\]](http://docs.aws.amazon.com/translate/latest/dg/images/gs-10.png)

## Translate a document


Real-time document translation supports translations from English to any supported language, and from any supported language to English.

To translate a document using the Amazon Translate console:

1. Open the [Amazon Translate console](https://console.aws.amazon.com/translate/home).

1. In the navigation menu on the left, choose **Real-time translation**.

1. In the Translation panel, choose the **Documents** tab.  
![\[The translate document screen of the Amazon Translate console.\]](http://docs.aws.amazon.com/translate/latest/dg/images/gs-12.png)

1. For **Source language**, select the language of the source text, or select **Auto** for auto detection.

1. For **Target language**, select a language. If the source language is not English, you must select English for the target language.

1. Under **Upload file**, choose **Choose file** and enter the path to the source file. The maximum file size is 100 KB.

1. For **Document type**, select the format of the translation source file. Document translation supports plain text, HTML, or Word (.docx) input files.

1. Choose **Translate**.

   After the translation task completes, choose **Download translation** to download the translated document to your local hard drive. The format of the translated document (text, HTML, or Word) matches the input document.

## View equivalent API request and response data


After you use the console to translate the input text or document, you can view the equivalent API request data and response data in JSON format.

1. Below the **Translation** panel, expand the ** Application integration** panel.

   The console displays the equivalent translation request data in JSON format.   
![\[JSON code samples for translating text.\]](http://docs.aws.amazon.com/translate/latest/dg/images/gs-20.png)

1. You can copy the **JSON request** to use in a [TranslateText](https://docs.aws.amazon.com/translate/latest/APIReference/API_TranslateText.html) or [TranslateDocument](https://docs.aws.amazon.com/translate/latest/APIReference/API_TranslateDocument.html) API operation. 

1. The JSON output in the **JSON response panel** matches the output that the API generates.

## Use translation features


To use translation features with the Amazon Translate console:

1. Open the [Amazon Translate console](https://console.aws.amazon.com/translate/home).

1. In the navigation menu on the left, choose **Real-time translation**.

1. Provide the source language, target language, and the input data (text or document) as described in the previous procedures.

1. Under **Additional settings**, you can choose to customize the output of your translation job with the following settings:  
**Custom terminology**  
Select a custom terminology file. If the file has an entry for a source term in the input text, Amazon Translate uses the translation from the terminology file.  
For more information, see [Customizing your translations with custom terminology](how-custom-terminology.md).  
**Brevity**  
Reduces the length of the translation output for most translations (compared to the translation output without brevity). Amazon Translate supports brevity for translating text, but not for translating a document. Amazon Translate ignores the brevity setting if the source and target language form an unsupported language pair for brevity.   
For information about supported languages, see [Using brevity in Amazon Translate](customizing-translations-brevity.md).  
**Profanity**  
Masks profane words and phrases in your translation output. Amazon Translate doesn't support profanity masking in all supported languages.   
For more information, see [Masking profane words and phrases in Amazon Translate](customizing-translations-profanity.md).  
**Formality**  
For some target languages, you can set **Formality** to formal or informal. Amazon Translate ignores the formality setting if formality doesn't support the target language.  
For more information, see [Setting formality in Amazon Translate](customizing-translations-formality.md).

1. For document translation, choose **Translate** to translate the document using the chosen features.

   For text translation, the console applies the translation feature to the translated text when you choose each feature.

# Real-time translation using the API
Real-time translation (API)

Amazon Translate provides the following real-time translation operations to support interactive applications:
+  [TranslateText](https://docs.aws.amazon.com/translate/latest/APIReference/API_TranslateText.html) – translates a block of text.
+  [TranslateDocument](https://docs.aws.amazon.com/translate/latest/APIReference/API_TranslateDocument.html) – translates the contents of a file (plain text, HTML, or .docx).

These synchronous operations return the translation result directly to your application. If you use auto language detection with these operations, you may incur a charge. For more information, see [Automatic language detection](how-it-works.md#how-to-auto).

## Translate text


Use the [TranslateText](https://docs.aws.amazon.com/translate/latest/APIReference/API_TranslateText.html) operation to translate a single block of text.

### Translate text using the command line


The following example shows how to use the [TranslateText](https://docs.aws.amazon.com/translate/latest/APIReference/API_TranslateText.html) operation from the command line. The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^). 

At the command line, enter the following command. 

```
aws translate translate-text \
            --region region \
            --source-language-code "en" \
            --target-language-code "es" \
            --text "hello, world"
```

The command responds with the following JSON:

```
{
    "TargetLanguageCode": "es",
    "TranslatedText": "Hola, mundo",
    "SourceLanguageCode": "en"
}
```

### Translate text using a JSON file


This example shows how to use a JSON file to translate a longer text block. You can specify the source and target language on the command line, or you specify them in the JSON file.

**Note**  
The example JSON file is formatted for readability. Reformat the `"Text"` field to remove line breaks.  
The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^).

**To translate text using a JSON file**

1. Copy the following text into a JSON file called `translate.json`:

   ```
   {
       "Text": "Amazon Translate translates documents between languages in 
       real time. It uses advanced machine learning technologies 
       to provide high-quality real-time translation. Use it to 
       translate documents or to build applications that work in 
       multiple languages.", 
       "SourceLanguageCode": "en", 
       "TargetLanguageCode": "fr"
   }
   ```

1. In the AWS CLI, run the following command:

   ```
   aws translate translate-text \
               --region region \
               --cli-input-json file://translate.json > translated.json
   ```

   The command outputs a JSON file that contains the following JSON text:

   ```
   {
       "TargetLanguageCode": "fr", 
       "TranslatedText": "Amazon Translate traduit les documents entre 
       les langue en temps réel. Il utilise des technologies 
       avancées d'apprentissage de la machine pour fournir 
       une traduction en temps réel de haute qualité. Utilisez-le 
       pour traduire des documents ou pour créer des applications 
       qui fonctionnent en plusieurs langues.", 
       "SourceLanguageCode": "en"
   }
   ```

## Translate document


Use the [TranslateDocument](https://docs.aws.amazon.com/translate/latest/APIReference/API_TranslateDocument.html) operation to translate a text, HTML, or Word (.docx) document and return the translation result directly to your application.

Real-time document translation supports translations from English to any supported language, and from any supported language to English. You can specify the source language code or use auto detect. 

### Translate document using the command line


The following example shows how to use the [TranslateDocument](https://docs.aws.amazon.com/translate/latest/APIReference/API_TranslateDocument.html) operation from the command line. The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\$1) Unix continuation character at the end of each line with a caret (^). 

At the command line, enter the following command. 

```
aws translate translate-document \
            --region region \
            --source-language-code "en" \
            --target-language-code "es" \
            --document-content fileb://source-lang.txt 
            --document ContentType=text/plain 
            --query "TranslatedDocument.Content" 
            --output text | base64 
            --decode > target-lang.txt
```

The command responds with the following JSON:

```
{
    "SourceLanguageCode": "en",
    "TargetLanguageCode": "es",
    "TranslatedDocument":{
      "Content": blob
    }
}
```

# Asynchronous batch processing with Amazon Translate
Asynchronous batch processing

To translate large collections of documents (up to 5 GB in size), use the Amazon Translate asynchronous batch processing operation, [StartTextTranslationJob](https://docs.aws.amazon.com/translate/latest/APIReference/API_StartTextTranslationJob.html). This is best for collections of short documents, such as social media postings or user reviews, or any situation in which instantaneous translation is not required.

To perform an asynchronous batch translation, you typically perform the following steps:

1. Store a set of documents in an input folder inside of an Amazon S3 bucket.

1. Start a batch translation job.

1. As part of your request, provide Amazon Translate with an IAM role that has read access to the input Amazon S3 folder and all its sub-folders. The role must also have read and write access to an output Amazon S3 bucket.

1. Monitor the progress of the batch translation job.

1. Retrieve the results of the batch translation job from the specified output bucket.

## Region availability


Batch translation is supported in the following AWS Regions:
+ US East (Ohio)
+ US East (N. Virginia)
+ US West (N. California)
+ US West (Oregon)
+ Asia Pacific (Mumbai)
+ Asia Pacific (Seoul)
+ Asia Pacific (Singapore) 
+ Asia Pacific (Sydney) 
+ Asia Pacific (Tokyo)
+ Canada (Central)
+ Europe (Frankfurt)
+ Europe (Ireland)
+ Europe (London)
+ Europe (Paris)
+ Europe (Stockholm)

**Topics**
+ [

## Region availability
](#async-regions)
+ [

# Prerequisites for batch translation jobs
](async-prereqs.md)
+ [

# Running a batch translation job
](async-start.md)
+ [

# Monitoring and analyzing batch translation jobs
](async-monitor.md)
+ [

# Getting batch translation results
](async-results.md)

# Prerequisites for batch translation jobs
Prerequisites

The following prerequisites must be met in order for Amazon Translate to perform a successful batch translation job:
+ The Amazon S3 buckets that contain your input and output documents must be in the same AWS Region as the API endpoint you are calling.
+ The collection of batch input documents must be 5 GB or less in size.
+ There can be a maximum of one million documents submitted in a batch translation job.
+ Each input document must be 20 MB or less and must contain fewer than 1 million characters.
+ Your input files must be in a folder in an Amazon S3 bucket. If you add your input files to the top level of a bucket, Amazon Translate throws an error when you attempt to run a batch translation job. This requirement applies to the input files. No folder is necessary for the output files, and Amazon Translate can place them at the top level of an Amazon S3 bucket.
+ Your input file folder can contain nested folders. Make sure none of the nested folders are named **details**, otherwise Amazon Translate throws an error when you attempt to run the batch translation job.

## Supported file formats


Amazon Translate supports the following types of files for batch translation jobs:
+ Plain text.
+ HTML.
+ Word documents (.docx).
+ PowerPoint Presentation files (.pptx).
+ Excel Workbook files (.xlsx).
+ XML Localization Interchange File Format (XLIFF) files (.xlf). Amazon Translate supports only XLIFF version 1.2.

Amazon Translate requires files to be UTF-8 encoded.

## Prerequisite permissions


Before you can run a batch translation job, your AWS account must have a service role in IAM. This role must have a permissions policy that grants Amazon Translate:
+ Read access to your input folder and all its sub-folders in Amazon S3.
+ Read and write access to your output bucket.

It must also include a trust policy that allows Amazon Translate to assume the role and gain its permissions. This trust policy must allow the `translate.amazonaws.com` service principal to perform the `sts:AssumeRole` action.

When you create a batch translation job by using the Amazon Translate console, you have the option to allow Amazon Translate to automatically create this role for you. When you run a batch translation job by using the AWS CLI or the Amazon Translate API, you provide the Amazon Resource Name (ARN) of the role in your request.

For more information, see [Creating a Role to Delegate Permissions to an AWS Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*.

**Example Permissions policy**  
The following example permissions policy grants read access to an input folder in an Amazon S3 bucket. It grants read and write access to an output bucket.    
****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": [
        "arn:aws:s3:::input-bucket-name/*",
        "arn:aws:s3:::output-bucket-name/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": [
        "arn:aws:s3:::input-bucket-name",
        "arn:aws:s3:::output-bucket-name"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::output-bucket-name/*"
    }
  ]
}
```

**Example Trust policy**  
The following trust policy allows Amazon Translate to assume the IAM role that the policy belongs to.  
We recommend that you verify the AWS account that is using the trust policy, to mitigate the [ Confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) problem. This example uses the **aws:SourceArn** and **aws:SourceAccount** condition keys to verify the source account. Enter the AWS account that submits the batch translation job.     
****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "translate.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "ArnLike": {
            "aws:SourceArn": "arn:aws:translate:*:111122223333:*"
        },
        "StringEquals": {
            "aws:SourceAccount": "111122223333"
        }
      }
    }
  ]
}
```

## Prerequisite permissions to customize encryption


You can customize your encryption settings in Amazon Translate, but first you must add permissions to the service role in IAM.

Amazon Translate encrypts the translation output that you produce when you run a batch translation job. By default, it does this encryption with an *AWS managed key*. This type of key is created by AWS and stored in AWS Key Management Service (AWS KMS) in your account. However, you cannot manage this KMS key yourself. It is managed and used on your behalf only by AWS.

Optionally, you can choose to encrypt your output with a *customer managed key*, which is a KMS key that you create, own, and manage in your AWS account. 

Your key must have a key policy that enables Amazon Translate to use it. The key policy does this by granting its permissions to the service role that allows Amazon Translate to access your Amazon S3 bucket. 

The key policy allows the service role to perform the AWS KMS operations that are required to encrypt your output, as shown by the following example policy statement. 

**Example KMS key policy statement**  

```
{
  "Effect": "Allow",
  "Principal":
  {
    "AWS":
    [
      "arn:aws:iam::111122223333:role/AmazonTranslateServiceRoleS3FullAccess"
    ]
  },
  "Action":
  [
    "kms:Decrypt",
    "kms:GenerateDataKey",
    "kms:CreateGrant",
    "kms:RetireGrant",
    "kms:DescribeKey"
  ],
  "Resource": "*"
}
```

For more information, see [Key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) in the *AWS Key Management Service Developer Guide*

### Permissions to use an AWS KMS key from another AWS account


If you want to use a KMS key that's in a different AWS account from the one where you use Amazon Translate, then you must: 

1. Update the service role for Amazon Translate in IAM.

1. Update the key policy in AWS KMS.

To update your service role, attach a policy that allows it to perform the necessary AWS KMS operations with the KMS key that's in the other AWS account, as shown by the following example.

**Example IAM policy to grant access to a KMS key in a different account**  

```
{
  "Effect": "Allow",
  "Action":
  [
    "kms:Decrypt",
    "kms:GenerateDataKey",
    "kms:CreateGrant",
    "kms:RetireGrant",
    "kms:DescribeKey"
  ],
  "Resource": "arn:aws:kms:us-west-2:111122223333:key/key-id"
}
```

To update your KMS key policy, add the service role and admin user as principals that are allowed to use the key, as shown by the following example policy statement.

**Example KMS key policy statement to allow an IAM role to use the key**  

```
{
  "Effect": "Allow",
  "Principal":
  {
    "AWS":
    [
      "arn:aws:iam::444455556666:role/AmazonTranslateServiceRoleS3FullAccess",
      "arn:aws:iam::444455556666:admin"
    ]
  },
  "Action":
  [
    "kms:Decrypt",
    "kms:CreateGrant",
    "kms:GenerateDataKey",
    "kms:RetireGrant",
    "kms:DescribeKey"
  ],
  "Resource": "*"
}
```

For more information, see [Allowing users in other accounts to use a AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html) in the *AWS Key Management Service Developer Guide*

# Running a batch translation job
Running a job

You can run a batch translation job by using the Amazon Translate console, the AWS CLI, or the Amazon Translate API.

**Note**  
Batch translation jobs are long-running operations and can take significant time to complete. For example, batch translation on a small dataset might take a few minutes, while very large datasets may take up to 2 days or more. Completion time is also dependent on the availability of resources. 

## Amazon Translate console
Running a job (console)

To run a translation job by using the Amazon Translate console, use the **Batch translation** page to create the job:

1. Open the [Amazon Translate console](https://console.aws.amazon.com/translate/home).

1. In the navigation menu on the left, choose **Batch translation**.

1. On the **Translation jobs** page, choose **Create job**. The console shows the **Create translation job** page.

1. Under **Job settings**, do the following:

   1. For **Name**, enter a custom name for the batch translation job.

   1. For **Source language**, select the language of the source files. If you don't know the language of the source files, or your input documents contains different source languages, select `auto`. Amazon Translate auto detects the source language for each file. 

   1. For **Target languages**, select up to 10 languages. Amazon Translate translates each source file into each target language.

1. Under **Input data**, do the following:

   1. For **Input S3 location**, specify the input folder that contains the translation source files in Amazon S3. To provide the folder by navigating to it in Amazon S3, choose **Select folder**.

   1. For **File format**, select format of the translation source files.

1. Under **Output data**, do the following:

   1. For **Output S3 location**, specify the output folder in Amazon S3 where Amazon Translate puts the translation output. To provide the folder by navigating to it in Amazon S3, choose **Select folder**.

   1. Optionally, choose **Customize encryption settings (advanced)** if you want to encrypt your output with a customer managed key that you manage in the AWS Key Management Service (AWS KMS).

      By default, Amazon Translate encrypts your translation output using a KMS key that is created, managed, and used on your behalf by AWS. Choose this option if you want to encrypt your output with your own KMS key instead. 

      If you want to use a KMS key from the current AWS account, select it under **Choose an AWS Key Management Service key**. Or, if you want to use a KMS key from a different AWS account, enter the Amazon Resource Name (ARN) for that key.
**Note**  
Before you can use your own KMS key, you must add permissions to the service role for Amazon Translate in IAM. If you want to use a KMS key from a different account, you must also update the key policy in AWS KMS. For more information, see [Prerequisite permissions to customize encryption](async-prereqs.md#async-prereqs-permissions-custom-encryption).

1. Under **Customizations - optional**, you can choose to customize the output of your translation job with the following settings:  
**Profanity**  
Masks profane words and phrases in your translation output. If you specify multiple target languages for the job, all the target languages must support profanity masking. If any of the target languages don't support profanity masking, the translation job won't mask profanity for any target language.  
For more information, see [Masking profane words and phrases in Amazon Translate](customizing-translations-profanity.md).  
**Brevity**  
Amazon Translate doesn't support brevity for batch translation jobs.   
For more information, see [Using brevity in Amazon Translate](customizing-translations-brevity.md).  
**Formality**  
For some target languages, you can set **Formality** to formal or informal. If you specify multiple target languages for the job, translate ignores the formality setting for any unsupported target language.  
 For more information, see [Setting formality in Amazon Translate](customizing-translations-formality.md).  
**Custom terminology**  
Consists of example source terms and the desired translation for each term. If you specify multiple target languages for the job, translate uses the designated terminology for each requested target language that has an entry for the source term in the terminology file.  
For more information, see [Customizing your translations with custom terminology](how-custom-terminology.md).  
**Parallel data**  
Consists of examples that show how you want segments of text to be translated. If you specify multiple target languages for the job, the parallel data file must include translations for all the target languages.  
When you add parallel data to a batch translation job, you create an *Active Custom Translation* job.  
Active Custom Translation jobs are priced at a higher rate than other jobs that don't use parallel data. For more information, see [Amazon Translate pricing](https://aws.amazon.com/translate/pricing/).
For more information, see [Customizing your translations with parallel data (Active Custom Translation)](customizing-translations-parallel-data.md).

1. Under **Access permissions**, provide Amazon Translate with an IAM role that grants the required permissions to your input and output files in Amazon S3:
   + If you already have this IAM role in your account, choose **Use an existing IAM role**, and select it under **IAM role**.
   + If you don't already have this IAM role in your account, choose **Create an IAM role**. For **IAM role**, choose **Input and output S3 buckets**. For **Role name**, provide a custom name. When you create the translation job, Amazon Translate creates the role automatically. The role name in IAM is prefixed with *AmazonTranslateServiceRole-*.
**Note**  
If you chose to encrypt your translation output with your own KMS key, then you cannot choose **Create an IAM role**. In this case, you must use a preexisting IAM role, and your KMS key must have a key policy that allows the role to use the key.   
For more information, see [Prerequisite permissions to customize encryption](async-prereqs.md#async-prereqs-permissions-custom-encryption)

1. Choose **Create job**.

   The console returns to the **Translation jobs** page, where the job creation status is shown in a banner at the top of the page. After a few minutes, your job is shown in the table.

1. Choose the job name in the **Name** column to open the job details page.

   While your translation job runs, the **Status** field shows **In progress**. 

1. When the status becomes **Completed**, go to your translation output by choosing the link under **Output file location**. The console goes to your output bucket in Amazon S3.

1. To download your output files, select the check box for each, and choose **Download**.

## AWS CLI
Running a job (CLI)

To run a translation job by using the AWS CLI, use the [https://docs.aws.amazon.com/cli/latest/reference/translate/start-text-translation-job.html](https://docs.aws.amazon.com/cli/latest/reference/translate/start-text-translation-job.html) command, and specify the name of your parallel data resource for the `parallel-data-names` parameter.

**Example Start-text-translation-job command**  
The following example runs a translation job by submitting an Excel file that is stored in an input bucket in Amazon S3. This job is customized by the parallel data that is included in the request.  

```
$ aws translate start-text-translation-job \
> --input-data-config ContentType=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,S3Uri=s3://amzn-s3-demo-bucket/input/ \
> --output-data-config S3Uri=s3://amzn-s3-demo-bucket/output/ \
> --data-access-role-arn arn:aws:iam::111122223333:role/my-iam-role \
> --source-language-code en \
> --target-language-codes es it \
> --job-name my-translation-job
```
If the command succeeds, Amazon Translate responds with the job ID and status:  

```
{
    "JobId": "4446f95f20c88a4b347449d3671fbe3d",
    "JobStatus": "SUBMITTED"
}
```
If you want to customize the output of your translation job, you can use the following parameters:    
`--settings`  
Settings to configure your translation output, including the following options:  
Turn on brevity in the translation output. Amazon Translate doesn't support brevity for batch translation jobs. For more information, see [Using brevity in Amazon Translate](customizing-translations-brevity.md).  
Enable profanity to mask profane words and phrases. To enable, set the profanity parameter to `Profanity=MASK`. For more information, see [Masking profane words and phrases in Amazon Translate](customizing-translations-profanity.md). If any of the target languages don't support profanity masking, the translation job won't mask profanity for any target language.  
Set the level of formality in the translation output. Set the `Formality` parameter to `FORMAL` or `INFORMAL`. If you specify multiple target languages for the job, translate ignores the formality setting for any unsupported target language. For more information, see [Setting formality in Amazon Translate](customizing-translations-formality.md).  
`--terminology-names`  
The name of a custom terminology resource to add to the translation job. This resource lists example source terms and the desired translation for each term. If you specify multiple target languages for the job, translate uses the designated terminology for each requested target language that has an entry for the source term in the terminology file.  
This parameter accepts only one custom terminology resource.  
For a list of available custom terminology resources, use the [https://docs.aws.amazon.com/cli/latest/reference/translate/list-terminologies.html](https://docs.aws.amazon.com/cli/latest/reference/translate/list-terminologies.html) command.  
For more information, see [Customizing your translations with custom terminology](how-custom-terminology.md).  
`--parallel-data-names`  
The name of a parallel data resource to add to the translation job. This resource consists of examples that show how you want segments of text to be translated. If you specify multiple target languages for the job, the parallel data file must include translations for all the target languages.  
When you add parallel data to a translation job, you create an *Active Custom Translation* job.  
This parameter accepts only one parallel data resource.  
Active Custom Translation jobs are priced at a higher rate than other jobs that don't use parallel data. For more information, see [Amazon Translate pricing](https://aws.amazon.com/translate/pricing/).
For a list of available parallel data resources, use the [https://docs.aws.amazon.com/cli/latest/reference/translate/list-parallel-data.html](https://docs.aws.amazon.com/cli/latest/reference/translate/list-parallel-data.html) command.  
For more information, see [Customizing your translations with parallel data (Active Custom Translation)](customizing-translations-parallel-data.md).

To check the status of your translation job, use the [https://docs.aws.amazon.com/cli/latest/reference/translate/describe-text-translation-job.html](https://docs.aws.amazon.com/cli/latest/reference/translate/describe-text-translation-job.html) command.

**Example Describe-text-translation-job command**  

The following example checks the job status by providing the job ID. This ID was provided by Amazon Translate when the job was initiated by the `start-text-translation-job` command.

```
$ aws translate describe-text-translation-job \
> --job-id 4446f95f20c88a4b347449d3671fbe3d
```

Amazon Translate responds with the job properties, which include its status:

```
{
    "TextTranslationJobProperties": {
        "JobId": "4446f95f20c88a4b347449d3671fbe3d",
        "JobName": "my-translation-job",
        "JobStatus": "COMPLETED",
        "JobDetails": {
            "TranslatedDocumentsCount": 0,
            "DocumentsWithErrorsCount": 0,
            "InputDocumentsCount": 1
        },
        "SourceLanguageCode": "en",
        "TargetLanguageCodes": [
            "es", 
            "it" 
        ],
        "SubmittedTime": 1598661012.468,
        "InputDataConfig": {
            "S3Uri": "s3://amzn-s3-demo-bucket/input/",
            "ContentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
        },
        "OutputDataConfig": {
            "S3Uri": "s3://amzn-s3-demo-bucket/output/111122223333-TranslateText-4446f95f20c88a4b347449d3671fbe3d/"
        },
        "DataAccessRoleArn": "arn:aws:iam::111122223333:role/my-iam-role"
    }
}
```

If the `JobStatus` value is `IN_PROGRESS`, allow a few minutes to pass, and run [https://docs.aws.amazon.com/cli/latest/reference/translate/describe-text-translation-job.html](https://docs.aws.amazon.com/cli/latest/reference/translate/describe-text-translation-job.html) again until the status is `COMPLETED`. When the job completes, you can download the translation results at the location provided by the `S3Uri` field under `OutputDataConfig`.

## Amazon Translate API
Running a job (API)

To submit a batch translation job by using the Amazon Translate API, use the [StartTextTranslationJob](https://docs.aws.amazon.com/translate/latest/APIReference/API_StartTextTranslationJob.html) operation.

# Monitoring and analyzing batch translation jobs
Monitoring and analyzing

You can use a job's ID to monitor its progress and get the Amazon S3 location of its output documents. To monitor a specific job, use the [DescribeTextTranslationJob](https://docs.aws.amazon.com/translate/latest/APIReference/API_DescribeTextTranslationJob.html) operation. You can also use the [ListTextTranslationJobs](https://docs.aws.amazon.com/translate/latest/APIReference/API_ListTextTranslationJobs.html) operation to retrieve information on all of the translation jobs in your account. To restrict results to jobs that match a certain criteria, use the [ListTextTranslationJobs](https://docs.aws.amazon.com/translate/latest/APIReference/API_ListTextTranslationJobs.html) operation's `filter` parameter. You can filter results by job name, job status, or the date and time that the job was submitted. 

**Example describe-text-translation-job command**  
The following example check's a job's status by using the AWS CLI to run the [DescribeTextTranslationJob](https://docs.aws.amazon.com/translate/latest/APIReference/API_DescribeTextTranslationJob.html) command:  

```
$ aws translate describe-text-translation-job --job-id 1c1838f470806ab9c3e0057f14717bed
```
This command returns the following output:  

```
{
  "TextTranslationJobProperties": {
    "InputDataConfig": {
      "ContentType": "text/plain",
      "S3Uri": "s3://input-bucket-name/folder"
    },
    "EndTime": 1576551359.483,
    "SourceLanguageCode": "en",
    "DataAccessRoleArn": "arn:aws:iam::012345678901:role/service-role/AmazonTranslateInputOutputAccess",
    "JobId": "1c1838f470806ab9c3e0057f14717bed",
    "TargetLanguageCodes": [
      "fr"
    ],
    "JobName": "batch-test",
    "SubmittedTime": 1576544017.357,
    "JobStatus": "COMPLETED",
    "Message": "Your job has completed successfully.",
    "JobDetails": {
      "InputDocumentsCount": 77,
      "DocumentsWithErrorsCount": 0,
      "TranslatedDocumentsCount": 77
    },
    "OutputDataConfig": {
      "S3Uri": "s3://bucket-name/output/012345678901-TranslateText-1c1838f470806ab9c3e0057f14717bed/"
    }
  }
}
```

You can stop a batch translation job while its status is `IN_PROGRESS` by using the [StopTextTranslationJob](https://docs.aws.amazon.com/translate/latest/APIReference/API_StopTextTranslationJob.html) operation.

**Example stop-text-translation-job command**  
The following example stops a batch translation with by using the AWS CLI to run the [StopTextTranslationJob](https://docs.aws.amazon.com/translate/latest/APIReference/API_StopTextTranslationJob.html) command:  

```
$ aws translate stop-text-translation-job --job-id 5236d36ce5192abdb3e2519f3ab8b065
```
This command returns the following output:  

```
{
  "TextTranslationJobProperties": {
    "InputDataConfig": {
      "ContentType": "text/plain",
      "S3Uri": "s3://input-bucket-name/folder"
    },
    "SourceLanguageCode": "en",
    "DataAccessRoleArn": "arn:aws:iam::012345678901:role/service-role/AmazonTranslateInputOutputAccess",
    "TargetLanguageCodes": [
      "fr"
    ],
    "JobName": "canceled-test",
    "SubmittedTime": 1576558958.167,
    "JobStatus": "STOP_REQUESTED",
    "JobId": "5236d36ce5192abdb3e2519f3ab8b065",
    "OutputDataConfig": {
      "S3Uri": "s3://output-bucket-name/012345678901-TranslateText-5236d36ce5192abdb3e2519f3ab8b065/"
    }
  }
}
```

# Getting batch translation results
Getting results

Once the job's status is `COMPLETED` or `COMPLETED_WITH_ERROR`, your output documents are available in the Amazon S3 folder you specified. The output document names match the input document names, with the addition of the target language code as a prefix. For instance, if you translated a document called `mySourceText.txt` into French, the output document will be called `fr.mySourceText.txt`.

If the status of a batch translation job is `FAILED`, the [DescribeTextTranslationJob](https://docs.aws.amazon.com/translate/latest/APIReference/API_DescribeTextTranslationJob.html) operation response includes a `Message` field that describes the reason why the job didn't complete successfully.

Each batch translation job also generates an auxiliary file that contains information on the translations performed, such as the total number of characters translated and the number of errors encountered. This file, called `target-language-code.auxiliary-translation-details.json`, is generated in the `details` subfolder of your output folder.

The following is an example of a batch translation auxiliary file.

```
{
  "sourceLanguageCode": "en",
  "targetLanguageCode": "fr",
  "charactersTranslated": "105",
  "documentCountWithCustomerError": "0",
  "documentCountWithServerError": "0",
  "inputDataPrefix": "s3://input-bucket-name/folder",
  "outputDataPrefix": "s3://output-bucket-name/012345678901-TranslateText-1c1838f470806ab9c3e0057f14717bed/",
  "details": [
    {
      "sourceFile": "mySourceText.txt",
      "targetFile": "fr.mySourceText.txt",
      "auxiliaryData": {
        "appliedTerminologies": [
          {
            "name": "TestTerminology",
            "terms": [
              {
                "sourceText": "Amazon",
                "targetText": "Amazon"
              }
            ]
          }
        ]
      }
    },
    {
      "sourceFile": "batchText.txt",
      "targetFile": "fr.batchText.txt",
      "auxiliaryData": {
        "appliedTerminologies": [
          {
            "name": "TestTerminology",
            "terms": [
              {
                "sourceText": "Amazon",
                "targetText": "Amazon"
              }
            ]
          }
        ]
      }
    }
  ]
}
```