Language Weaver Developer Quickstart

Paul Filkin — Thu, 05 Mar 2026 23:22:59 GMT

Current Revision posted to Language Weaver Wiki by Paul Filkin on 3/5/2026 11:22:59 PM

A practical guide for developers integrating with Language Weaver Cloud and Edge translation APIs.

1. Key Differences: Cloud vs Edge

Aspect	Language Weaver Cloud	Language Weaver Edge
Hosting	RWS-hosted SaaS	On-premise / self-hosted
Base URL	`https://api.languageweaver.com/v4`	`https://{controller-host}:8001/api/v2`
Authentication	Client ID + Client Secret → Bearer token	API key (HTTP Basic) or username/password → Bearer token
Language codes	3-letter codes (e.g. `eng`, `fra`)	3-letter codes (e.g. `eng`, `fra`)
Input encoding	Base64	Base64 + URL-encoded
Rate limits	Account-tier dependent	Limited by server capacity

Both platforms share the same fundamental workflow: authenticate → discover language pairs → translate.

2. Authentication

2.1 Language Weaver Cloud

Cloud uses an OAuth-style client credentials flow. You obtain a temporary bearer token using your client ID and client secret (found in the Language Weaver Cloud portal under Account Settings).

Request:

curl -X POST "https://api.languageweaver.com/v4/token" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "tokenType": "Bearer",
  "validityInSeconds": 86400
}

Use the token in subsequent requests:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  "https://api.languageweaver.com/v4/languages"

Tip: Tokens are valid for 24 hours. Cache and reuse them rather than requesting a new token per call. Refresh before expiry.

2.2 Language Weaver Edge

Edge offers two authentication methods:

Option A: API Key (HTTP Basic Auth)

Admin users have a unique API key visible under [Username] > My Account in the Edge Web GUI. Pass it as the HTTP Basic username with an empty password:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/language-pairs"

Note: The trailing colon after the API key is required — it tells curl the password is blank.

Option B: Username / Password → Bearer Token

First, obtain a token:

curl -X POST "https://controller-host:8001/api/v2/auth" \
  -d username="jsmith@example.com" \
  -d password="mypassword"

This returns a JWT token valid for 30 days (configurable). Then use it:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  "https://controller-host:8001/api/v2/language-pairs"

Option C: SAML (Edge only)

For SAML-enabled Edge instances, a three-step browser-assisted flow is available:

GET /api/v2/auth/saml/gen-secret → returns a temporary SECRET
Open GET /api/v2/auth/saml/init?secret=SECRET in a browser for user login
GET /api/v2/auth/saml/wait?secret=SECRET → returns the access token once login completes

2.3 Authentication Errors

Both platforms return 401 Unauthorized when credentials are invalid, expired, or missing.

3. Discovering Available Language Pairs

Before translating, query the available language pairs to find the correct languagePairId.

3.1 Cloud

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.languageweaver.com/v4/accounts/language-pairs"

The response lists available language pairs with their identifiers, source/target languages, and capabilities.

3.2 Edge

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/language-pairs"

Response (abbreviated):

{
  "languagePairs": [
    {
      "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
      "sourceLanguage": "English",
      "sourceLanguageId": "eng",
      "targetLanguage": "French",
      "targetLanguageId": "fra",
      "domain": "Generic",
      "platform": "SRV",
      "technology": "TNMV",
      "version": "8.4.1",
      "linguisticOptions": [
        {
          "id": "Formality",
          "values": ["Informal", "Formal", "Polite"],
          "systemDefault": "Informal"
        }
      ]
    }
  ]
}

Useful Filters (Edge)

Parameter	Description
`sourceLanguageId`	Filter by source language, e.g. `eng`
`targetLanguageId`	Filter by target language, e.g. `fra`
`domain`	Filter by domain, e.g. `Generic`
`mode`	`translation` (default), `installed`, `licensed`, `installedAndLicensed`, `adaptable`
`chains`	`also` (default — includes chains), `only`, or `excluded`

Example — find all English-to-French pairs:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/language-pairs?sourceLanguageId=eng&targetLanguageId=fra"

Language Pair Chains (Edge)

Edge supports chained translation (e.g. Spanish → English → French) when a direct pair isn't available. Chains are identified by the >> separator in their languagePairId:

