README

PHP Interface to the open source LibreTranslate project

Install

Composer (recommended)

composer require jefs42/libretranslate

require('vendor/autoload.php');

use Jefs42\LibreTranslate;

$translator = new LibreTranslate();

Manual

Download the LibreTranslate.php file from src/ directory and place somewhere in you project.

Include the file in your project:

require_once("path/to/LibreTranslate.php");

use Jefs42\LibreTranslate;

$translator = new LibreTranslate();

Usage

By default, this class will try to connect to and use a local installation of the LibreTranslate server at http://localhost:5000

Pass host and optionally port, source and/or target parameters to override defaults.

// use locally installed LibreTranslate server on port 5000 with default language settings
$translator = new LibreTranslate();

// specify server with alternate port
$translator = new LibreTranslate("https://libretranslate", 5042);

// use localhost, default port, but override default languages used in translations
$translator = new LibreTranslate(null, null, 'de', 'it');

LibreTranslate Mirros

Set API Key

Depending on the server settings, you may need to provide a valid API key to make translation request.

$translator->setApiKey('xxxxx-xxxxx-xxxxx');

Set Default Languages

The default source and target languages are set by the server. You may override these settings when constructing the class, or as needed:

// Set to translate from English to Swedish
$translator->setLanguages('en', 'sv');

// change only one - source or target
$translator->setSource('es');

$translator->setTarget('ru');

Each translation function also supports specifying the languages to use when calling the function.

Detect Language

LibreTranslate will attempt to determine the language of the string passed to it.

$lang = $translator->detect("mi nombre es jefs42");
// expected result: $lang = 'es'

Translate Text

Translate a string of text, or an array of multiple texts. A server may or may not have a character limit set. For larger texts see Translate File.

// translate text using current default source/target languages
$translatedText = $translator->translate("My name is jefs42");

// specifally request languages to use in translation.
// eg. from English to German
$translatedText = $translator->translate("My name is jefs42", "en", "de");

// translate multiple texts in one call
// returns array of translated texts
$translatedText = $translator->translate(["My name is jefs42", "Where is the bathroom?"]);

Translate File

Translate a file of text.

Check $translator->Settings(), current supported formats appear to be - .txt, .odt, .odp, .docx and .pptx

// translate file using current default source/target languages
$translatedText = $translator->translateFile("/full/path/to/file.txt");

// translate file with specific source/target languages
// eg. from English to Italian
$translatedText = $translator->translateFile("/full/path/to/file.txt", "en", "it");

Translation server may have max size limits on post/files size.
Could pass $_SERVER['FILES']['formfield']['tmp_name'] if using for a web form.

Suggest

Submit a suggested translation to the server.

// Submit suggestion using current source/target language
$translator->suggest('My name is jefs42', 'Mi nombre es jefs42');

// Specify languages for suggestion
$translator->suggest('My name is jefs42', 'Mi chiamo jefs42', 'en', 'it');

Sugesstions must be enabled on the LibreTranslate server.

Get Available Languages

Get the list of languages available on the current server.

$languages = $translator->Languages();
/*
Returns array of language codes/names:
[en] => 'English',
[it] => 'Italian',
...
*/

Check Server Settings

Get settings current server is running with.

$settings = $translator->Settings();
/*
Returns array of settings and their current values:
[api_keys] => 1,
[keyRequired] => ,
[char_limit] => -1,
...
*/

See LibreTranslate Arguments for server settings.

LTManage

If you are running a locally hosted LibreTranslate server, you may have access to ltmanage. This allows you to view current keys and their request limits, as well as create new keys and delete current keys.

See LibreTranslate Manage Keys for details.

If ltmanage is found in the local path then the following additonal functions will be available for use:

listKeys

Will return an array of current keys and their request limits.

$keys = $translator->listKeys();
/*
Returns array of current keys and limits:
[
    'key1' => '500',
    'key2' => '50',
    ...
]
*/

addKey

Create a new key for local server with optional request limit.

// create a new key limited to server defaults
$key = $translator->addKey();

// create a new key with a specific request limit (higher or lower than server default)
$key = $translator->addKey(400); // limit to 400 requests per minute

/*
Returns string of new key:
"xxxxx-xxxx-xxxx"
*/

removeKey

Delete an existing key from the available keys.

try {
    $translator->removeKey("xxxxx-xxxxx-xxxxx");
} catch (Exception $e) {
    // key doesn't exist
}
/*
Returns true on deletion
*/

jefs42 / libretranslate

Maintainers

Details