Amazon Comprehend can detect the dominant language in a text document and return a language code with a confidence score. The language-detection feature can identify 100 languages, but other Comprehend features support smaller language sets. Check the feature-specific language support table before using a detected code with another API.

Detection returns the most likely language for each input document; it does not translate text or report the percentage of a document written in each language. For a long document that switches languages, split it into meaningful sections and aggregate the section results for your use case. See AWS's language detection guidance and limitations for the current language list and model behavior.

Set up AWS access

Choose an AWS Region where Amazon Comprehend is available. For local development, Boto3 uses the standard AWS credential provider chain; in AWS, prefer the workload's IAM role over long-lived access keys. Keep the Region consistent when you use S3-based analysis jobs.

Install Boto3 and choose a Region

Install the AWS SDK for Python and create a Comprehend client in the Region where you plan to make requests:

python -m pip install boto3
import boto3

comprehend = boto3.client("comprehend", region_name="us-east-1")

Replace us-east-1 with your Region. Boto3 obtains credentials from its configured provider chain, such as a named profile for local development or an IAM role attached to an AWS workload.

Choose an access method and grant permissions

You can try language detection in the AWS console or call it with the AWS CLI or an SDK. Grant the calling identity only the API actions its workflow needs. For the single-document and synchronous batch examples in this article, a minimal identity policy is:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "comprehend:DetectDominantLanguage",
      "comprehend:BatchDetectDominantLanguage"
    ],
    "Resource": "*"
  }]
}

These detection actions do not support resource-level permissions, so their identity policy uses "Resource": "*"; confirm this in the AWS Comprehend service authorization reference. An asynchronous job also requires permission to start and describe that job and permission to pass its data-access role. The separate data-access role must trust comprehend.amazonaws.com and allow the service to read the input and write the results in Amazon S3. AWS documents the caller and service-role requirements in its Amazon Comprehend IAM guidance.

Detect language in one document

Use DetectDominantLanguage when an application needs an immediate result for one document. Its input is a UTF-8 string with at least 20 characters and a maximum encoded size of 100 KB. The service measures the UTF-8 text size, so character count alone is not a safe limit for text with multibyte characters. See the DetectDominantLanguage API reference.

Check the text and call the API

Boto3 accepts a Python string for Text. This example checks the character minimum and UTF-8 byte size before sending the request; its 100,000-byte ceiling is a conservative guard below the documented 100 KB limit:

text = "Amazon Comprehend can identify the main language in this message."
utf8_size = len(text.encode("utf-8"))

if len(text) < 20:
    raise ValueError("Provide at least 20 characters of text")
if utf8_size > 100_000:
    raise ValueError("Text exceeds the 100 KB UTF-8 limit")

response = comprehend.detect_dominant_language(Text=text)
languages = response["Languages"]
dominant = languages[0]

print(dominant["LanguageCode"], dominant["Score"])

For best results, provide enough natural-language context. AWS notes that detection can struggle with short input, phonetic spellings, and closely related languages such as Indonesian and Malay. A Python string that cannot be encoded as UTF-8 should be corrected at the source; encoding and decoding it again does not repair invalid source data.

Read the language code and score

The response contains a Languages array ordered by descending score. Its first entry is the detected dominant language. For example, an abbreviated response might look like this:

{
  "Languages": [
    {"LanguageCode": "en", "Score": 0.98},
    {"LanguageCode": "de", "Score": 0.01}
  ]
}

LanguageCode follows RFC 5646. Common values include en for English, es for Spanish, and zh-TW for Traditional Chinese. Score is the model's confidence that a language is dominant. AWS says each score is independent: do not add the scores or interpret one as the percentage of the document written in that language.

Use the score as one input to an application decision, not as a guarantee that the prediction is correct. Review representative examples and decide how to handle uncertain results before automatically routing or processing user content.

Handle rejected or uncertain input

If AWS rejects a request, catch Boto3's botocore.exceptions.ClientError and inspect exc.response["Error"]["Code"] to identify the cause. Common checks include IAM permission, the configured Region, non-empty text, the 20-character minimum, and the UTF-8 byte limit. AWS describes this pattern in its Boto3 error-handling guide. Do not retry an unchanged request that fails validation.

For transient service or throttling errors, configure Boto3 retries for the error types your application needs and apply application-level rate limiting if needed. AWS applies dynamic throttling to synchronous requests rather than one fixed transactions-per-second limit for every account and Region; check current Comprehend quotas and Boto3's retry options for your workload.

Choose a mode for multiple documents

Amazon Comprehend has two synchronous choices and an asynchronous S3 job for language detection. “Batch” can mean either a synchronous request containing a small group of documents or a large asynchronous job, so choose by both document size and when your application needs the result.