SpaEng_Generic_SRV_TNMV_8_4_x_2>>EngFra_Generic_SRV_TNMV_8_4_x_1

4. Translating Text

Both platforms require input text to be Base64-encoded.

4.1 Cloud — Synchronous Translation

# Base64-encode your text
echo -n "Hello, how are you?" | base64
# => SGVsbG8sIGhvdyBhcmUgeW91Pw==

curl -X POST "https://api.languageweaver.com/v4/mt/translations/async" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["Hello, how are you?"],
    "sourceLanguageId": "eng",
    "targetLanguageId": "fra",
    "model": "generic",
    "inputFormat": "plain"
  }'

Note: Cloud also supports passing plain text strings directly in the input array for simple text translations, without Base64 encoding. Check the current Cloud API docs for the latest accepted formats.

4.2 Edge — Quick (Synchronous) Translation

Best for small, plain text inputs under 1 KB:

INPUT=$(echo -n "Hello, how are you?" | base64)

curl -X POST "https://controller-host:8001/api/v2/translations/quick" \
  -u "YOUR_API_KEY:" \
  -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
  --data-urlencode input="$INPUT"

Response:

{
  "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
  "translation": "Qm9uam91ciwgY29tbWVudCBhbGxlei12b3VzID8="
}

Decode the result: echo "Qm9uam91ciwgY29tbWVudCBhbGxlei12b3VzID8=" | base64 -d

Auto Language Detection in Translation

To automatically detect the source language, use AutXxx as the language pair ID, where Xxx is the 3-letter target language code:

curl -X POST "https://controller-host:8001/api/v2/translations/quick" \
  -u "YOUR_API_KEY:" \
  -d languagePairId="AutFra" \
  --data-urlencode input="$INPUT"

Note: AutXxx cannot be used with language pair chains.

4.3 Edge — Asynchronous Translation

For larger documents or when you need job tracking:

Step 1 — Submit the job:

curl -X POST "https://controller-host:8001/api/v2/translations" \
  -u "YOUR_API_KEY:" \
  -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
  --data-urlencode input="$INPUT" \
  --data-urlencode inputFormat="text/plain" \
  --data-urlencode title="My translation job"

Response:

{
  "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd"
}

Step 2 — Poll for status:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd"

Check the state and substate fields. The job is complete when state is done and substate is succeeded.

Job states:

State	Substate	Meaning
`preparing`	`created`, `scheduled`, `dispatching`	Job is queued
`inProgress`	`translating`, `preprocessing`, `postprocessing`	Job is running
`done`	`succeeded`	Complete — download results
`done`	`failed`	Error — check `errorMessage`
`done`	`canceled`	Cancelled by user

Step 3 — Download the result:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/download"

Returns Base64-encoded output. Decode it to get your translated content.

4.4 Async Translation Options (Edge)

The async endpoint supports many optional parameters:

Parameter	Description
`inputFormat`	MIME type of input (see §6 below)
`outputFormat`	MIME type of output; defaults to same as input
`encoding`	Character encoding; defaults to `utf-8`
`dictionaryIds`	Comma-separated user dictionary IDs
`linguisticOptions`	E.g. `Formality:Formal`
`generateMetadata`	`true` to produce segment-level metadata
`labels`	Comma-separated labels for categorisation
`pdfConverter`	`Standard` or `Abbyy` for PDF inputs
`includeTextContent`	`true` to also produce a plain-text output

5. Language Detection

5.1 Cloud

curl -X POST "https://api.languageweaver.com/v4/mt/translations/language-detection" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Bonjour, comment allez-vous ?"
  }'

5.2 Edge

Input must be Base64-encoded:

INPUT=$(echo -n "Bonjour, comment allez-vous ?" | base64)

curl -X POST "https://controller-host:8001/api/v2/language-detections" \
  -u "YOUR_API_KEY:" \
  -d input="$INPUT" \
  --data-urlencode inputFormat="text/plain"

Response:

{
  "encoding": "UTF-8",
  "languages": [
    {
      "code": "fra",
      "languageTag": "fr",
      "name": "French",
      "score": 0.95
    }
  ],
  "scripts": [
    {
      "code": "Latn",
      "name": "Latin",
      "percent": 85.2
    },
    {
      "code": "Zyyy",
      "name": "Common",
      "percent": 14.8
    }
  ]
}

