Babely SDK Documentation

The Babely SDK provides a simple and powerful way to integrate Babely's translation capabilities into your applications.

Installation

typescript
npm install @babely/sdk

Quick Start

typescript
import { Babely } from "@babely/sdk";

async function run() {
  const babely = new Babely({
    apiKey: process.env.BABELY_API_KEY,
  });

  const result = await babely.translate({
    sourceText: "Hello, world!",
    sourceLocale: "en",
    targetLocale: "sv",
    projectId: process.env.BABELY_PROJECT_ID,
  });

  console.log(result.translatedText);
}

run();

Authentication

The SDK requires an API key to authenticate requests. Your API key should start with org_. You can obtain an API key from your Babely dashboard.

typescript
const babely = new Babely({
  apiKey: process.env.BABELY_API_KEY,
});

Parameters:

The translate method accepts an object with the following properties:

  • ◇projectId (string, required): The ID of your Babely project
  • ◇sourceLocale (string, required): The locale code of the source text
  • ◇targetLocale (string, required): The locale code to translate into
  • ◇sourceText (string, required): The text to translate
  • ◇format (string, optional): The format of the source text. Defaults to "string"
  • ◇cache (boolean, optional): Whether to use cached translations. Defaults to true

Supported Formats:

  • ◇string: Plain text
  • ◇json: JSON files
  • ◇yaml: YAML files
  • ◇properties: Java properties files
  • ◇android: Android resource files
  • ◇xcode-strings: iOS Strings files
  • ◇xcode-stringsdict: iOS Stringsdict files
  • ◇xcode-xcstrings: iOS XCStrings files
  • ◇md: Markdown files
  • ◇mdx: MDX files
  • ◇html: HTML files
  • ◇js: JavaScript files
  • ◇ts: TypeScript files
  • ◇po: Gettext PO files
  • ◇xliff: XLIFF files
  • ◇csv: CSV files
  • ◇xml: XML files
  • ◇arb: ARB (Application Resource Bundle) files
  • ◇ftl: Fluent FTL files
  • ◇php: PHP files

Best Practices

  1. ◇

    Cache Management: By default, translations are cached. You can disable caching for specific requests by setting cache: false in the translate parameters.

  2. ◇

    Error Handling: Always implement proper error handling in your application to gracefully handle API errors.

  3. ◇

    API Key Security: Never expose your API key in client-side code. Always keep it secure on your server.

  4. ◇

    Format Selection: Choose the appropriate format for your content type to ensure accurate translations.

Examples

Translating JSON Content

typescript
const babely = new Babely({
  apiKey: process.env.BABELY_API_KEY,
});

const jsonContent = {
  greeting: "Hello",
  farewell: "Goodbye"
};

const translation = await babely.translate({
  projectId: 'your_project_id',
  sourceLocale: 'en',
  targetLocale: 'fr',
  sourceText: JSON.stringify(jsonContent),
  format: 'json'
});

const translatedJson = JSON.parse(translation.translatedText);

Translating Markdown Content

typescript
const babely = new Babely({
  apiKey: process.env.BABELY_API_KEY,
});

const markdownContent = "# Welcome\n\nThis is a **markdown** document.";

const translation = await babely.translate({
  projectId: 'your_project_id',
  sourceLocale: 'en',
  targetLocale: 'de',
  sourceText: markdownContent,
  format: 'md'
});

console.log(translation.translatedText);
OverridesAPI