Language Weaver Developer Quickstart

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

1. Key Differences: Cloud vs Edge

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:

1. GET /api/v2/auth/saml/gen-secret → returns a temporary SECRET

2. Open GET /api/v2/auth/saml/init?secret=SECRET in a browser for user login

3. 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)

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:

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:

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

Output Formats

7. Language Codes Reference

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

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:

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

1. Authenticate

2. Base64-encode the source text

3. Call the quick/synchronous translation endpoint

4. Base64-decode the response

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

Pattern 2: Document Translation with Job Tracking

1. Authenticate

2. Base64-encode the document

3. Submit an async translation job (POST /translations)

4. Poll status (GET /translations/{id}) until state=done

5. Download the result (GET /translations/{id}/download)

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

Pattern 3: Auto-Detect and Translate

1. Authenticate

2. Use the language detection endpoint to identify the source language

3. Look up available language pairs for the detected source → desired target

4. 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.

Further Reading

• Language Weaver Edge API Reference

• Language Weaver Cloud API Reference

• Language Codes (Full List)

• Supported Encodings