The response returns up to 3 detected languages with confidence scores (0–1), plus detected writing scripts with percentage breakdowns.

6. Supported Input/Output Formats (Edge)

Input Formats

Category	MIME Type	Extensions
Plain text	`text/plain`	`.txt`
HTML	`text/html`	`.htm`, `.html`, `.xhtml`
XML	`text/xml`	`.xml`
XLIFF 1.x	`application/x-xliff`	`.xliff`
XLIFF 2.x	`application/xliff`	`.xliff`
TMX	`text/x-tmx`	`.tmx`
PDF	`application/pdf`	`.pdf`
Word (OOXML)	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`.docx`
Excel (OOXML)	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	`.xlsx`
PowerPoint (OOXML)	`application/vnd.openxmlformats-officedocument.presentationml.presentation`	`.pptx`
Word (Legacy)	`application/msword`	`.doc`
RTF	`application/rtf`	`.rtf`
Images	`image/jpeg`, `image/png`, `image/tiff`, `image/gif`	`.jpg`, `.png`, `.tif`, `.gif`
Email	`application/vnd.ms-outlook`, `message/rfc822`	`.msg`, `.eml`
OpenDocument	`application/vnd.oasis.opendocument.text` (etc.)	`.odt`, `.ods`, `.odp`

Output Formats

MIME Type	Description
`default` or empty	Matches input format (with some exceptions for images/PDFs)
`text/plain`	Plain text
`application/x-xliff`	XLIFF v1.2
`application/xliff`	XLIFF v2.1
`text/x-tmx`	TMX

7. Language Codes Reference

Both Cloud and Edge use 3-letter codes. Common examples:

Language	Code	IETF Tag
English	`eng`	`en`
French	`fra`	`fr`
German	`ger`	`de`
Spanish	`spa`	`es`
Chinese (Simplified)	`chi`	`zh-Hans`
Chinese (Traditional)	`cht`	`zh-Hant`
Japanese	`jpn`	`ja`
Korean	`kor`	`ko`
Arabic	`ara`	`ar`
Portuguese	`por`	`pt`
Portuguese (Brazil)	`ptb`	`pt-BR`
Russian	`rus`	`ru`
Dutch	`dut`	`nl`
Italian	`ita`	`it`
Polish	`pol`	`pl`
Turkish	`tur`	`tr`
Swedish	`swe`	`sv`
Danish	`dan`	`da`
Norwegian	`nor`	`no`
Finnish	`fin`	`fi`
Czech	`cze`	`cs`
Hungarian	`hun`	`hu`
Romanian	`rum`	`ro`
Ukrainian	`ukr`	`uk`
Hindi	`hin`	`hi`
Thai	`tha`	`th`
Vietnamese	`vie`	`vi`
Indonesian	`ind`	`id`

For the full list of 100+ languages, see the Edge language codes reference or query the Cloud API's languages endpoint.

8. Error Handling

Both platforms use standard HTTP status codes:

Code	Meaning
`200`	Success
`400`	Bad request — invalid or missing parameters
`401`	Unauthorised — invalid, expired, or missing credentials
`403`	Forbidden — insufficient privileges
`404`	Not found — endpoint doesn't exist
`500`	Internal server error

Error Response Format (Edge)

{
  "error": {
    "code": 400,
    "message": "user could not be added",
    "details": "the specified user already exists: jsmith@example.com"
  }
}

The details field is optional and provides additional context when available.

9. Common Integration Patterns

Pattern 1: Simple Text Translation

Authenticate
Base64-encode the source text
Call the quick/synchronous translation endpoint
Base64-decode the response

Best for: chat integrations, real-time translation widgets, short text.

Pattern 2: Document Translation with Job Tracking

Authenticate
Base64-encode the document
Submit an async translation job (POST /translations)
Poll status (GET /translations/{id}) until state=done
Download the result (GET /translations/{id}/download)

Best for: file-based workflows, batch processing, large documents.

Pattern 3: Auto-Detect and Translate

Authenticate
Use the language detection endpoint to identify the source language
Look up available language pairs for the detected source → desired target
Translate using the appropriate language pair

Alternatively, use AutXxx as the language pair ID to combine detection and translation in a single call (Edge only).

Pattern 4: Batch Operations (Edge)

Use the bulk download endpoint to retrieve multiple completed translations at once:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/translations/download-archive?translationIds=ID1,ID2,ID3"

