Fluency Evaluation

Evaluate how naturally and idiomatic a translation reads in the target language across three complementary methods: single-item dimension scoring, batch processing, and MQM-style error evaluation.

Evaluate Fluency (Dimension-Based)

Evaluates the fluency of a translation across five linguistic dimensions and provides improvement feedback.

Endpoint: POST /translation/fluency-score

Caution

POST /translation/fluency is a deprecated alias for this endpoint and will be removed in a future release. New integrations should call /translation/fluency-score directly.

Request Body

Sent as JSON.

Field	Type	Required	Description
sourceLang	string	yes	Source language code
targetLang	string	yes	Target language code
sourceText	string	yes	The original text in the source language
translatedText	string	yes	The translated text to evaluate

Note

Billed as a flat 10 words per call, regardless of text length.

Response

Success Response (200)

{
  "status": "ok",
  "timestamp": "2025-01-12T22:31:48.856Z",
  "data": {
    "fluency": 6.4,
    "idiomatic": 7,
    "collocational": 6,
    "discourse": 7,
    "pragmatic": 6,
    "calque": 6,
    "issue_type": "collocation",
    "severity": "minor",
    "problematic_phrase": "macht Sinn",
    "suggested_fix": "ergibt Sinn",
    "main_issue": "The phrase is a calque from English and unnatural in German."
  }
}

fluency is the mean of the five dimensions (idiomatic, collocational, discourse, pragmatic, calque), each scored 1-10. issue_type is one of calque, collocation, idiom_literal, discourse_marker, register_mismatch, false_friend, or none. severity is one of critical, major, minor, or cosmetic.

Example Request

bash

curl -X POST "https://platform.algebras.ai/api/v1/translation/fluency-score" \
     -H "X-Api-Key: your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceLang": "en",
           "targetLang": "de",
           "sourceText": "That makes sense.",
           "translatedText": "Das macht Sinn."
         }'

python

import requests

url = "https://platform.algebras.ai/api/v1/translation/fluency-score"
headers = {
    "X-Api-Key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "sourceLang": "en",
    "targetLang": "de",
    "sourceText": "That makes sense.",
    "translatedText": "Das macht Sinn."
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()["data"]
    print(f"Fluency: {result['fluency']}, issue: {result['issue_type']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

nodejs

const url = "https://platform.algebras.ai/api/v1/translation/fluency-score";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "X-Api-Key": "your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceLang: "en",
    targetLang: "de",
    sourceText: "That makes sense.",
    translatedText: "Das macht Sinn.",
  }),
});

if (response.ok) {
  const result = await response.json();
  console.log("Fluency:", result.data.fluency, "issue:", result.data.issue_type);
} else {
  const error = await response.json();
  console.error("Error:", response.status, error);
}

go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "https://platform.algebras.ai/api/v1/translation/fluency-score"

    payload := map[string]interface{}{
        "sourceLang":     "en",
        "targetLang":     "de",
        "sourceText":     "That makes sense.",
        "translatedText": "Das macht Sinn.",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("X-Api-Key", "your_api_key_here")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    if resp.StatusCode == 200 {
        var result map[string]interface{}
        json.Unmarshal(body, &result)
        data := result["data"].(map[string]interface{})
        fmt.Println("Fluency:", data["fluency"], "issue:", data["issue_type"])
    } else {
        fmt.Printf("Error: %d\n", resp.StatusCode)
        fmt.Println(string(body))
    }
}

Evaluate Fluency (Batch)

Evaluates the fluency of up to 20 source/translation pairs concurrently. Individual item failures do not abort the whole batch.

Endpoint: POST /translation/fluency-batch

Request Body

Sent as JSON.

Field	Type	Required	Description
sourceLang	string	yes	Source language code
targetLang	string	yes	Target language code
items	array of objects	yes	Pairs to evaluate (max 20)
items[].sourceText	string	yes	The original text in the source language
items[].translatedText	string	yes	The translated text to evaluate

