arml/README.md

Enjoy unlimited and free translation with our API.

# 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:

```bash
npm install arml
```

---


## Quick Start

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

### Import and Initialize the Translator

```javascript
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

```javascript
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`

```typescript
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:

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

#### Example

```javascript
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`

```typescript
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:

```typescript
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

```javascript
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`

```typescript
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:

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

#### Example

```javascript
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`

```typescript
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

```javascript
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

```javascript
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](https://docs.trymagic.xyz/arml/translate/index.html)
- [API Documentation](https://api.translate.arml.trymagic.xyz/docs)
- [Platform](https://arml.trymagic.xyz)

---


<!-- For support or to report issues, contact [support@arml-translate.example](mailto:support@arml-translate.example). -->