Returns a zip file containing all requested translations. Total output size is limited to 1 GB.

10. Tips and Gotchas

Always Base64-encode input text for Edge. Forgetting this is the most common integration mistake.
URL-encode parameters when using form data with curl (--data-urlencode).
Cache your auth tokens. Cloud tokens last 24 hours; Edge tokens last 30 days. Don't authenticate on every request.
Check linguistic options. Some language pairs support formality settings (Formal, Informal, Polite). Query the language pairs endpoint to discover what's available.
Edge timestamps use the format yyyy-MM-dd HH:mm:ss.SSS (e.g. 2024-01-02 15:04:05.999999999Z).
Character encoding defaults to UTF-8 on both platforms. Specify explicitly if your content uses a different encoding.
Language pair chains (Edge) enable translation between language pairs that don't have a direct model, by routing through a pivot language (usually English).
Quality estimation is available in async translation results on Edge, giving a breakdown of good/adequate/poor percentages.

Quick Start

Paul Filkin — Thu, 05 Mar 2026 23:22:02 GMT

Revision 1 posted to Language Weaver Wiki by Paul Filkin on 3/5/2026 11:22:02 PM

Language Weaver Developer Quickstart

A practical guide for developers integrating with Language Weaver Cloud and Edge translation APIs.

1. Key Differences: Cloud vs Edge

Aspect	Language Weaver Cloud	Language Weaver Edge
Hosting	RWS-hosted SaaS	On-premise / self-hosted
Base URL	`https://api.languageweaver.com/v4`	`https://{controller-host}:8001/api/v2`
Authentication	Client ID + Client Secret → Bearer token	API key (HTTP Basic) or username/password → Bearer token
Language codes	3-letter codes (e.g. `eng`, `fra`)	3-letter codes (e.g. `eng`, `fra`)
Input encoding	Base64	Base64 + URL-encoded
Rate limits	Account-tier dependent	Limited by server capacity

Both platforms share the same fundamental workflow: authenticate → discover language pairs → translate.

2. Authentication

2.1 Language Weaver Cloud

Request:

curl -X POST "https://api.languageweaver.com/v4/token" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "tokenType": "Bearer",
  "validityInSeconds": 86400
}

Use the token in subsequent requests:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  "https://api.languageweaver.com/v4/languages"

Tip: Tokens are valid for 24 hours. Cache and reuse them rather than requesting a new token per call. Refresh before expiry.

2.2 Language Weaver Edge

Edge offers two authentication methods:

Option A: API Key (HTTP Basic Auth)

Admin users have a unique API key visible under [Username] > My Account in the Edge Web GUI. Pass it as the HTTP Basic username with an empty password:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/language-pairs"

Note: The trailing colon after the API key is required — it tells curl the password is blank.

Option B: Username / Password → Bearer Token

First, obtain a token:

curl -X POST "https://controller-host:8001/api/v2/auth" \
  -d username="jsmith@example.com" \
  -d password="mypassword"

This returns a JWT token valid for 30 days (configurable). Then use it:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  "https://controller-host:8001/api/v2/language-pairs"

Option C: SAML (Edge only)

For SAML-enabled Edge instances, a three-step browser-assisted flow is available:

GET /api/v2/auth/saml/gen-secret → returns a temporary SECRET
Open GET /api/v2/auth/saml/init?secret=SECRET in a browser for user login
GET /api/v2/auth/saml/wait?secret=SECRET → returns the access token once login completes

2.3 Authentication Errors

Both platforms return 401 Unauthorized when credentials are invalid, expired, or missing.

3. Discovering Available Language Pairs

Before translating, query the available language pairs to find the correct languagePairId.

3.1 Cloud

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.languageweaver.com/v4/accounts/language-pairs"

The response lists available language pairs with their identifiers, source/target languages, and capabilities.

3.2 Edge

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/language-pairs"

Response (abbreviated):

{
  "languagePairs": [
    {
      "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
      "sourceLanguage": "English",
      "sourceLanguageId": "eng",
      "targetLanguage": "French",
      "targetLanguageId": "fra",
      "domain": "Generic",
      "platform": "SRV",
      "technology": "TNMV",
      "version": "8.4.1",
      "linguisticOptions": [
        {
          "id": "Formality",
          "values": ["Informal", "Formal", "Polite"],
          "systemDefault": "Informal"
        }
      ]
    }
  ]
}