Note

Billed as a flat 10 words per item in the batch.

Response

Success Response (200)

{
  "status": "ok",
  "timestamp": "2025-01-12T22:31:48.856Z",
  "data": {
    "evaluations": [
      {
        "index": 0,
        "fluency": 9.2,
        "idiomatic": 9,
        "collocational": 9,
        "discourse": 9,
        "pragmatic": 10,
        "calque": 9,
        "issue_type": "none",
        "severity": null,
        "problematic_phrase": null,
        "suggested_fix": null,
        "main_issue": null
      },
      {
        "index": 1,
        "fluency": 6.4,
        "idiomatic": 7,
        "collocational": 6,
        "discourse": 7,
        "pragmatic": 6,
        "calque": 6,
        "issue_type": "collocation",
        "severity": "minor",
        "problematic_phrase": "macht Sinn",
        "suggested_fix": "ergibt Sinn",
        "main_issue": "The phrase is a calque from English and unnatural in German."
      }
    ],
    "batch_summary": {
      "total": 2,
      "successful": 2,
      "failed": 0
    }
  }
}

Note

A failed item carries error and status_code instead of the score fields, with fluency and the rest left null.

Example Request

bash

curl -X POST "https://platform.algebras.ai/api/v1/translation/fluency-batch" \
     -H "X-Api-Key: your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceLang": "en",
           "targetLang": "de",
           "items": [
             { "sourceText": "Hello, World!", "translatedText": "Hallo, Welt!" },
             { "sourceText": "That makes sense.", "translatedText": "Das macht Sinn." }
           ]
         }'

python

import requests

url = "https://platform.algebras.ai/api/v1/translation/fluency-batch"
headers = {
    "X-Api-Key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "sourceLang": "en",
    "targetLang": "de",
    "items": [
        {"sourceText": "Hello, World!", "translatedText": "Hallo, Welt!"},
        {"sourceText": "That makes sense.", "translatedText": "Das macht Sinn."}
    ]
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    for evaluation in response.json()["data"]["evaluations"]:
        print(evaluation["index"], evaluation["fluency"])
else:
    print(f"Error: {response.status_code}")
    print(response.json())

nodejs

const url = "https://platform.algebras.ai/api/v1/translation/fluency-batch";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "X-Api-Key": "your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceLang: "en",
    targetLang: "de",
    items: [
      { sourceText: "Hello, World!", translatedText: "Hallo, Welt!" },
      { sourceText: "That makes sense.", translatedText: "Das macht Sinn." },
    ],
  }),
});

if (response.ok) {
  const result = await response.json();
  result.data.evaluations.forEach((e) => console.log(e.index, e.fluency));
} else {
  const error = await response.json();
  console.error("Error:", response.status, error);
}

go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "https://platform.algebras.ai/api/v1/translation/fluency-batch"

    payload := map[string]interface{}{
        "sourceLang": "en",
        "targetLang": "de",
        "items": []map[string]string{
            {"sourceText": "Hello, World!", "translatedText": "Hallo, Welt!"},
            {"sourceText": "That makes sense.", "translatedText": "Das macht Sinn."},
        },
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("X-Api-Key", "your_api_key_here")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    if resp.StatusCode == 200 {
        var result map[string]interface{}
        json.Unmarshal(body, &result)
        data := result["data"].(map[string]interface{})
        evaluations := data["evaluations"].([]interface{})
        for _, e := range evaluations {
            item := e.(map[string]interface{})
            fmt.Println(item["index"], item["fluency"])
        }
    } else {
        fmt.Printf("Error: %d\n", resp.StatusCode)
        fmt.Println(string(body))
    }
}

Evaluate Fluency (MQM-Style)

Evaluates translation naturalness using Multidimensional Quality Metrics (MQM) style, scoring on a 0–100 scale where errors are penalized: critical errors subtract 25, major errors subtract 5, and minor errors subtract 1. Returns a detailed breakdown of all errors found across five linguistic dimensions.

