arml v0.0.12

Arml Translator Library Documentation

The Translator library provides a powerful, flexible, and easy-to-use interface for integrating translation functionality into your application. It supports translating text, batch translations, and language detection through a robust API.

Installation

To use the Translator library in your project, install it via npm:

npm install arml

Quick Start

Here’s how to get started with the Translator library:

Import and Initialize the Translator

import {Translator} from "arml";

const translator = new Translator("your_api_key_here");

export default translator;

Replace "your_api_key_here" with your actual API key.

Example: Translating Text

const translatedText = await translator.translate("Hello, world!", { target: "es" });
console.log(translatedText?.translated_text); // Output: "¡Hola, mundo!"

Features

1. Translate Text

Translate a single text to a target language with ease.

Method: translate

translate(
  text: string,
  { source = "auto", target = "en" }: TranslateOptions
): Promise<TranslationResponse | null>

• Parameters:
  • text (string): The text to translate.
  • source (optional): The source language (default: auto-detected).
  • target (string): The target language.
• Returns: A promise resolving to the following structure:

interface TranslationResponse {
  original_text: string;
  source_language: string;
  target_language: string;
  translated_text: string;
  pronunciation: string | null;
  passing_time: number;
}

Example

const response = await translator.translate("Bonjour", { source: "fr", target: "en" });
console.log(response?.translated_text); // Output: "Hello"
console.log(response); // Detailed response object

2. Batch Translate

Translate multiple texts in a single request.

Method: batchTranslate

batchTranslate(
  texts: string[],
  { source = "auto", target = "en" }: TranslateOptions
): Promise<BatchTranslationResponse | null>

• Parameters:
  • texts (string[]): Array of texts to translate.
  • source (optional): The source language (default: auto-detected).
  • target (string): The target language.
• Returns: A promise resolving to the following structure:

interface BatchTranslationResponse {
  translations: BatchTranslation[];
  passing_time: number;
}

interface BatchTranslation {
  id: number;
  uuid: string;
  original_text: string;
  source_language: string;
  target_language: string;
  translated_text: string;
}

Example

const batchResponse = await translator.batchTranslate([
  "Hola",
  "Bonjour",
  "Hallo",
], { target: "en" });

console.log(batchResponse?.translations); // Detailed translation objects

3. Detect Language

Identify the language of a given text.

Method: detect

detect(text: string): Promise<DetectTranslationResponse | null>

• Parameters:
  • text (string): The text whose language needs to be detected.
• Returns: A promise resolving to the following structure:

interface DetectTranslationResponse {
  text: string;
  detected_language: string;
  confidence: string;
  passing_time: number;
}

Example

const detectedLang = await translator.detect("Hola");
console.log(detectedLang?.detected_language); // Output: "es"
console.log(detectedLang); // Detailed detection object

4. Quick Translate

Perform a one-off translation without creating a Translator instance.

Method: quick

static quick({
  text,
  apiKey,
  options,
}: {
  text: string;
  apiKey: string;
  options: TranslateOptions;
}): Promise<string | undefined>

• Parameters:
  • text (string): The text to translate.
  • apiKey (string): The API key for the translation service.
  • options (TranslateOptions): Source and target language options.
• Returns: The translated text or undefined if an error occurs.

Example

const quickTranslation = await Translator.quick({
  text: "Bonjour",
  apiKey: "your_api_key_here",
  options: { target: "en" },
});

console.log(quickTranslation); // Output: "Hello"

API Reference

Constructor

new Translator(apiKey: string)

• Parameter:
  • apiKey (string): Your API key required to access the translation service.
• Throws: An error if no API key is provided.

Types

The library provides several types to ensure proper usage:

• TranslationResponse: Represents the response for a single translation.
• BatchTranslationResponse: Represents the response for batch translations.
• DetectTranslationResponse: Represents the response for language detection.
• TranslateOptions: Configuration options for translation requests.

Example: Importing Types

import type {
  BatchTranslationResponse,
  DetectTranslationResponse,
  TranslationResponse,
  TranslateOptions,
} from "@/types";

Error Handling

The library gracefully handles errors, logging them to the console. Ensure that you provide valid API keys and parameters to avoid issues.

Resources

• Documentation
• API Documentation
• Platform