Useful Filters (Edge)

Parameter	Description
`sourceLanguageId`	Filter by source language, e.g. `eng`
`targetLanguageId`	Filter by target language, e.g. `fra`
`domain`	Filter by domain, e.g. `Generic`
`mode`	`translation` (default), `installed`, `licensed`, `installedAndLicensed`, `adaptable`
`chains`	`also` (default — includes chains), `only`, or `excluded`

Example — find all English-to-French pairs:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/language-pairs?sourceLanguageId=eng&targetLanguageId=fra"

Language Pair Chains (Edge)

Edge supports chained translation (e.g. Spanish → English → French) when a direct pair isn't available. Chains are identified by the >> separator in their languagePairId:

SpaEng_Generic_SRV_TNMV_8_4_x_2>>EngFra_Generic_SRV_TNMV_8_4_x_1

4. Translating Text

Both platforms require input text to be Base64-encoded.

4.1 Cloud — Synchronous Translation

# Base64-encode your text
echo -n "Hello, how are you?" | base64
# => SGVsbG8sIGhvdyBhcmUgeW91Pw==

curl -X POST "https://api.languageweaver.com/v4/mt/translations/async" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["Hello, how are you?"],
    "sourceLanguageId": "eng",
    "targetLanguageId": "fra",
    "model": "generic",
    "inputFormat": "plain"
  }'

Note: Cloud also supports passing plain text strings directly in the input array for simple text translations, without Base64 encoding. Check the current Cloud API docs for the latest accepted formats.

4.2 Edge — Quick (Synchronous) Translation

Best for small, plain text inputs under 1 KB:

INPUT=$(echo -n "Hello, how are you?" | base64)

curl -X POST "https://controller-host:8001/api/v2/translations/quick" \
  -u "YOUR_API_KEY:" \
  -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
  --data-urlencode input="$INPUT"

Response:

{
  "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
  "translation": "Qm9uam91ciwgY29tbWVudCBhbGxlei12b3VzID8="
}

Decode the result: echo "Qm9uam91ciwgY29tbWVudCBhbGxlei12b3VzID8=" | base64 -d

Auto Language Detection in Translation

To automatically detect the source language, use AutXxx as the language pair ID, where Xxx is the 3-letter target language code:

curl -X POST "https://controller-host:8001/api/v2/translations/quick" \
  -u "YOUR_API_KEY:" \
  -d languagePairId="AutFra" \
  --data-urlencode input="$INPUT"

Note: AutXxx cannot be used with language pair chains.

4.3 Edge — Asynchronous Translation

For larger documents or when you need job tracking:

Step 1 — Submit the job:

curl -X POST "https://controller-host:8001/api/v2/translations" \
  -u "YOUR_API_KEY:" \
  -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
  --data-urlencode input="$INPUT" \
  --data-urlencode inputFormat="text/plain" \
  --data-urlencode title="My translation job"

Response:

{
  "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd"
}

Step 2 — Poll for status:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd"

Check the state and substate fields. The job is complete when state is done and substate is succeeded.

Job states:

State	Substate	Meaning
`preparing`	`created`, `scheduled`, `dispatching`	Job is queued
`inProgress`	`translating`, `preprocessing`, `postprocessing`	Job is running
`done`	`succeeded`	Complete — download results
`done`	`failed`	Error — check `errorMessage`
`done`	`canceled`	Cancelled by user

Step 3 — Download the result:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/download"

Returns Base64-encoded output. Decode it to get your translated content.

4.4 Async Translation Options (Edge)

The async endpoint supports many optional parameters:

Parameter	Description
`inputFormat`	MIME type of input (see §6 below)
`outputFormat`	MIME type of output; defaults to same as input
`encoding`	Character encoding; defaults to `utf-8`
`dictionaryIds`	Comma-separated user dictionary IDs
`linguisticOptions`	E.g. `Formality:Formal`
`generateMetadata`	`true` to produce segment-level metadata
`labels`	Comma-separated labels for categorisation
`pdfConverter`	`Standard` or `Abbyy` for PDF inputs
`includeTextContent`	`true` to also produce a plain-text output

5. Language Detection

5.1 Cloud

curl -X POST "https://api.languageweaver.com/v4/mt/translations/language-detection" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Bonjour, comment allez-vous ?"
  }'

