SDKs overview

LibreTranslate offers client libraries, commonly referred to as Software Development Kits (SDKs), to streamline the integration of its machine translation capabilities into various applications. These SDKs are designed to abstract the complexities of direct HTTP API calls, providing developers with idiomatic interfaces for interacting with the LibreTranslate API using their preferred programming languages. The availability of both official and community-maintained libraries aims to reduce development effort and accelerate the implementation of translation features, whether using the hosted service or a self-hosted LibreTranslate instance.

The core functionality exposed through these SDKs typically includes methods for translating text, detecting language, and retrieving a list of supported languages. Developers can choose between using these libraries or making direct HTTP requests to the LibreTranslate REST API endpoints, depending on their project requirements and existing infrastructure. While official SDKs are directly supported by the LibreTranslate project, community libraries extend support to additional languages and frameworks, reflecting the open-source nature of the platform.

Official SDKs by language

LibreTranslate maintains official SDKs for key programming languages to ensure reliable and up-to-date integration with its API. These libraries are typically the first choice for developers due to their direct support from the project maintainers and alignment with the latest API versions.

Language Package Name Install Command Maturity
Python libretranslate pip install libretranslate Stable
JavaScript @libretranslate/node npm install @libretranslate/node Stable
PHP libretranslate/libretranslate-php composer require libretranslate/libretranslate-php Stable

These official libraries provide a structured way to access LibreTranslate's features, including:

  • Text Translation: Sending source text and specifying target/source languages.
  • Language Detection: Identifying the language of a given text input.
  • Supported Languages: Fetching a list of all languages the API can translate between.

Developers are encouraged to consult the official LibreTranslate documentation for the most current information regarding SDK versions, usage guidelines, and any breaking changes.

Installation

Installation of LibreTranslate SDKs typically follows the standard package management practices for each respective programming language. The following sections provide common installation methods for the officially supported libraries.

Python

The Python SDK can be installed using pip, Python's package installer. This command adds the libretranslate package to your project's dependencies.

pip install libretranslate

JavaScript (Node.js)

For Node.js environments, the JavaScript SDK is available via npm, the Node.js package manager.

npm install @libretranslate/node

PHP

PHP projects using Composer can install the LibreTranslate PHP library by adding it as a dependency.

composer require libretranslate/libretranslate-php

Quickstart example

The following quickstart examples demonstrate basic text translation using the official SDKs. These snippets illustrate how to initialize the client and perform a translation operation. Replace YOUR_API_KEY with your actual LibreTranslate API key if you are using the hosted service, or adjust the base_url if self-hosting.

Python Quickstart

This Python example translates a sentence from English to Spanish.

import libretranslate_py as lt

# Initialize the client (replace with your LibreTranslate instance URL if self-hosting)
# For the hosted service, you might need an API key:
# client = lt.Client("https://translate.libretranslate.com", api_key="YOUR_API_KEY")
client = lt.Client("https://translate.libretranslate.com")

text_to_translate = "Hello, world!"
source_language = "en"
target_language = "es"

translated_text = client.translate(text_to_translate, source_language, target_language)
print(f"Original: {text_to_translate}")
print(f"Translated: {translated_text}")

# Example of language detection
detected_language = client.detect("Hola mundo")
print(f"Detected language for 'Hola mundo': {detected_language}")

JavaScript (Node.js) Quickstart

This Node.js example performs a similar English to Spanish translation.

const LibreTranslate = require('@libretranslate/node');

// Initialize the client (replace with your LibreTranslate instance URL if self-hosting)
// For the hosted service, you might need an API key:
// const lt = new LibreTranslate('https://translate.libretranslate.com', 'YOUR_API_KEY');
const lt = new LibreTranslate('https://translate.libretranslate.com');

async function translateText() {
  const textToTranslate = "How are you?";
  const sourceLanguage = "en";
  const targetLanguage = "fr";

  try {
    const translatedText = await lt.translate(textToTranslate, sourceLanguage, targetLanguage);
    console.log(`Original: ${textToTranslate}`);
    console.log(`Translated: ${translatedText}`);

    // Example of getting supported languages
    const languages = await lt.languages();
    console.log("Supported languages:", languages.map(lang => lang.name).join(', '));
  } catch (error) {
    console.error("Translation error:", error);
  }
}

translateText();

PHP Quickstart

The PHP quickstart demonstrates translating text using the installed PHP library.

<?php
require 'vendor/autoload.php';

use LibreTranslate\LibreTranslate;

// Initialize the client (replace with your LibreTranslate instance URL if self-hosting)
// For the hosted service, you might need an API key:
// $lt = new LibreTranslate('https://translate.libretranslate.com', 'YOUR_API_KEY');
$lt = new LibreTranslate('https://translate.libretranslate.com');

$textToTranslate = "Thank you very much.";
$sourceLanguage = "en";
$targetLanguage = "de";

try {
    $translatedText = $lt->translate($textToTranslate, $sourceLanguage, $targetLanguage);
    echo "Original: " . $textToTranslate . "\n";
    echo "Translated: " . $translatedText . "\n";

    // Example of language detection
    $detectedLanguage = $lt->detect('Ich bin ein Berliner');
    echo "Detected language for 'Ich bin ein Berliner': " . json_encode($detectedLanguage) . "\n";
} catch (Exception $e) {
    echo "Translation error: " . $e->getMessage() . "\n";
}
?>

Community libraries

Beyond the officially supported SDKs, the open-source nature of LibreTranslate has fostered the development of several community-contributed libraries. These libraries extend support to additional programming languages and frameworks, catering to a broader range of development environments. While not officially maintained by the LibreTranslate project, they often provide valuable alternatives for developers whose tech stacks are not covered by the official offerings.

Examples of community-developed client libraries include:

  • Go: A Go client library allows integration into Go applications. Developers can typically find these on package repositories like Go Modules.
  • Rust: For Rust developers, there are community crates available that provide an interface to the LibreTranslate API, often discoverable on crates.io.
  • Dart/Flutter: Libraries for Dart and Flutter facilitate integration into cross-platform mobile and web applications, commonly found on pub.dev.

When using community libraries, it is recommended to review their documentation, recent activity, and community support to ensure compatibility and ongoing maintenance. The LibreTranslate documentation or its GitHub repository often links to or mentions notable community contributions.

These community libraries are developed independently and may vary in their feature sets, API parity with the latest LibreTranslate API, and stability. Developers should evaluate these options based on their specific project needs and the library's level of active maintenance. For instance, the general principles of API design and best practices for creating RESTful services are broadly applicable across languages, as outlined by organizations such as the World Wide Web Consortium (W3C), which can help in evaluating the quality of any client library.