Skip to main content

Translation API for Node.js

This guide shows you how to use the Langbly translation API in Node.js and TypeScript. Langbly is Google Translate v2 compatible and charges $5 per 1M additional input characters—a 75% lower usage rate than Google Cloud Translation Basic's published $20 rate.

Installation​

npm install langbly
# or
yarn add langbly
# or
pnpm add langbly

Quick Start​

import { Langbly } from 'langbly';

const client = new Langbly({ apiKey: 'your-api-key-here' });

const result = await client.translate({
  q: 'Hello, how are you?',
  target: 'nl',
});

console.log(result.translatedText);
// Output: "Hallo, hoe gaat het met je?"

Get Your API Key​

  1. Sign up at langbly.com/signup and add payment details to activate API access
  2. Create an API key in your dashboard
  3. The first 500K input characters each month are included after activation

Translate Text​

Basic Translation​

import { Langbly } from 'langbly';

const client = new Langbly({ apiKey: 'your-api-key-here' });

// English to Dutch
const result = await client.translate({ q: 'Good morning!', target: 'nl' });
console.log(result.translatedText); // "Goedemorgen!"

// English to German
const result2 = await client.translate({ q: 'Good morning!', target: 'de' });
console.log(result2.translatedText); // "Guten Morgen!"

With Source Language​

const result = await client.translate({
  q: 'Bonjour le monde',
  target: 'en',
  source: 'fr',
});
console.log(result.translatedText); // "Hello world"

HTML Translation​

const result = await client.translate({
  q: '<p>Welcome to our <strong>website</strong></p>',
  target: 'nl',
  format: 'html',
});
console.log(result.translatedText);
// "<p>Welkom op onze <strong>website</strong></p>"

Batch Translation​

Translate multiple strings in a single API call:

const results = await client.translate({
  q: ['Hello', 'Goodbye', 'Thank you'],
  target: 'nl',
});

results.forEach((r) => console.log(r.translatedText));
// "Hallo"
// "Tot ziens"
// "Dank je"

Error Handling​

The SDK provides typed error classes:

import { Langbly, AuthenticationError, RateLimitError } from 'langbly';

const client = new Langbly({ apiKey: 'your-api-key-here' });

try {
  const result = await client.translate({ q: 'Hello', target: 'nl' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else {
    console.error('Error:', error);
  }
}

Auto-Retry​

The SDK automatically retries on 429 and 5xx errors with exponential backoff:

const client = new Langbly({
  apiKey: 'your-api-key-here',
  maxRetries: 3, // default
});

Integration Examples​

Express.js Middleware​

import express from 'express';
import { Langbly } from 'langbly';

const app = express();
const langbly = new Langbly({ apiKey: process.env.LANGBLY_API_KEY! });

app.post('/api/translate', express.json(), async (req, res) => {
  const { text, target, source } = req.body;

  const result = await langbly.translate({
    q: text,
    target,
    source,
  });

  res.json({ translation: result.translatedText });
});

Next.js API Route​

// app/api/translate/route.ts
import { Langbly } from 'langbly';
import { NextRequest, NextResponse } from 'next/server';

const langbly = new Langbly({ apiKey: process.env.LANGBLY_API_KEY! });

export async function POST(request: NextRequest) {
  const { text, target } = await request.json();

  const result = await langbly.translate({
    q: text,
    target,
  });

  return NextResponse.json({ translation: result.translatedText });
}

Translate i18n JSON File​

import { readFileSync, writeFileSync } from 'fs';
import { Langbly } from 'langbly';

const client = new Langbly({ apiKey: process.env.LANGBLY_API_KEY! });

async function translateI18n(inputFile: string, outputFile: string, targetLang: string) {
  const source = JSON.parse(readFileSync(inputFile, 'utf-8'));
  const keys = Object.keys(source);
  const values = Object.values(source) as string[];

  const results = await client.translate({ q: values, target: targetLang });

  const translated: Record<string, string> = {};
  keys.forEach((key, i) => {
    translated[key] = results[i].translatedText;
  });

  writeFileSync(outputFile, JSON.stringify(translated, null, 2));
  console.log(`Translated ${keys.length} keys to ${targetLang}`);
}

// Usage
await translateI18n('locales/en.json', 'locales/nl.json', 'nl');

Environment Variables​

export LANGBLY_API_KEY=your-api-key-here
// Automatically reads LANGBLY_API_KEY from environment
const client = new Langbly();

TypeScript Support​

The SDK is written in TypeScript with full type definitions:

import { Langbly, TranslateResult, LangblyError } from 'langbly';

const client = new Langbly({ apiKey: 'your-key' });

// TranslateResult is fully typed
const result: TranslateResult = await client.translate({
  q: 'Hello',
  target: 'nl',
});

Google Translate Migration​

// Before (Google Translate)
// import { v2 } from '@google-cloud/translate';
// const client = new v2.Translate({ key: 'GOOGLE_KEY' });
// const [translation] = await client.translate('Hello', 'nl');

// After (Langbly) - same concept, simpler API
import { Langbly } from 'langbly';
const client = new Langbly({ apiKey: 'your-key' });
const result = await client.translate({ q: 'Hello', target: 'nl' });
console.log(result.translatedText);

Next Steps​