5.2 Edge

Input must be Base64-encoded:

INPUT=$(echo -n "Bonjour, comment allez-vous ?" | base64)

curl -X POST "https://controller-host:8001/api/v2/language-detections" \
  -u "YOUR_API_KEY:" \
  -d input="$INPUT" \
  --data-urlencode inputFormat="text/plain"

Response:

{
  "encoding": "UTF-8",
  "languages": [
    {
      "code": "fra",
      "languageTag": "fr",
      "name": "French",
      "score": 0.95
    }
  ],
  "scripts": [
    {
      "code": "Latn",
      "name": "Latin",
      "percent": 85.2
    },
    {
      "code": "Zyyy",
      "name": "Common",
      "percent": 14.8
    }
  ]
}

The response returns up to 3 detected languages with confidence scores (0–1), plus detected writing scripts with percentage breakdowns.

6. Supported Input/Output Formats (Edge)

Input Formats

Category	MIME Type	Extensions
Plain text	`text/plain`	`.txt`
HTML	`text/html`	`.htm`, `.html`, `.xhtml`
XML	`text/xml`	`.xml`
XLIFF 1.x	`application/x-xliff`	`.xliff`
XLIFF 2.x	`application/xliff`	`.xliff`
TMX	`text/x-tmx`	`.tmx`
PDF	`application/pdf`	`.pdf`
Word (OOXML)	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`.docx`
Excel (OOXML)	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	`.xlsx`
PowerPoint (OOXML)	`application/vnd.openxmlformats-officedocument.presentationml.presentation`	`.pptx`
Word (Legacy)	`application/msword`	`.doc`
RTF	`application/rtf`	`.rtf`
Images	`image/jpeg`, `image/png`, `image/tiff`, `image/gif`	`.jpg`, `.png`, `.tif`, `.gif`
Email	`application/vnd.ms-outlook`, `message/rfc822`	`.msg`, `.eml`
OpenDocument	`application/vnd.oasis.opendocument.text` (etc.)	`.odt`, `.ods`, `.odp`

Output Formats

MIME Type	Description
`default` or empty	Matches input format (with some exceptions for images/PDFs)
`text/plain`	Plain text
`application/x-xliff`	XLIFF v1.2
`application/xliff`	XLIFF v2.1
`text/x-tmx`	TMX

7. Language Codes Reference

Both Cloud and Edge use 3-letter codes. Common examples:

Language	Code	IETF Tag
English	`eng`	`en`
French	`fra`	`fr`
German	`ger`	`de`
Spanish	`spa`	`es`
Chinese (Simplified)	`chi`	`zh-Hans`
Chinese (Traditional)	`cht`	`zh-Hant`
Japanese	`jpn`	`ja`
Korean	`kor`	`ko`
Arabic	`ara`	`ar`
Portuguese	`por`	`pt`
Portuguese (Brazil)	`ptb`	`pt-BR`
Russian	`rus`	`ru`
Dutch	`dut`	`nl`
Italian	`ita`	`it`
Polish	`pol`	`pl`
Turkish	`tur`	`tr`
Swedish	`swe`	`sv`
Danish	`dan`	`da`
Norwegian	`nor`	`no`
Finnish	`fin`	`fi`
Czech	`cze`	`cs`
Hungarian	`hun`	`hu`
Romanian	`rum`	`ro`
Ukrainian	`ukr`	`uk`
Hindi	`hin`	`hi`
Thai	`tha`	`th`
Vietnamese	`vie`	`vi`
Indonesian	`ind`	`id`

For the full list of 100+ languages, see the Edge language codes reference or query the Cloud API's languages endpoint.

8. Error Handling

Both platforms use standard HTTP status codes:

Code	Meaning
`200`	Success
`400`	Bad request — invalid or missing parameters
`401`	Unauthorised — invalid, expired, or missing credentials
`403`	Forbidden — insufficient privileges
`404`	Not found — endpoint doesn't exist
`500`	Internal server error

Error Response Format (Edge)

{
  "error": {
    "code": 400,
    "message": "user could not be added",
    "details": "the specified user already exists: jsmith@example.com"
  }
}

The details field is optional and provides additional context when available.

9. Common Integration Patterns

Pattern 1: Simple Text Translation

Authenticate
Base64-encode the source text
Call the quick/synchronous translation endpoint
Base64-decode the response