Endpoint: POST /translation/fluency-mqm

Request Body

Sent as JSON.

Field	Type	Required	Description
sourceLang	string	yes	Source language code
targetLang	string	yes	Target language code
sourceText	string	yes	The original text in the source language
translatedText	string	yes	The translated text to evaluate

Note

Billed as a flat 10 words per call, same as fluency-score.

Response

Success Response (200)

{
  "status": "ok",
  "timestamp": "2025-01-12T22:31:48.856Z",
  "data": {
    "score": 95,
    "idiomatic": 100,
    "collocational": 100,
    "discourse": 100,
    "pragmatic": 100,
    "calque": 95,
    "errors": [
      {
        "dimension": "calque",
        "severity": "major",
        "phrase": "macht Sinn",
        "explanation": "Literal mirror of 'makes sense'; German prefers 'ergibt Sinn'."
      }
    ],
    "main_issue": "The phrase 'macht Sinn' is a calque from English.",
    "issue_type": "calque",
    "severity": "major"
  }
}

score ranges from 0 (many errors) to 100 (no errors). Each dimension (idiomatic, collocational, discourse, pragmatic, calque) shows the score for that category alone: 100 minus penalties for errors in that dimension. errors is a list of all issues found, each with dimension, severity (critical, major, or minor), the problematic phrase, and an explanation. issue_type is one of calque, collocation, idiom_literal, discourse_marker, register_mismatch, false_friend, or none.

Note

Unlike POST /translation/fluency-score, MQM evaluation returns all errors found rather than just the most critical one.

Example Request

bash

curl -X POST "https://platform.algebras.ai/api/v1/translation/fluency-mqm" \
     -H "X-Api-Key: your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceLang": "en",
           "targetLang": "de",
           "sourceText": "That makes sense.",
           "translatedText": "Das macht Sinn."
         }'

python

import requests

url = "https://platform.algebras.ai/api/v1/translation/fluency-mqm"
headers = {
    "X-Api-Key": "your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "sourceLang": "en",
    "targetLang": "de",
    "sourceText": "That makes sense.",
    "translatedText": "Das macht Sinn."
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()["data"]
    print(f"Score: {result['score']}, main issue: {result['main_issue']}")
    for error in result['errors']:
        print(f"  {error['severity']} ({error['dimension']}): {error['phrase']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

nodejs

const url = "https://platform.algebras.ai/api/v1/translation/fluency-mqm";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "X-Api-Key": "your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceLang: "en",
    targetLang: "de",
    sourceText: "That makes sense.",
    translatedText: "Das macht Sinn.",
  }),
});

if (response.ok) {
  const result = await response.json();
  console.log("Score:", result.data.score, "main issue:", result.data.main_issue);
  result.data.errors.forEach((error) => {
    console.log(`  ${error.severity} (${error.dimension}): ${error.phrase}`);
  });
} else {
  const error = await response.json();
  console.error("Error:", response.status, error);
}

go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    url := "https://platform.algebras.ai/api/v1/translation/fluency-mqm"

    payload := map[string]interface{}{
        "sourceLang":     "en",
        "targetLang":     "de",
        "sourceText":     "That makes sense.",
        "translatedText": "Das macht Sinn.",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("X-Api-Key", "your_api_key_here")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    if resp.StatusCode == 200 {
        var result map[string]interface{}
        json.Unmarshal(body, &result)
        data := result["data"].(map[string]interface{})
        fmt.Println("Score:", data["score"], "main issue:", data["main_issue"])
        if errors, ok := data["errors"].([]interface{}); ok {
            for _, e := range errors {
                error := e.(map[string]interface{})
                fmt.Printf("  %s (%s): %s\n", error["severity"], error["dimension"], error["phrase"])
            }
        }
    } else {
        fmt.Printf("Error: %d\n", resp.StatusCode)
        fmt.Println(string(body))
    }
}