OperationInput limitResult handling
DetectDominantLanguageOne document, up to 100 KB of UTF-8 text; at least 20 characters.Synchronous response for one document.
BatchDetectDominantLanguageUp to 25 documents per request; each should contain at least 20 characters and be no larger than 5 KB.Synchronous response with separate results and errors.
StartDominantLanguageDetectionJobDocuments in S3, up to 1 MB per document; async quotas also cap the input collection.Asynchronous job writes results to S3; poll job status.

The synchronous batch API handles up to 25 short documents in one request. It is still synchronous: the caller waits for a response. Use the S3 job for a larger collection or documents too large for the batch API. Current asynchronous quotas include a 5 GB total input limit and up to 1,000,000 input files or lines; see AWS's guidelines and quotas before submitting a large job. Quotas can change, and some are Region-specific.

Start an asynchronous job from S3

Upload UTF-8 documents to an S3 input location, then start a job. The input and output S3 locations must be in the same Region as the Comprehend endpoint. The service's data-access role needs s3:ListBucket and s3:GetObject for input, plus s3:PutObject for output. The identity starting the job needs the Comprehend start and describe actions and iam:PassRole for that role; the identity that uploads input or reads output also needs its own S3 permissions.

job = comprehend.start_dominant_language_detection_job(
    InputDataConfig={
        "S3Uri": "s3://example-bucket/input/",
        "InputFormat": "ONE_DOC_PER_LINE",
    },
    OutputDataConfig={"S3Uri": "s3://example-bucket/output/"},
    DataAccessRoleArn=(
        "arn:aws:iam::123456789012:role/ComprehendDataAccessRole"
    ),
    JobName="language-detection-example",
)

print(job["JobId"], job["JobStatus"])

With ONE_DOC_PER_LINE, each line is a document; ONE_DOC_PER_FILE is another supported input format. Do not put generated output under an input prefix that the job will scan. This prevents a later job from treating its own results as new source documents.

Choose synchronous or asynchronous processing

For an asynchronous job, use its returned ID to check progress. The call below shows one status check; an application can poll with an interval and stop when the job reaches a terminal state:

status = comprehend.describe_dominant_language_detection_job(
    JobId=job["JobId"]
)
properties = status["DominantLanguageDetectionJobProperties"]
print(properties["JobStatus"])

When the job completes, read the output location from the job properties and retrieve the generated results from S3. A job may fail, so inspect its final status before consuming output. For more on the three processing modes, see AWS's guide to single-document, synchronous batch, and asynchronous analysis.

Use detections in an application

Language detection is useful for choosing a later step, provided the detected language is supported by that step and the prediction is strong enough for your application's policy.

Route a support message with a fallback

Do not assume every detected language has a dedicated queue. Review a low-confidence result or an unsupported language instead of silently sending it to the wrong destination:

def route_message(response, review_threshold):
    languages = response.get("Languages", [])
    if not languages:
        return "manual-review"

    dominant = languages[0]
    if dominant["Score"] < review_threshold:
        return "manual-review"

    queues = {"en": "english-support", "es": "spanish-support"}
    return queues.get(dominant["LanguageCode"], "manual-review")

Set review_threshold from examples representative of your own messages. AWS does not prescribe one score that is safe for every routing task.

Keep batch results aligned with input

For multiple short messages, the batch response uses each result's Index to point to its input position. A successful HTTP response can still contain per-document errors, so handle both lists:

documents = [
    "Please help me update the delivery address for this order.",
    "Necesito cambiar la fecha de entrega de mi pedido.",
]

response = comprehend.batch_detect_dominant_language(TextList=documents)

for result in response["ResultList"]:
    source_text = documents[result["Index"]]
    print(source_text, result["Languages"][0])

for error in response["ErrorList"]:
    source_text = documents[error["Index"]]
    print("Could not analyze:", source_text, error["ErrorCode"])

Keep the original list until you have matched each result or error to its source. For larger S3 collections, use the asynchronous job described above instead of splitting the corpus into a stream of oversized real-time requests.

Choose a Comprehend feature for the next step

Detection tells you which language is dominant; it does not identify names or extract key phrases. If the next step is key-phrase extraction, see our guide to Amazon Comprehend key phrase extraction. If you need domain-specific labels such as a part number or policy identifier, read our guide to custom entity recognition. Check each feature's supported languages before connecting it to a language-detection result.

Next steps

Use DetectDominantLanguage for one document up to 100 KB of UTF-8 text, BatchDetectDominantLanguage for up to 25 documents of 5 KB each, or an S3 job for an asynchronous collection with documents up to 1 MB each. Measure encoded bytes, read the first language result as the dominant prediction, and send low-confidence or unsupported cases to an explicit fallback. Validate language detection with representative text before making it an automatic routing decision.