Best for: chat integrations, real-time translation widgets, short text.

Pattern 2: Document Translation with Job Tracking

Authenticate
Base64-encode the document
Submit an async translation job (POST /translations)
Poll status (GET /translations/{id}) until state=done
Download the result (GET /translations/{id}/download)

Best for: file-based workflows, batch processing, large documents.

Pattern 3: Auto-Detect and Translate

Authenticate
Use the language detection endpoint to identify the source language
Look up available language pairs for the detected source → desired target
Translate using the appropriate language pair

Alternatively, use AutXxx as the language pair ID to combine detection and translation in a single call (Edge only).

Pattern 4: Batch Operations (Edge)

Use the bulk download endpoint to retrieve multiple completed translations at once:

curl -u "YOUR_API_KEY:" \
  "https://controller-host:8001/api/v2/translations/download-archive?translationIds=ID1,ID2,ID3"

Returns a zip file containing all requested translations. Total output size is limited to 1 GB.

10. Tips and Gotchas

Always Base64-encode input text for Edge. Forgetting this is the most common integration mistake.
URL-encode parameters when using form data with curl (--data-urlencode).
Cache your auth tokens. Cloud tokens last 24 hours; Edge tokens last 30 days. Don't authenticate on every request.
Check linguistic options. Some language pairs support formality settings (Formal, Informal, Polite). Query the language pairs endpoint to discover what's available.
Edge timestamps use the format yyyy-MM-dd HH:mm:ss.SSS (e.g. 2024-01-02 15:04:05.999999999Z).
Character encoding defaults to UTF-8 on both platforms. Specify explicitly if your content uses a different encoding.
Language pair chains (Edge) enable translation between language pairs that don't have a direct model, by routing through a pivot language (usually English).
Quality estimation is available in async translation results on Edge, giving a breakdown of good/adequate/poor percentages.

Language Weaver Developer Quickstart

Language Weaver Developer Quickstart

1. Key Differences: Cloud vs Edge

2. Authentication

2.1 Language Weaver Cloud

2.2 Language Weaver Edge

Option A: API Key (HTTP Basic Auth)

Option B: Username / Password → Bearer Token

Option C: SAML (Edge only)

2.3 Authentication Errors

3. Discovering Available Language Pairs

3.1 Cloud

3.2 Edge

Useful Filters (Edge)

Language Pair Chains (Edge)

4. Translating Text

4.1 Cloud — Synchronous Translation

4.2 Edge — Quick (Synchronous) Translation

Auto Language Detection in Translation

4.3 Edge — Asynchronous Translation

4.4 Async Translation Options (Edge)

5. Language Detection

5.1 Cloud

5.2 Edge

6. Supported Input/Output Formats (Edge)

Input Formats

Output Formats

7. Language Codes Reference

8. Error Handling

Error Response Format (Edge)

9. Common Integration Patterns

Pattern 1: Simple Text Translation

Pattern 2: Document Translation with Job Tracking

Pattern 3: Auto-Detect and Translate

Pattern 4: Batch Operations (Edge)

10. Tips and Gotchas

Further Reading

Quick Start

Language Weaver Developer Quickstart

1. Key Differences: Cloud vs Edge

2. Authentication

2.1 Language Weaver Cloud

2.2 Language Weaver Edge

Option A: API Key (HTTP Basic Auth)

Option B: Username / Password → Bearer Token

Option C: SAML (Edge only)

2.3 Authentication Errors

3. Discovering Available Language Pairs

3.1 Cloud

3.2 Edge

Useful Filters (Edge)

Language Pair Chains (Edge)

4. Translating Text

4.1 Cloud — Synchronous Translation

4.2 Edge — Quick (Synchronous) Translation

Auto Language Detection in Translation

4.3 Edge — Asynchronous Translation

4.4 Async Translation Options (Edge)

5. Language Detection

5.1 Cloud

5.2 Edge

6. Supported Input/Output Formats (Edge)

Input Formats

Output Formats

7. Language Codes Reference

8. Error Handling

Error Response Format (Edge)

9. Common Integration Patterns

Pattern 1: Simple Text Translation

Pattern 2: Document Translation with Job Tracking

Pattern 3: Auto-Detect and Translate

Pattern 4: Batch Operations (Edge)

10. Tips and Gotchas

Further Reading